Structured Concurrency and Scoped Values in Java 25: Replacing ThreadLocal in High-Throughput Services: Step-by-Step Tutorial

Modern web services process thousands of concurrent requests every second. Java 21 introduced virtual threads to make servers faster and cheaper. However, virtual threads introduce new challenges when tasks run without structure. If one background task fails, other tasks continue running and waste expensive CPU cycles. Even worse, traditional ThreadLocal variables cause memory leaks and high memory usage across millions of virtual threads. Java 25 solves both problems with Structured Concurrency and Scoped Values. In this tutorial, you will learn how to replace ThreadLocal, coordinate parallel tasks safely, and build a high-throughput Spring Boot 4 checkout service.

Table of Contents

• The Problems of Unstructured Concurrency
• Why ThreadLocal Fails at Scale
• Understanding Scoped Values in Java 25
• Understanding Structured Concurrency
• Building the Spring Boot 4 Workshop Service
• Pattern 1: Fail-Fast Parallel Fan-Out
• Pattern 2: Speculative Redundant Racing
• Comparative Concurrency & Context Matrix
• Performance and Memory Benchmarks
• Enterprise Real-World Use Cases
• Best Practices and Common Mistakes
• Companion Workshop Code
• Frequently Asked Questions
• References

---

The Problems of Unstructured Concurrency

In standard Java code, developers run parallel tasks using ExecutorService or CompletableFuture. This style is called unstructured concurrency. Unstructured concurrency means that tasks have no clear owner or boundary.

Consider an e-commerce checkout request. The server must check inventory, charge a credit card, and run fraud detection. If the developer submits three tasks to an ExecutorService, each task runs independently on its own thread. Now imagine the credit card gets declined immediately.

In an unstructured system, the inventory and fraud detection tasks do not stop. They continue running in the background. They query the database. They consume network bandwidth and CPU cycles. We call these tasks orphan threads. Orphan threads waste system resources and create silent bugs.

Unstructured concurrency creates three serious problems:

• Thread and Resource Leaks: When a parent request fails, child threads keep running until they finish or time out.
• Lost Exceptions: If multiple child tasks fail, the application often loses secondary exception details or hides root causes.
• Broken Observability: Thread dumps cannot show which thread created which task. There is no parent-child tree structure in the logs.

Java 25 introduces StructuredTaskScope to fix this issue. Structured concurrency treats multiple subtasks as a single unit of work. If one subtask fails, the scope automatically cancels the other subtasks immediately.

---

Why ThreadLocal Fails at Scale

For more than twenty years, Java developers used ThreadLocal to share data across methods. When an HTTP request reaches a server, a filter stores security tokens, tenant identifiers, and correlation IDs in a ThreadLocal. Downstream services read this data without passing extra parameters through every method signature.

This approach worked when servers ran 200 platform threads. However, modern microservices run hundreds of thousands of Java 25 Virtual Threads. In this high-concurrency world, ThreadLocal introduces severe architectural problems.

First, ThreadLocal is mutable. Any class in your application can call threadLocal.set(newValue). If a third-party library changes the value, your business logic can fail in unexpected ways. Second, ThreadLocal has an unbounded lifetime. The value stays in memory until someone manually calls threadLocal.remove(). If a developer forgets the finally block, the object leaks into the thread pool. The next request processed by that thread can read stale customer data, creating a security breach.

Third, InheritableThreadLocal is very expensive. When a virtual thread forks child threads, the JVM copies the internal ThreadLocalMap. Copying thousands of maps creates heavy garbage collector pressure. We need an immutable, bounded, and lightweight solution.

---

Understanding Scoped Values in Java 25

Java 25 introduces ScopedValue to replace ThreadLocal. A ScopedValue is an immutable container that holds a value for a specific block of code. Once you bind a value, nobody can mutate it.

When the execution leaves the code block, the binding disappears automatically. You do not need manual try ... finally { remove(); } logic. The garbage collector never holds leaked references.

Here is how you define and use a ScopedValue:

public class SecurityContextHolder {

    // Define a static constant ScopedValue key
    public static final ScopedValue<String> USER_ID = ScopedValue.newInstance();

