Home / Concurrency / Scoped values
Concurrency advanced

Scoped values

Share data across call stacks safely without ThreadLocal pitfalls.

Code Comparison
✕ Java 8 
static final ThreadLocal<User> CURRENT =
    new ThreadLocal<>();
void handle(Request req) {
    CURRENT.set(authenticate(req));
    try { process(); }
    finally { CURRENT.remove(); }
}
✓ Java 25 
static final ScopedValue<User> CURRENT =
    ScopedValue.newInstance();
void handle(Request req) {
    ScopedValue.where(CURRENT,
        authenticate(req)
    ).run(this::process);
}
Why the modern way wins
🔒

Immutable

Callees can read but never modify the scoped value.

🧹

Auto cleanup

No manual remove() — value is scoped to the block.

⚡

Virtual-thread safe

Works efficiently with millions of virtual threads.

Old Approach
ThreadLocal
Modern Approach
ScopedValue
Since JDK
25
Difficulty
advanced
JDK Support
Scoped values
Available

Finalized in JDK 25 LTS (JEP 506, Sept 2025).

How it works

ScopedValue provides immutable, inheritable, scope-limited context. Unlike ThreadLocal, scoped values are automatically cleaned up, work with virtual threads, and can't be mutated by callees.

Related patterns

Concurrency beginner

Virtual threads

Java 8
Thread thread = new Thread(() -> {
    System.out.println("hello");
});
thread.start();
thread.join();
Java 21+
Thread.startVirtualThread(() -> {
    System.out.println("hello");
}).join();
Hover to see modern ➜
JDK 21+ →
Concurrency advanced

Structured concurrency

Java 8
ExecutorService exec =
    Executors.newFixedThreadPool(2);
Future<User> u = exec.submit(this::fetchUser);
Future<Order> o = exec.submit(this::fetchOrder);
try {
    return combine(u.get(), o.get());
} finally { exec.shutdown(); }
Java 25 (Preview)
try (var scope = new StructuredTaskScope
        .ShutdownOnFailure()) {
    var u = scope.fork(this::fetchUser);
    var o = scope.fork(this::fetchOrder);
    scope.join().throwIfFailed();
    return combine(u.get(), o.get());
}
Hover to see modern ➜
JDK 25+ →
Concurrency advanced

Stable values

Java 8
private volatile Logger logger;
Logger getLogger() {
    if (logger == null) {
        synchronized (this) {
            if (logger == null)
                logger = createLogger();
        }
    }
    return logger;
}
Java 25 (Preview)
private final StableValue<Logger> logger =
    StableValue.of(this::createLogger);

Logger getLogger() {
    return logger.get();
}
Hover to see modern ➜
JDK 25+ →
Share 𝕏 🦋 in ⬡