Java Reference ยท Concurrency
Scoped values (ScopedValue)
Reference for java.lang.ScopedValue (final in Java 25): share immutable context with a call chain and its child threads, rebinding, and how it differs from ThreadLocal.
A ScopedValue<T> lets you bind a value for the duration of a piece of code and read it anywhere in the calls beneath it, without passing it as a parameter. When the code finishes, the binding disappears. The value is immutable inside the scope: nobody can set() it, and code can only rebind it for an inner scope.
It was designed as a safer, cheaper alternative to ThreadLocal for context like the current user, a request id or a transaction, especially with many virtual threads. ScopedValue became a final feature in Java 25 (JEP 506), after previews in 21 to 24, so it needs no flags.
static final ScopedValue<String> USER = ScopedValue.newInstance(); ScopedValue.where(USER, "ann").run(() -> { System.out.println(USER.get()); // ann });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public final class ScopedValue<T> { public static <T> ScopedValue<T> newInstance() public static <T> ScopedValue.Carrier where(ScopedValue<T> key, T value) public T get() public boolean isBound() public T orElse(T other) public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X } // ScopedValue.Carrier: where(...), run(Runnable), call(Callable), get(Supplier)
| Member | Description |
|---|---|
newInstance() |
Creates a new key. Keep it in a static final field; the key object, not its name, identifies the value. |
where(key, value) |
Starts a binding. Returns a Carrier that can add more where(...) bindings. |
Carrier.run(Runnable) |
Runs code with the bindings in effect. |
Carrier.call(Callable) |
Runs code and returns its result; checked exceptions propagate. |
Carrier.get(Supplier) |
Like call for a Supplier that cannot throw checked exceptions. |
get() |
Returns the bound value; throws NoSuchElementException if unbound. |
isBound() |
true if a binding is in effect for the current thread. |
orElse(other) / orElseThrow(...) |
Fallback or custom exception when unbound. |
Usage notes
- Immutable and scoped. There is no
set()and noremove(); the binding ends automatically whenrun/callreturns, even by an exception. That removes the classicThreadLocalleak in thread pools. - Not inherited by
new Thread. Plain threads do not see your bindings (see the second example). Structured concurrency scopes (a preview API in Java 25) copy bindings into the forked subtasks automatically. - Cheap with virtual threads: bindings are not copied per thread, so millions of threads cost nothing extra.
nullis a valid value, butisBound()still tells bound from unbound.- Use for read-only context (identity, locale, trace id). If code needs to mutate shared state, pass an object or use another mechanism; a bound mutable object defeats the point.
- Rebinding (
whereinsiderun) shadows the outer value only for the inner code, and the outer one returns afterwards. - Java versions: incubating in Java 20, preview in 21 to 24, final in 25. Code on 21 to 24 needs
--enable-preview.