    public void handleRequest(String userId) {
        // Bind the value for the execution of the lambda block
        ScopedValue.where(USER_ID, userId).run(() -> {
            // Downstream methods can read the value directly
            processPayment();
        });
        
        // Outside the block, USER_ID is no longer bound!
    }

    private void processPayment() {
        // Read the value safely without passing it as an argument
        String currentUser = USER_ID.get();
        System.out.println("Processing payment for user: " + currentUser);
    }
}

Notice how clean this design is. The method processPayment() does not take a userId parameter. However, it reads USER_ID.get() with full confidence. As soon as the lambda block finishes, the binding ends. Most importantly, child virtual threads created inside that block automatically inherit the ScopedValue without copying any internal hash maps.

---

Understanding Structured Concurrency

In structured programming, code blocks have clean entries and clean exits. An if-else block or a for loop has a clear beginning and end. Structured concurrency brings the same safety to multi-threaded code.

The core rule of structured concurrency is simple: if a task splits into concurrent subtasks, all subtasks must finish before the main block exits.

Java 25 implements this pattern with StructuredTaskScope. A StructuredTaskScope manages the lifetime of concurrent subtasks using standard try-with-resources syntax:

try (var scope = StructuredTaskScope.open()) {
    // 1. Fork concurrent subtasks
    Subtask<String> taskA = scope.fork(() -> fetchUser());
    Subtask<Integer> taskB = scope.fork(() -> fetchBalance());

    // 2. Synchronize and wait for completion
    scope.join();

    // 3. Process results safely
    return new DashboardData(taskA.get(), taskB.get());
} // 4. The scope closes and terminates any remaining threads automatically

The try-with-resources block acts as a barrier. The thread cannot leave the block until all subtasks finish or terminate. If an error occurs or a timeout triggers, the scope closes and cancels all running child threads. You never create orphan background threads.

---

Building the Spring Boot 4 Workshop Service

Let us build a real-world Spring Boot 4 checkout microservice. Our application must receive an HTTP checkout request, read the incoming correlation headers, bind them using ScopedValue, and coordinate three subtasks using StructuredTaskScope.

Defining the Request Context

First, we create an immutable record named RequestContext to store our correlation ID, user ID, and tenant ID:

package com.webcodein.concurrency.model;

import java.time.Instant;
import java.util.UUID;

public record RequestContext(
        String correlationId,
        String userId,
        String tenantId,
        Instant timestamp
) {
    public static RequestContext anonymous() {
        return new RequestContext(
                UUID.randomUUID().toString(),
                "anonymous",
                "tenant-default",
                Instant.now()
        );
    }
}

Creating the Scoped Value Holder

Next, we build a static helper class named RequestContextScope to manage the ScopedValue instance:

package com.webcodein.concurrency.context;

import com.webcodein.concurrency.model.RequestContext;
import java.lang.ScopedValue;

public final class RequestContextScope {

    public static final ScopedValue<RequestContext> CONTEXT = ScopedValue.newInstance();

    private RequestContextScope() {}

    public static RequestContext get() {
        return CONTEXT.isBound() ? CONTEXT.get() : RequestContext.anonymous();
    }

    public static boolean isBound() {
        return CONTEXT.isBound();
    }

    public static <T, X extends Throwable> T callWith(RequestContext context, ScopedValue.CallableOp<T, X> op) throws X {
        return ScopedValue.where(CONTEXT, context).call(op);
    }

    public static void runWith(RequestContext context, Runnable runnable) {
        ScopedValue.where(CONTEXT, context).run(runnable);
    }
}

Intercepting Requests with a Servlet Filter

Now we create a Spring web filter named ScopedRequestContextFilter. This filter extracts the X-Correlation-Id, X-User-Id, and X-Tenant-Id HTTP headers from incoming requests. It binds the RequestContext to our ScopedValue for the entire lifecycle of the request:

package com.webcodein.concurrency.web;

import com.webcodein.concurrency.context.RequestContextScope;
import com.webcodein.concurrency.model.RequestContext;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.time.Instant;
import java.util.UUID;

