Modern Concurrency in Java

Chapter 5. Scoped Values

He who does not place things in their proper place has committed injustice.

Ali ibn Abi Talib (may God be pleased with him)

In this chapter, we will explore ScopedValue, a powerful addition to Java that was finalized in JDK 25. It provides a structured way to bind values to a specific scope while remaining accessible and consistent with the context. Unlike traditional Thread​Local variables, which can be cumbersome and prone to memory leaks, this offers a cleaner and more efficient approach when dealing with multithreaded applications. In this chapter, we will examine why ScopedValue is a better replacement for Thread​Local and its API and then walk through practical use cases.

Let’s begin.

The Burden of Passing Context

There are often scenarios in which we need to share data among various parts of the code where simply using method arguments isn’t feasible. This is especially common when our application depends on a framework. To illustrate the idea, let’s consider an example.

Imagine a job-scheduling framework in which user code registers tasks that the framework will execute. Whenever the framework runs a job, it creates a JobContext object containing metadata such as the job’s name, priority, and scheduling constraints. This context is essential for framework operations but is largely irrelevant to user code.

The following example demonstrates a typical job-scheduling framework that suffers from what we call the “parameter passing problem”:

import ...