Skip to content
Tutorials Center
My learning

Topics

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.

Java
static final ScopedValue<String> USER = ScopedValue.newInstance();

ScopedValue.where(USER, "ann").run(() -> {
    System.out.println(USER.get());     // ann
});

Try it

Java Bind, read and rebind

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.

Java Several bindings and threads

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

Java
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 no remove(); the binding ends automatically when run/call returns, even by an exception. That removes the classic ThreadLocal leak 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.
  • null is a valid value, but isBound() 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 (where inside run) 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.