@Component("scopedRequestContextFilter")
@Order(Ordered.HIGHEST_PRECEDENCE)
public class ScopedRequestContextFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain
    ) throws ServletException, IOException {
        String correlationId = request.getHeader("X-Correlation-Id");
        if (correlationId == null || correlationId.isBlank()) {
            correlationId = UUID.randomUUID().toString();
        }

        String userId = request.getHeader("X-User-Id");
        if (userId == null || userId.isBlank()) {
            userId = "anonymous";
        }

        String tenantId = request.getHeader("X-Tenant-Id");
        if (tenantId == null || tenantId.isBlank()) {
            tenantId = "tenant-primary";
        }

        RequestContext context = new RequestContext(correlationId, userId, tenantId, Instant.now());
        response.setHeader("X-Correlation-Id", correlationId);

        // Bind the ScopedValue for the entire downstream execution stack
        try {
            RequestContextScope.callWith(context, () -> {
                filterChain.doFilter(request, response);
                return null;
            });
        } catch (ServletException | IOException e) {
            throw e;
        } catch (Exception e) {
            throw new ServletException("Failed to process request within ScopedValue scope", e);
        }
    }
}

Every controller, service, and forked virtual thread downstream now accesses this context with zero memory leaks. When the HTTP response finishes, the binding vanishes automatically.

---

Pattern 1: Fail-Fast Parallel Fan-Out

When an order arrives, our service must execute three operations simultaneously:

1. Reserve product stock in the database (40ms).
2. Authorize the customer credit card via a payment gateway (60ms).
3. Evaluate fraud risk using an AI scoring engine (30ms).

If we run these tasks sequentially, the user waits 40ms + 60ms + 30ms = 130ms. By running them concurrently, the total time drops to the slowest task: only 60ms!

Even more importantly, if fraud detection detects an attacker, we want to stop immediately. We do not want to charge the credit card or reserve inventory. In Java 25, we use StructuredTaskScope.Joiner.awaitAllSuccessfulOrThrow() to enforce this fail-fast policy.

Here is the implementation in our OrderProcessingService:

package com.webcodein.concurrency.service;

import com.webcodein.concurrency.context.RequestContextScope;
import com.webcodein.concurrency.model.OrderRequest;
import com.webcodein.concurrency.model.OrderResult;
import com.webcodein.concurrency.model.RequestContext;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

import java.util.concurrent.ExecutionException;
import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.Subtask;

@Service
public class OrderProcessingService {

    private static final Logger log = LoggerFactory.getLogger(OrderProcessingService.class);

    private final InventoryService inventoryService;
    private final PaymentService paymentService;
    private final FraudDetectionService fraudDetectionService;

    public OrderProcessingService(
            InventoryService inventoryService,
            PaymentService paymentService,
            FraudDetectionService fraudDetectionService
    ) {
        this.inventoryService = inventoryService;
        this.paymentService = paymentService;
        this.fraudDetectionService = fraudDetectionService;
    }

    public OrderResult processOrder(OrderRequest request) {
        long startTime = System.currentTimeMillis();
        RequestContext context = RequestContextScope.get();
        log.info("[Correlation: {}] Starting structured checkout for order {}",
                context.correlationId(), request.orderId());

        // Joiner awaits all tasks or throws on the first failure
        var joiner = StructuredTaskScope.Joiner.awaitAllSuccessfulOrThrow();
        try (var scope = StructuredTaskScope.open(joiner)) {
            // Fork 3 Virtual Threads. All 3 threads inherit the ScopedValue context!
            Subtask<String> inventoryTask = scope.fork(() ->
                    inventoryService.reserveItems(request.orderId(), request.itemCount()));

            Subtask<String> paymentTask = scope.fork(() ->
                    paymentService.processPayment(request.orderId(), request.amount()));

            Subtask<Integer> fraudTask = scope.fork(() ->
                    fraudDetectionService.evaluateRisk(request.orderId(), request.customerId(), request.amount()));

            // Wait for all subtasks to finish, or fail fast immediately
            scope.join();

            long duration = System.currentTimeMillis() - startTime;
            return new OrderResult(
                    request.orderId(),
                    "CONFIRMED",
                    inventoryTask.get(),
                    paymentTask.get(),
                    fraudTask.get(),
                    duration,
                    context.correlationId(),
                    Thread.currentThread().toString()
            );
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("Order processing scope interrupted", e);
        } catch (Throwable throwable) {
            // Unwrap the real domain cause from ExecutionException
            Throwable cause = (throwable instanceof ExecutionException && throwable.getCause() != null)
                    ? throwable.getCause()
                    : throwable;
            log.error("[Correlation: {}] Order processing failed: {}", context.correlationId(), cause.getMessage());
            if (cause instanceof RuntimeException runtimeException) {
                throw runtimeException;
            }
            throw new RuntimeException("Order processing failed", cause);
        }
    }
}

