Scoped Values

## Background you need first **ThreadLocal<T>** is a long-standing Java class: a variable whose value is independent per thread. `tl.set(x)` stores x for the current thread; `tl.get()` reads it back; `tl.remove()` clears it. It's commonly used to carry implicit context (current user, request id, transaction) down a call chain without parameters. **Virtual threads** (Java 21) are extremely lightweight threads — you can have millions of them, typically one per task/request, created and discarded constantly. **Platform threads** are the old heavyweight OS threads, usually pooled and reused. **ScopedValue** is the newer alternative (finalized Java 25) for the same implicit-context need. ## Weakness 1 — Unbounded, mutable lifetime (the leak / staleness trap) A ThreadLocal value persists on the thread until someone calls `remove()`. There is no automatic end-of-use. Two failure modes follow: - **Memory leak**: on a *pooled* platform thread that lives for hours, a value (and whatever it references) stays reachable forever unless explicitly removed. People forget, especially on exception paths. - **Stale/cross-task bleed**: a thread is reused for a new task while still holding the previous task's value; the new task reads someone else's context. The correct fix is a `try { tl.set(x); ... } finally { tl.remove(); }` discipline — boilerplate that is easy to get wrong. ScopedValue removes the obligation entirely: a binding exists *only* for the dynamic extent of `where(KEY, v).run(task)` and is torn down automatically when that call returns, normally or exceptionally. You **cannot** forget to clean up, because there is nothing to clean up manually. ## Weakness 2 — Mutability (action at a distance) With ThreadLocal, any code anywhere can call `set()` and change the value other code will later read. That makes reasoning hard: a value read in method A might have been mutated by some unrelated deep call. ScopedValue is **immutable** — there is no `set()`. If inner code needs a different value, it opens a *nested* binding (`where` again) whose effect is confined to that inner scope and is undone on exit. The flow of data is therefore always lexically visible at the binding site and strictly stack-structured. ## Weakness 3 — Cost and inheritance at virtual-thread scale Each platform/virtual thread that uses a ThreadLocal gets its own entry in a per-thread map. With **millions** of virtual threads this per-thread mutable storage is a real cost in allocation and GC. Worse, **InheritableThreadLocal** *copies* values to each child thread at creation — multiply that by a fan-out of subtasks and it's expensive. A ScopedValue binding is a small immutable record on the binding stack. Subtasks don't get a *copy*; they share the binding **by reference** because the value can never change. Combined with **structured concurrency** (where a parent forks subtasks via a `StructuredTaskScope` and the subtasks run within the parent's dynamic extent), forked subtasks **inherit** the parent's scoped-value bindings for free — no per-thread copy, no cleanup. That is exactly the property you want when spawning many short-lived virtual threads. ## When ThreadLocal is still needed ScopedValue targets the *read-mostly, scoped, downward-flowing context* case. If you genuinely need **mutable** per-thread state that a method updates and a sibling later reads back *up* the call stack, ThreadLocal still fits — but that pattern is rarer and often a smell. For the common implicit-context case, prefer ScopedValue. ## One-line takeaways - Immutable vs mutable → easier reasoning. - Bounded auto-cleanup vs manual remove() → no leaks, no stale bleed. - Shared-by-reference bindings + structured-concurrency inheritance vs per-thread copies → cheap at millions of threads.