Why ScopedValue Is the Future Replacement for ThreadLocal in Java

Introduction

ScopedValue is a preview feature introduced in Java 20 and standardized in Java 21, designed to address the shortcomings of ThreadLocal for thread‑local data transmission.

ThreadLocal Pain Points

Common problems with ThreadLocal include memory leaks, data pollution, lack of inheritance, and performance overhead.

Memory‑leak issue

When a thread is reused in a pool, values stored in ThreadLocal may never be garbage‑collected.

Typical problematic code

/**
 * ThreadLocal typical problem demo
 */
public class ThreadLocalProblems {
    private static final ThreadLocal<UserContext> userContext = new ThreadLocal<>();
    private static final ThreadLocal<Connection> connectionHolder = new ThreadLocal<>();
    // ... set, get, forget remove, data contamination, performance test ...
}

Complex lifecycle management : manual set/remove is error‑prone.

Memory‑leak risk : reused threads keep stale values.

Poor inheritance : child threads cannot automatically see parent values.

Performance cost : ThreadLocalMap hash operations add overhead.

InheritableThreadLocal mitigates inheritance but introduces extra complexity and worse performance.

ScopedValue: New‑Generation Thread‑Local Variable

ScopedValue solves the above issues by providing automatic lifecycle management, safe inheritance, and better performance, especially with virtual threads.

Core design ideas

ScopedValue binds a value to a logical execution scope rather than a physical thread.

Basic usage

/**
 * ScopedValue basic usage demo
 */
public class ScopedValueBasics {
    private static final ScopedValue<UserContext> USER_CONTEXT = ScopedValue.newInstance();
    private static final ScopedValue<Connection> DB_CONNECTION = ScopedValue.newInstance();
    private static final ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();
    public void basicUsage() {
        UserContext user = new UserContext("user_123");
        ScopedValue.runWhere(USER_CONTEXT, user, () -> {
            System.out.println("Current user: " + USER_CONTEXT.get().getUserId());
            ScopedValue.runWhere(REQUEST_ID, "req_456", () -> {
                System.out.println("Request ID: " + REQUEST_ID.get());
                System.out.println("User: " + USER_CONTEXT.get().getUserId());
            });
        });
    }
    // ... callWhere with return value, multiple ScopedValues, exception handling ...
}

ScopedValue vs ThreadLocal: Full Comparison

ScopedValue provides automatic cleanup, safe inheritance, and better performance compared with ThreadLocal.

Memory management comparison

Images illustrate how ScopedValue avoids the stale‑value problem of ThreadLocal.

Code comparison

public class ThreadLocalVsScopedValue {
    private static final ThreadLocal<UserContext> TL_USER_CONTEXT = new ThreadLocal<>();
    private static final ThreadLocal<Connection> TL_CONNECTION = new ThreadLocal<>();
    private static final ScopedValue<UserContext> SV_USER_CONTEXT = ScopedValue.newInstance();
    private static final ScopedValue<Connection> SV_CONNECTION = ScopedValue.newInstance();
    public void processRequestThreadLocal(HttpServletRequest request) {
        // set, try‑finally remove, manual cleanup
    }
    public void processRequestScopedValue(HttpServletRequest request) {
        UserContext userContext = new UserContext(request.getHeader("X-User-Id"));
        try (Connection conn = dataSource.getConnection()) {
            ScopedValue.runWhere(
                ScopedValue.where(SV_USER_CONTEXT, userContext)
                    .where(SV_CONNECTION, conn),
                () -> processBusinessLogic());
        }
    }
}

Performance comparison test

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MICROSECONDS)
@State(Scope.Thread)
public class PerformanceComparison {
    private static final ThreadLocal<String> THREAD_LOCAL = new ThreadLocal<>();
    private static final ScopedValue<String> SCOPED_VALUE = ScopedValue.newInstance();
    private static final int ITERATIONS = 100_000;
    @Benchmark
    public void threadLocalPerformance() {
        for (int i = 0; i < ITERATIONS; i++) {
            THREAD_LOCAL.set("value_" + i);
            String v = THREAD_LOCAL.get();
            THREAD_LOCAL.remove();
        }
    }
    @Benchmark
    public void scopedValuePerformance() {
        for (int i = 0; i < ITERATIONS; i++) {
            ScopedValue.runWhere(SCOPED_VALUE, "value_" + i, () -> {
                String v = SCOPED_VALUE.get();
            });
        }
    }
}

Advanced Features

Structured concurrency support