Notice what happens inside the catch block. When fraudDetectionService throws a FraudDetectedException, the scope cancels the inventoryTask and paymentTask virtual threads before they complete. The payment gateway is never charged, and no database locks remain open.

Task Tree Hierarchy and Cascading Interruption

As illustrated in Figure 4, the fundamental architectural breakthrough of Java 25 Structured Concurrency is the enforcement of a strict lexical task tree hierarchy. In traditional concurrent programming using CompletableFuture.allOf() or unbounded thread pools, child tasks possess an independent lifecycle. If one task throws an exception, sibling tasks continue running in the background unaware of the failure. These orphaned tasks consume CPU cycles, keep database connections checked out from the pool, hold open socket descriptors, and may even execute unintended downstream writes.

In contrast, StructuredTaskScope guarantees that child virtual threads are strictly bounded by the syntactic block of the parent scope. When fraudDetectionService fails with a FraudDetectedException:

• The scope transitions to a cancelled state and intercepts the first causal exception.
• It immediately calls Thread.interrupt() across all remaining sibling subtasks (such as the payment authorization and stock reservation).
• Blocking network sockets, HTTP clients, and database queries receive an immediate InterruptedException, closing connections cleanly and unwinding their call stacks.
• When the try-with-resources block exits, all child threads are guaranteed to have completed or terminated. Zero zombie virtual threads escape into the JVM background.

Furthermore, this hierarchy is fully recognized by modern diagnostic tools. During production debugging, a thread dump taken via JDK Flight Recorder (JFR) displays virtual threads organized in their structural parent-child tree rather than a flat, chaotic list of thousands of unrelated threads. For distributed tracking, this pairs naturally with event-driven Kafka messaging and HikariCP connection pool tuning.

---

Pattern 2: Speculative Redundant Racing

In distributed systems, external APIs experience sudden latency spikes. If your checkout page needs a shipping cost estimate, waiting for a slow provider hurts user conversion. A common enterprise pattern is hedged requests or speculative racing.

You query two carrier APIs concurrently (such as FastExpress and BudgetFreight). Whichever carrier answers first wins. You take the fastest result and cancel the slower query immediately.

In Java 25, you implement speculative racing using StructuredTaskScope.Joiner.anySuccessfulOrThrow():

public ShippingQuote getFastestShippingQuote(String origin, String destination) {
    RequestContext context = RequestContextScope.get();
    log.info("[Correlation: {}] Racing carrier quotes from {} to {}", context.correlationId(), origin, destination);

    // Joiner completes as soon as ANY subtask succeeds!
    var joiner = StructuredTaskScope.Joiner.<ShippingQuote>anySuccessfulOrThrow();
    try (var scope = StructuredTaskScope.open(joiner)) {
        // Fork redundant queries to both carriers
        scope.fork(() -> shippingCarrierService.fetchPrimaryCarrierQuote(origin, destination));
        scope.fork(() -> shippingCarrierService.fetchSecondaryCarrierQuote(origin, destination));

        // Wait for the winner
        scope.join();

        // Return the fastest quote! The slower subtask is cancelled automatically.
        return joiner.result();
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new IllegalStateException("Shipping quote race interrupted", e);
    } catch (Throwable throwable) {
        Throwable cause = (throwable instanceof ExecutionException && throwable.getCause() != null)
                ? throwable.getCause()
                : throwable;
        throw new RuntimeException("Quote query failed", cause);
    }
}

FastExpress answers in 40ms. BudgetFreight takes 200ms. With anySuccessfulOrThrow(), your customer gets an answer in 40ms. BudgetFreight gets cancelled before wasting server memory.

---

Comparative Concurrency & Context Propagation Matrix

Modern Java architectures offer several mechanisms for concurrency and context propagation. The following comparative matrix contrasts traditional techniques with Java 25 Structured Concurrency and Scoped Values:

Performance and Memory Benchmarks

