Structured Concurrency in Java

Structured concurrency is a way to treat multiple related concurrent tasks as one unit of work.

The mental model is simple: if a parent operation starts several child tasks, those child tasks should finish, fail, or be cancelled before the parent operation is considered complete.

Structured concurrency is a modern Java feature and has gone through preview iterations. Java 21 includes a preview version of StructuredTaskScope, and newer JDKs have continued to revise the API.

Suppose a backend endpoint needs to build a dashboard. It needs user data, order data, and recommendation data.

Build Dashboard
    ├── Load user
    ├── Load orders
    └── Load recommendations

These calls can run concurrently. Starting them is not the hard part. The hard part is coordinating them correctly.

• What if one task fails?
• What if one task is slow?
• What if the client disconnects?
• What if the parent request times out?
• Who cancels the remaining tasks?

With normal ExecutorService code, it is easy to start multiple tasks and accidentally manage them poorly.

Future<User> userFuture =
        executor.submit(() -> loadUser(userId));

Future<List<Order>> ordersFuture =
        executor.submit(() -> loadOrders(userId));

Future<List<Product>> recommendationsFuture =
        executor.submit(() -> loadRecommendations(userId));

User user = userFuture.get();
List<Order> orders = ordersFuture.get();
List<Product> recommendations = recommendationsFuture.get();

return new Dashboard(user, orders, recommendations);

This looks reasonable, but the failure behavior is awkward. If loading the user fails, what happens to the orders and recommendations tasks? Are they cancelled? Are they still running? Who owns them?

Parent task: Build Dashboard
        |
        +-- child task: Load User
        |
        +-- child task: Load Orders
        |
        +-- child task: Load Recommendations

Parent does not finish until child tasks are handled.

The parent scope owns the child tasks. That gives the program a clearer lifecycle.

This is the kind of code you may see with the Java 21 preview API.

import java.util.concurrent.StructuredTaskScope;

public Dashboard buildDashboard(String userId) throws Exception {
    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
        var userTask =
                scope.fork(() -> loadUser(userId));

        var ordersTask =
                scope.fork(() -> loadOrders(userId));

        var recommendationsTask =
                scope.fork(() -> loadRecommendations(userId));

        scope.join();
        scope.throwIfFailed();

        return new Dashboard(
                userTask.get(),
                ordersTask.get(),
                recommendationsTask.get()
        );
    }
}

The important idea is not the exact syntax. The important idea is that the subtasks belong to the scope. The scope joins them, handles failure, and closes cleanly.

Structured concurrency lets you choose a policy. A common policy is shutdown-on-failure.

Load user succeeds
Load orders fails
Load recommendations still running
        ↓
Scope notices failure
        ↓
Cancel remaining work
        ↓
Parent fails cleanly

Structured concurrency and virtual threads are often discussed together.

Virtual threads make it cheap to run many blocking-looking tasks. Structured concurrency helps organize those tasks so their lifecycle stays understandable.

Structured concurrency is useful when one logical operation needs several concurrent subtasks.

• Build a dashboard from multiple service calls
• Fetch user, account, and permissions in parallel
• Query multiple replicas and use the fastest successful result
• Run independent validations concurrently
• Call several downstream APIs as part of one request

Structured concurrency is not a replacement for every async style.