If you've been eyeing StructuredTaskScope but didn't want --enable-preview anywhere near production, the wait is almost over: JEP 543, Structured Concurrency, has been Targeted for JDK 28 since October 21. In the JDK 28 early-access docs the API no longer carries the preview mark.
It took a while. StructuredTaskScope has been in preview since JDK 21 and the API was reworked along the way: open() and open(Joiner) date from JDK 25, open(Joiner, UnaryOperator) from JDK 26 and open(UnaryOperator) from JDK 27. If you tried it in 21 and gave up, what you'll find now looks very different.
The idea, in one example
You start several subtasks inside a block, wait for them, and if one fails the others are cancelled. Nothing keeps running outside the try.
record CustomerView(Customer customer, List<Order> orders) {}
CustomerView loadView(long id) throws ExecutionException, InterruptedException {
try (var scope = StructuredTaskScope.open()) {
Subtask<Customer> customer = scope.fork(() -> customerRepo.find(id));
Subtask<List<Order>> orders = scope.fork(() -> orderRepo.byCustomer(id));
scope.join(); // if one fails, the other is cancelled and ExecutionException is thrown
return new CustomerView(customer.get(), orders.get());
}
}
open() with no arguments applies the most common policy: all succeed, or the first failure wins. If everything finishes, join() returns null and you read each result with get(). If one fails, join() throws ExecutionException with the original exception as the cause, and the subtasks still running are cancelled via interruption.
By default each subtask runs in an unnamed virtual thread. If you need something else, withThreadFactory lets you plug in your own.
Joiners decide when it's over
You change the policy by passing a Joiner to open. The factories in JDK 28:
-
awaitAllSuccessfulOrThrow(): the one from the example above;join()returnsnull. -
allSuccessfulOrThrow():join()returns aList<T>with every result. -
anySuccessfulOrThrow(): the first successful result wins; it only fails if all of them fail. -
allUntil(Predicate): returns every subtask and cancels when the predicate says so; failures don't makejoin()throw.
The first three have a variant that takes a Function<Throwable, R_X> so you choose which exception join() throws. That's what the third type parameter of StructuredTaskScope<T, R, R_X extends Throwable> is for.
A classic case: ask two replicas for the same thing, keep the fastest, and don't wait more than two seconds.
String fetchFastest(String key) throws ExecutionException, InterruptedException {
try (var scope = StructuredTaskScope.open(
Joiner.<String>anySuccessfulOrThrow(),
cfg -> cfg.withTimeout(Duration.ofSeconds(2)))) {
scope.fork(() -> mirrorA.fetch(key));
scope.fork(() -> mirrorB.fetch(key));
return scope.join(); // the first one to answer wins; the other is cancelled
}
}
If the timeout fires, join() throws ExecutionException whose cause is a StructuredTaskScope.CancelledByTimeoutException. The config also has withName to name the scope.
If you already used the preview
The interface declaration, the join() signature and the Joiner names used here are the same in the JDK 27 preview and in the JDK 28 early access. So if your code compiles today with --enable-preview on JDK 27, chances are that moving to JDK 28 just means removing --enable-preview from javac and java.
One caveat: Targeted means the JEP is planned for JDK 28, and the early-access docs warn that the spec isn't final yet. Try your code on a JDK 28 build before taking anything for granted.
Check yourself in 2 minutes
Structured concurrency sits on top of virtual threads, and that's where most interview questions go. Three short challenges, no sign-up needed (they're in Spanish, the code isn't):
- Virtual threads: scale, not speed
- Pinning: when a virtual thread gets stuck
- From ThreadLocal to ScopedValue
They come from NextPatch, a small daily habit I'm building for Java developers: a 45-second summary of one change between versions, then a 2-minute challenge.
Are you planning to use StructuredTaskScope once 28 ships, or are you sticking with CompletableFuture? I'm curious what's holding people back.
Originally published in Spanish on the NextPatch blog, with links to the JEP and the JDK 28 early-access javadoc.
Top comments (0)