To measure the concrete benefits of ScopedValue compared to ThreadLocal, we executed a micro-benchmark processing 100,000 request iterations on a multi-core machine running Java 25 and Spring Boot 4.

Because ScopedValue avoids creating internal ThreadLocalMap tables, it saves dozens of megabytes under high concurrency. Your application handles higher request volumes without triggering garbage collector pauses or memory exhaustion.

---

Enterprise Real-World Use Cases

1. High-Volume E-Commerce Order Checkout Fan-Out

In global retail platforms, processing an order checkout involves coordinating inventory deduction, payment authorization, loyalty rewards redemption, and fraud assessment. With StructuredTaskScope.ShutdownOnFailure, these independent operations fan out across lightweight virtual threads simultaneously. If the fraud engine identifies an unauthorized device or the payment gateway declines the card, the scope cancels the inventory deduction immediately. This prevents accidental stock locking and reduces end-to-end checkout latency from 350ms to 85ms under peak flash sale traffic, directly complementing high-concurrency Redis patterns.

2. Multi-Tenant Banking Transaction Orchestrator

Financial SaaS platforms must enforce strict data isolation across enterprise tenants. Using traditional ThreadLocal, passing tenant credentials, audit trace tokens, and encryption keys across asynchronous worker threads required manual boilerplate or leaked tenant context across reused threads. By binding tenant context to an immutable ScopedValue at the HTTP filter boundary, child virtual threads querying partitioned databases inherit tenant identity automatically without copying memory. Sibling tenant requests remain completely isolated, combining seamlessly with optimistic and pessimistic locking strategies.

3. Distributed Price Quote Aggregator with Speculative Racing

Logistics and insurance platforms query dozens of third-party external APIs to retrieve real-time freight quotes and currency conversion rates. Third-party network latency is unpredictable, with tail latencies exceeding 2,000ms. By using StructuredTaskScope.Joiner.anySuccessfulOrThrow(), the aggregator queries three mirror providers concurrently. The moment the fastest carrier responds, the scope captures the rate and cancels the remaining slow requests. This speculative hedging pattern reduces 99th percentile API latency by over 60 percent while protecting outbound socket connection pools.

Best Practices and Common Mistakes

1. Always Use Try-With-Resources

Never instantiate StructuredTaskScope without a try-with-resources block. The closing bracket of the try block acts as the synchronization boundary. If you omit it, threads may escape lexical control and run without limits.

2. Never Put Mutable Objects in a ScopedValue

A ScopedValue reference is immutable. However, if you store a mutable object inside it (such as a standard ArrayList or a mutable Java bean), different threads could mutate the internal fields. Always store immutable Java records inside a ScopedValue.

3. Unwrap ExecutionException

When a subtask inside a StructuredTaskScope throws an exception, scope.join() wraps it inside an ExecutionException. If you build Spring REST APIs, inspect throwable.getCause(). Otherwise, your Spring @ExceptionHandler receives a generic ExecutionException and returns an HTTP 500 error instead of the proper HTTP 403 or 402 code.

4. Combine with Database Locks Safely

When running concurrent subtasks, be careful with transaction boundaries. If two subtasks attempt to update the same database row concurrently, you can cause deadlocks. Use Optimistic and Pessimistic Locking patterns to coordinate database state across concurrent transactions.

---

Companion Workshop Code

To run, test, and experiment with all code examples shown in this tutorial, visit the companion workshop repository on GitHub:

GitHub: java-core/structured-concurrency-scoped-values-java-25

The companion workshop project includes:

• Complete Spring Boot 4.0.0 application configured for Java 25 preview features.
• Full test suite with 5 automated integration tests verifying fan-out checkout, fail-fast cancellation, and speculative carrier racing.
• Executable Maven wrapper (./mvnw) and multi-stage Dockerfile.
• Step-by-step running guide with ready-to-use curl test commands.

---

Frequently Asked Questions

---

For more foundational guides on modern Java and Spring Boot architecture, explore our companion analyses on Project Valhalla Value Types in Java 25 and modern local development with Testcontainers and Docker Compose.

References

• JEP 480: Structured Concurrency (Third Preview) – OpenJDK
• JEP 481: Scoped Values (Third Preview) – OpenJDK
• Spring Boot Reference Documentation – Official Documentation
• Java SE 25 API Specification – Oracle Corporation