When do you use .run() versus .call() on a ScopedValue binding, and what are common usage pitfalls?

## The two terminators A binding expression is `ScopedValue.where(KEY, value)` — but that on its own does nothing; you must run a task within it. There are two ways: - **`.run(Runnable op)`** — for a task that returns **no value** and throws only **unchecked** exceptions (RuntimeExceptions/Errors). It returns `void`. - **`.call(CallableOp<T, X> op)`** — for a task that **returns a value** of type `T` and/or may throw a **checked** exception `X`. `.call` returns the task's result and propagates its checked exception, so the caller must handle/declare it. Why two? Java's lambda typing distinguishes a `Runnable` (no return, no checked exceptions) from a callable-style functional interface (returns a value, may throw checked). Picking the right one is just matching your task's shape: *need a result or a checked throw → `.call`; pure side effect → `.run`.* ```java // run: side effect, void, unchecked only ScopedValue.where(USER, alice).run(() -> auditLogin()); // call: returns a value and may throw a checked exception Report r = ScopedValue.where(USER, alice).call(() -> buildReport()); // throws IOException ``` You can chain multiple bindings before the terminator: `ScopedValue.where(A, x).where(B, y).call(() -> ...)`. ## Pitfall 1 — reading outside the scope `KEY.get()` only works while inside the binding. Outside it (before binding, after it returns, or on an unrelated thread) it throws **`NoSuchElementException`**. Defensive reads: - `KEY.isBound()` → boolean check first. - `KEY.orElse(fallback)` → value or a default. - `KEY.orElseThrow(supplier)` → value or your own exception. ## Pitfall 2 — expecting persistence The binding lives **exactly** for the `run`/`call` invocation. After it returns (normally or by exception), the value is unbound again. People sometimes bind a value, return from the method, and later expect `get()` to still work — it won't. ## Pitfall 3 — escaping the scope If inside the scope you start a *bare* thread, schedule an async callback, or store a `() -> KEY.get()` lambda that runs *later*, and that work executes **after** the scope has closed, the read fails (unbound). The value is tied to the *dynamic extent*, not captured by closures that outlive it. The correct approach is to fork subtasks via **structured concurrency** so they run *within* the scope (then they inherit the binding), or to read the value *inside* the scope and pass the plain value forward. ## Pitfall 4 — looking for set() There is no `set()`/`update()`. To use a different value in a sub-region, open a nested `where(...)` (covered in the immutability question). Searching for a mutator is the most common newcomer mistake. ## Pitfall 5 — binding mutable state The *binding* (which object is bound) is immutable, but if you bind a mutable object (a list, a map, a builder) callees can still mutate its **contents**. That quietly brings back the action-at-a-distance you adopted ScopedValue to avoid. Prefer binding immutable values; if you must share mutable state, do it deliberately and document it. ## The clean usage pattern ```text 1. Declare: static final ScopedValue<T> KEY = ScopedValue.newInstance(); 2. Bind at the boundary where context is known (request entry, etc.). 3. Do ALL work needing the value inside run()/call(). 4. Read via get() (or isBound/orElse) only within that extent. 5. Don't let the value escape; if you fork, use structured concurrency. ``` Follow that and the value behaves as a safe, self-cleaning, scope-confined constant.