public class StructuredConcurrencyExample {
    private static final ScopedValue<UserContext> USER_CONTEXT = ScopedValue.newInstance();
    private static final ScopedValue<RequestInfo> REQUEST_INFO = ScopedValue.newInstance();
    public void structuredConcurrencyWithScopedValue() throws Exception {
        UserContext user = new UserContext("structured_user");
        RequestInfo request = new RequestInfo("req_123", System.currentTimeMillis());
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            ScopedValue.runWhere(
                ScopedValue.where(USER_CONTEXT, user).where(REQUEST_INFO, request),
                () -> {
                    Future<String> userTask = scope.fork(this::fetchUserData);
                    Future<String> orderTask = scope.fork(this::fetchOrderData);
                    Future<String> paymentTask = scope.fork(this::fetchPaymentData);
                    scope.join();
                    scope.throwIfFailed();
                    System.out.println("Aggregated: " + userTask.resultNow() + ", " + orderTask.resultNow() + ", " + paymentTask.resultNow());
                });
        }
    }
    // fetchUserData, fetchOrderData, fetchPaymentData omitted for brevity
}

Inheritance and nested scopes

public class ScopedValueInheritance {
    private static final ScopedValue<String> PARENT_VALUE = ScopedValue.newInstance();
    private static final ScopedValue<String> CHILD_VALUE = ScopedValue.newInstance();
    public void nestedScopes() {
        ScopedValue.runWhere(PARENT_VALUE, "parent_value", () -> {
            System.out.println("Outer: " + PARENT_VALUE.get());
            ScopedValue.runWhere(CHILD_VALUE, "child_value", () -> {
                System.out.println("Inner parent: " + PARENT_VALUE.get());
                System.out.println("Inner child: " + CHILD_VALUE.get());
                ScopedValue.runWhere(PARENT_VALUE, "shadowed_parent", () -> {
                    System.out.println("Shadowed parent: " + PARENT_VALUE.get());
                    System.out.println("Shadowed child: " + CHILD_VALUE.get());
                });
                System.out.println("Restored parent: " + PARENT_VALUE.get());
            });
            try { System.out.println(CHILD_VALUE.get()); } catch (Exception e) { System.out.println("Child out of scope: " + e.getMessage()); }
        });
    }
}

Error handling and debugging

public class ScopedValueErrorHandling {
    private static final ScopedValue<String> MAIN_VALUE = ScopedValue.newInstance();
    private static final ScopedValue<Integer> COUNT_VALUE = ScopedValue.newInstance();
    public void exceptionHandling() {
        try {
            ScopedValue.runWhere(MAIN_VALUE, "test_value", this::processWithError);
        } catch (RuntimeException e) {
            System.out.println("Caught: " + e.getMessage());
        }
        try { String v = MAIN_VALUE.get(); System.out.println(v); } catch (Exception e) { System.out.println("Value cleared: " + e.getMessage()); }
    }
    private void processWithError() { throw new RuntimeException("Business error"); }
    public void debugInformation() {
        ScopedValue.runWhere(ScopedValue.where(MAIN_VALUE, "debug_value").where(COUNT_VALUE, 42), () -> {
            System.out.println("Scope bindings:");
            System.out.println("MAIN_VALUE: " + MAIN_VALUE.get());
            System.out.println("COUNT_VALUE: " + COUNT_VALUE.get());
            debugComplexScenario();
        });
    }
    private void debugComplexScenario() {
        ScopedValue.runWhere(COUNT_VALUE, COUNT_VALUE.get() + 1, () -> {
            System.out.println("Nested debug COUNT_VALUE: " + COUNT_VALUE.get());
        });
    }
}

Real‑World Case: Web Application User Context

A practical example shows how ScopedValue can replace ThreadLocal for managing user context, request info, DB connections, and trace IDs in a Spring‑based web stack.

Define ScopedValues

public class WebScopedValues {
    public static final ScopedValue<UserContext> USER_CONTEXT = ScopedValue.newInstance();
    public static final ScopedValue<RequestInfo> REQUEST_INFO = ScopedValue.newInstance();
    public static final ScopedValue<Connection> DB_CONNECTION = ScopedValue.newInstance();
    public static final ScopedValue<String> TRACE_ID = ScopedValue.newInstance();
}
// UserContext and RequestInfo classes omitted for brevity

Filter implementation

@Component
@Slf4j
public class AuthenticationFilter implements Filter {
    @Autowired private UserService userService;
    @Autowired private JwtTokenProvider tokenProvider;
    @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        String requestId = generateRequestId();
        RequestInfo requestInfo = extractRequestInfo(httpRequest, requestId);
        UserContext userContext = authenticateUser(httpRequest);
        ScopedValue.runWhere(
            ScopedValue.where(WebScopedValues.REQUEST_INFO, requestInfo)
                .where(WebScopedValues.USER_CONTEXT, userContext)
                .where(WebScopedValues.TRACE_ID, requestId),
            () -> {
                try { chain.doFilter(request, response); }
                catch (Exception e) { log.error("Filter error", e); throw new RuntimeException(e); }
            });
        log.info("Request completed: {}", requestId);
    }
    // generateRequestId, extractRequestInfo, authenticateUser omitted for brevity
}

