Understanding ThreadLocal, ScopedValue, and StructuredTaskScope in Java

ThreadLocal

ThreadLocal provides a way to store variables that are isolated to each thread. In Java each thread owns a ThreadLocalMap whose keys are weak references to the corresponding ThreadLocal objects. If a ThreadLocal value is not removed with remove() , it can cause serious memory leaks.

Basic Concept

Beyond isolation, ThreadLocal is often used to reuse objects such as database connections. However, because the map holds weak references, failing to call remove() after the value is no longer needed still leads to leaks.

Application Cases

In a typical Spring e‑commerce service, a ThreadLocal<ShoppingCart> can hold a cart per request. The example below shows a service that creates a cart on first access, stores it in the ThreadLocal, and clears it after checkout to avoid leaks.

@Service
public class ShoppingCartService {
    private ThreadLocal
cartHolder = new ThreadLocal<>();

    public ShoppingCart getCurrentCart() {
        ShoppingCart cart = cartHolder.get();
        if (cart == null) {
            cart = new ShoppingCart();
            cartHolder.set(cart);
        }
        return cart;
    }

    public void checkout() {
        ShoppingCart cart = getCurrentCart();
        // perform checkout logic
        cartHolder.remove(); // prevent memory leak
    }
}

class ShoppingCart {
    private List
products = new ArrayList<>();
    public void addProduct(Product product) { products.add(product); }
    public List
getProducts() { return products; }
}

A similar pattern is used in an aspect that stores the authenticated UserVo in a static ThreadLocal so that downstream code can retrieve the current user without passing it as a method argument.

@Aspect
@Component
public class UserConsistencyAspect {
    private static final ThreadLocal
userHolder = new ThreadLocal<>();

    @Pointcut("@annotation(org.nozomi.common.annotation.GetUser)")
    public void userAuthPoint() {}

    @Around("userAuthPoint()")
    public Object injectUserFromRequest(ProceedingJoinPoint joinPoint) throws Throwable {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        UserVo operator = (UserVo) authentication.getPrincipal();
        if (operator == null) {
            return Response.fail("User not found");
        }
        userHolder.set(operator);
        return joinPoint.proceed();
    }

    public static UserVo getUser() { return userHolder.get(); }
}

ThreadLocal is also used to keep a Hibernate Session per thread, ensuring that each request reuses the same session while preventing cross‑thread interference.

@Service
public class ProductService {
    private final ThreadLocal
sessionThreadLocal = new ThreadLocal<>();

    public Product getProductById(String id) {
        Session session = getSession();
        return session.get(Product.class, id);
    }

    public void updateProduct(Product product) {
        Session session = getSession();
        session.update(product);
    }

    private Session getSession() {
        Session session = sessionThreadLocal.get();
        if (session == null) {
            session = sessionFactory.openSession();
            sessionThreadLocal.set(session);
        }
        return session;
    }

    public void closeSession() {
        Session session = sessionThreadLocal.get();
        if (session != null) {
            session.close();
            sessionThreadLocal.remove();
        }
    }
}

StructuredTaskScope

Structured concurrency, introduced with virtual threads, encourages submitting tasks as Runnable or Callable to an executor and managing their lifecycles as a unit. StructuredTaskScope acts as a scoped virtual‑thread launcher. Tasks are forked, joined, and their results retrieved via Future objects.

public static Weather readWeather() throws Exception {
    try (var scope = new StructuredTaskScope
()) {
        Future
future = scope.fork(Weather::readWeatherFrom);
        scope.join();
        return future.resultNow();
    }
}

The scope implements AutoCloseable , allowing the familiar try‑with‑resources pattern. fork() creates a virtual thread, join() blocks until all forked tasks finish, and resultNow() returns the computed value or throws if the task failed.

ScopedValue

Basic Concept

ScopedValue, incubated in JDK 20, is an immutable, scoped alternative to ThreadLocal designed for structured concurrency. It holds a value that is visible only within a dynamic scope created by ScopedValue.where(...) . After the scope ends, the value becomes unbound.

Basic Usage

Declare a static final instance:

module dioxide.cn.module {
    requires jdk.incubator.concurrent;
}

Enable the preview feature with the VM option --enable-preview . Bind a value to a scope and run code inside it:

private static final ScopedValue
VALUE = ScopedValue.newInstance();

public static Object[] stringScope() throws Exception {
    return ScopedValue.where(VALUE, "value", () -> {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            Future
user = scope.fork(VALUE::get);
            Future
order = scope.fork(() -> VALUE.get().length());
            scope.join().throwIfFailed();
            return new Object[]{user.resultNow(), order.resultNow()};
        }
    });
}

The where() method takes three arguments: the ScopedValue instance, the value to bind, and a Runnable or Callable that runs within the bound scope.

Internal Classes

Snapshot : an immutable map from ScopedValue to its bound value, guaranteeing that once created it never changes.

Carrier : a mutable‑free builder that accumulates bindings; each call to where() returns a new Carrier, enabling a chain‑of‑responsibility style.

Cache : a small per‑thread cache that stores the result of a ScopedValue lookup to speed up repeated get() calls.

where() and call()

where() creates a Carrier, then delegates to Carrier.call(op) (or run(op) ) which handles snapshot creation, cache invalidation, and finally invokes the supplied Callable . The call chain ensures the value is bound only for the duration of the operation.

public static
R where(ScopedValue
key, T value, Callable
op) throws Exception {
    return where(key, value).call(op);
}

Summary

ThreadLocal remains useful for simple thread‑local state such as database sessions or request‑scoped data, but it suffers from mutable state, potential memory leaks, and inheritance overhead. ScopedValue, together with StructuredTaskScope, offers an immutable, scoped alternative that fits the structured concurrency model introduced in modern Java, especially when working with virtual threads.

Choosing between the two depends on the specific concurrency requirements: use ThreadLocal for classic thread‑per‑request patterns, and prefer ScopedValue when you need safe data sharing across structured, possibly asynchronous, task hierarchies.