Java applications often perform multiple operations at the same time. A service might retrieve customer details, check inventory, calculate pricing, and request delivery information before returning a response.
These operations can run concurrently to reduce waiting time. However, managing related tasks with traditional threads, executors, and futures can become complicated.
Developers must coordinate task completion, handle failures, cancel unfinished operations, and ensure that background work does not continue after the main request has already failed.
Structured concurrency provides a way to organize related concurrent tasks around a clear parent-child relationship. Instead of treating every task as an independent operation, it allows developers to manage a group of tasks within a defined scope.
Java introduced structured concurrency through its preview APIs in recent releases. Because these APIs have evolved across JDK versions, developers should check the documentation for the specific Java version they use before adopting them.
This article explains structured concurrency, how it differs from traditional concurrency approaches, and how to use it to manage related Java tasks.
What Is Structured Concurrency?
Structured concurrency is a programming approach in which concurrent tasks are organized into a defined scope.
The parent operation creates child tasks, waits for their completion, and handles their results before the scope ends.
For example, consider an application that needs three independent operations:
Retrieve customer information.
Check product availability.
Calculate the order total.
With an unstructured approach, each operation might be submitted independently to an executor. The application then needs to track every future and determine what happens if one operation fails.
With structured concurrency, these tasks belong to a single operation. Their lifecycle is connected to the parent request.
The main idea is that a task should not unexpectedly outlive the operation responsible for it.
A structured task scope helps establish this relationship.
Why Traditional Concurrency Can Become Difficult
Java provides several concurrency APIs, including Thread, ExecutorService, Future, and CompletableFuture.
These APIs are useful, but coordinating multiple related operations requires careful lifecycle management.
Consider this example using CompletableFuture:
import java.util.concurrent.CompletableFuture;
public class OrderService {
public void processOrder() {
CompletableFuture<String> customerFuture =
CompletableFuture.supplyAsync(
() -> "Customer details"
);
CompletableFuture<String> inventoryFuture =
CompletableFuture.supplyAsync(
() -> "Inventory available"
);
CompletableFuture<String> pricingFuture =
CompletableFuture.supplyAsync(
() -> "Order price calculated"
);
CompletableFuture<Void> result =
CompletableFuture.allOf(
customerFuture,
inventoryFuture,
pricingFuture
);
result.join();
System.out.println(customerFuture.join());
System.out.println(inventoryFuture.join());
System.out.println(pricingFuture.join());
}
}This example executes independent operations concurrently.
However, several concerns remain:
The developer must coordinate all futures.
Failure handling needs additional planning.
Cancellation behavior must be considered.
The relationship between the parent operation and child tasks is not represented by a dedicated scope.
Unfinished operations may continue consuming resources if lifecycle management is incomplete.
These concerns become more difficult when a service has many concurrent operations or nested asynchronous workflows.
Understanding Java Structured Concurrency APIs
Java's structured concurrency APIs have been introduced and refined through preview releases.
The StructuredTaskScope API provides a mechanism for creating and managing related tasks.
A task scope generally follows this lifecycle:
Create a task scope.
Fork child tasks.
Join the tasks.
Handle task results or failures.
Close the scope.
The scope provides a boundary for the concurrent operations.
The exact API names, constructors, and policy classes have changed across preview iterations. Therefore, examples must target a specific JDK release rather than assuming that code from an earlier preview will compile unchanged on a newer release.
The following sections illustrate the core design using the Java 21 preview API.
Creating Concurrent Tasks With StructuredTaskScope
In the Java 21 preview API, StructuredTaskScope can be used to start multiple related tasks.
The following example retrieves customer and inventory information concurrently.
import java.util.concurrent.StructuredTaskScope;
public class OrderService {
public void processOrder() throws Exception {
try (var scope =
new StructuredTaskScope.ShutdownOnFailure()) {
var customerTask = scope.fork(
() -> getCustomerDetails()
);
var inventoryTask = scope.fork(
() -> checkInventory()
);
scope.join();
scope.throwIfFailed();
String customer = customerTask.get();
String inventory = inventoryTask.get();
System.out.println(customer);
System.out.println(inventory);
}
}
private String getCustomerDetails() {
return "Customer details retrieved";
}
private String checkInventory() {
return "Inventory available";
}
}This example demonstrates several important concepts.
Forking child tasks
In the Java 21 preview API, StructuredTaskScope can be used to start multiple related tasks.
var customerTask = scope.fork(
() -> getCustomerDetails()
);The returned subtask represents the operation. The parent can retrieve its result after the scope has joined the tasks.
Waiting for completion
The join() method waits for the child tasks to finish.
scope.join();The parent operation does not continue to process the results until the required tasks have completed.
Handling failures
The ShutdownOnFailure policy requests shutdown of the remaining tasks when a child task fails.
The following call checks whether a task failed:
scope.throwIfFailed();If a failure occurred, the method propagates it rather than allowing the application to continue as if every operation succeeded.
Closing the scope
The try-with-resources statement ensures that the scope is closed.
try (var scope =
new StructuredTaskScope.ShutdownOnFailure()) {Closing the scope is part of its lifecycle management. The parent operation should not leave child tasks running without considering their completion and cancellation.
Understanding ShutdownOnFailure and ShutdownOnSuccess
Structured concurrency supports different task coordination policies.
The Java 21 preview API included policies such as ShutdownOnFailure and ShutdownOnSuccess.
ShutdownOnFailure
Use this approach when all required operations must succeed.
For example, an order cannot be confirmed unless customer validation and inventory verification both succeed.
try (var scope =
new StructuredTaskScope.ShutdownOnFailure()) {
var customerTask = scope.fork(
() -> validateCustomer()
);
var inventoryTask = scope.fork(
() -> verifyInventory()
);
scope.join();
scope.throwIfFailed();
System.out.println(customerTask.get());
System.out.println(inventoryTask.get());
}If one task fails, the scope requests cancellation of the other unfinished tasks.
This avoids continuing unnecessary work when the overall operation cannot succeed.
ShutdownOnSuccess
Use this policy when the application needs the first successful result from multiple independent alternatives.
For example, a service might query two independent data sources and accept the first successful response.
In the Java 21 preview API, the pattern looked like this:
try (var scope =
new StructuredTaskScope.ShutdownOnSuccess<String>()) {
scope.fork(() -> queryPrimaryService());
scope.fork(() -> querySecondaryService());
String result = scope.join()
.result();
System.out.println(result);
}This approach can be useful for fallback services or redundant read operations.
However, it should not be used when every task must complete or when the results need to be combined.
Join the conversation! Your thoughts help the community grow.