Service and controller usage

@Service
@Slf4j
@Transactional
public class UserService {
    @Autowired private UserRepository userRepository;
    @Autowired private OrderService orderService;
    public UserProfile getCurrentUserProfile() {
        UserContext uc = WebScopedValues.USER_CONTEXT.get();
        String trace = WebScopedValues.TRACE_ID.get();
        log.info("[{}] Fetch profile for {}", trace, uc.getUserId());
        User user = userRepository.findById(uc.getUserId())
            .orElseThrow(() -> new UserNotFoundException("User not found: " + uc.getUserId()));
        return UserProfile.builder()
            .userId(user.getId())
            .username(user.getUsername())
            .email(user.getEmail())
            .roles(uc.getRoles())
            .locale(uc.getLocale())
            .lastLogin(user.getLastLoginTime())
            .build();
    }
    // updateUserProfile, getUserOrders omitted for brevity
}
@RestController
@RequestMapping("/api/users")
@Slf4j
public class UserController {
    @Autowired private UserService userService;
    @GetMapping("/profile")
    public ResponseEntity<UserProfile> getCurrentUserProfile() {
        return ResponseEntity.ok(userService.getCurrentUserProfile());
    }
    // other endpoints omitted for brevity
}

Migration Guide: From ThreadLocal to ScopedValue

Migration steps

public class MigrationGuide {
    // Old ThreadLocal definitions
    private static final ThreadLocal<UserContext> TL_USER = new ThreadLocal<>();
    private static final ThreadLocal<Connection> TL_CONN = new ThreadLocal<>();
    private static final ThreadLocal<String> TL_TRACE = new ThreadLocal<>();
    // New ScopedValue definitions
    private static final ScopedValue<UserContext> SV_USER = ScopedValue.newInstance();
    private static final ScopedValue<Connection> SV_CONN = ScopedValue.newInstance();
    private static final ScopedValue<String> SV_TRACE = ScopedValue.newInstance();
    public void beforeMigration() {
        TL_USER.set(new UserContext("user_old"));
        TL_TRACE.set("trace_old");
        try (Connection conn = createConnection()) {
            TL_CONN.set(conn);
            processBusinessOld();
        } finally {
            TL_USER.remove();
            TL_TRACE.remove();
            TL_CONN.remove();
        }
    }
    public void afterMigration() {
        UserContext user = new UserContext("user_new");
        String trace = "trace_new";
        try (Connection conn = createConnection()) {
            ScopedValue.runWhere(
                ScopedValue.where(SV_USER, user)
                    .where(SV_TRACE, trace)
                    .where(SV_CONN, conn),
                this::processBusinessNew);
        }
    }
    // processBusinessOld / processBusinessNew illustrate null‑checks vs automatic safety
}

Compatibility handling

public class CompatibilityLayer {
    private static final ScopedValue<UserContext> SV_USER = ScopedValue.newInstance();
    private static final ThreadLocal<UserContext> TL_USER = new ThreadLocal<>();
    public void bridgePattern() {
        UserContext user = new UserContext("bridge_user");
        ScopedValue.runWhere(SV_USER, user, () -> {
            TL_USER.set(user);
            try { processMixedBusiness(); } finally { TL_USER.remove(); }
        });
    }
    private void processMixedBusiness() {
        UserContext sv = SV_USER.get();
        UserContext tl = TL_USER.get();
        System.out.println("ScopedValue user: " + sv.getUserId());
        System.out.println("ThreadLocal user: " + tl.getUserId());
        assert sv == tl;
    }
    // Gradual migration strategy description omitted for brevity
}

Conclusion

ScopedValue brings memory safety, automatic lifecycle management, better performance with virtual threads, and seamless inheritance, making it a superior alternative to ThreadLocal for modern Java concurrency.

Memory safety : automatic cleanup eliminates leaks.

Ease of use : structured binding removes manual remove calls.

Performance : optimized for virtual threads.

Concurrency friendliness : works naturally with structured concurrency.

ThreadLocal vs ScopedValue selection rhyme New projects – use ScopedValue directly. Legacy code – migrate gradually, start with new modules. Performance‑critical – ScopedValue shines with virtual threads. Memory‑critical – ScopedValue avoids leaks. Team skill – ThreadLocal is familiar, but invest in learning ScopedValue.

For a visual recap: