skip to content

How do StructuredTaskScope's fail-fast and first-success policies (ShutdownOnFailure and ShutdownOnSuccess before JDK 25, Joiners since) differ, when would you use each, and how do they change error and cancellation propagation?

level: seniorimportance: must knowfreq 58%

answer

  1. Fail-fast = need ALL; first failure cancels
  2. First-success = need ONE; race, winner returned
  3. both: cancelling interrupts surviving siblings
  4. outcome reaches the owner at join()
  5. JDK 27: open() / Joiner.anySuccessfulOrThrow()

basics

~20 s

Fail-fast (ShutdownOnFailure before JDK 25; open() or Joiner.allSuccessfulOrThrow() since) cancels the rest on the first failure, for when you need every result. First-success (ShutdownOnSuccess; Joiner.anySuccessfulOrThrow()) cancels the rest on the first success, for when any one will do.

solid answer

~50 s

Both are completion policies: they decide when join() can stop early and what happens to the other subtasks. Fail-fast is the all-or-nothing fan-out: as soon as any subtask fails, the scope is cancelled, interrupting the still-running siblings, and the failure reaches the owner. Use it when an operation aggregates several required results (user AND orders AND prefs). First-success is the race: the first subtask to succeed cancels the scope, the losers are interrupted, and its value is the outcome. Use it for redundant or hedged requests. In JDK 21 to 24 these were the ShutdownOnFailure and ShutdownOnSuccess subclasses, read with throwIfFailed() and result(). Since JDK 25 (still preview at 27), fail-fast is the default policy of StructuredTaskScope.open(), first-success is Joiner.anySuccessfulOrThrow() (anySuccessfulResultOrThrow() at 25), and join() returns the result or throws: ExecutionException at JDK 27, FailedException at JDK 25.

code

java · 18 lines
java
// Need ALL results, fail fast: the default policy of open()
Page page(String id) throws ExecutionException, InterruptedException {
    try (var scope = StructuredTaskScope.open()) {
        var u = scope.fork(() -> fetchUser(id));
        var o = scope.fork(() -> fetchOrders(id));
        scope.join();   // throws ExecutionException on the first failure; the rest are cancelled
        return new Page(u.get(), o.get());
    }
}

// Need ANY one result, race
String fastest() throws ExecutionException, InterruptedException {
    try (var scope = StructuredTaskScope.open(Joiner.<String>anySuccessfulOrThrow())) {
        scope.fork(() -> queryMirror("eu"));
        scope.fork(() -> queryMirror("us"));
        return scope.join();   // the first success; the losers are cancelled
    }
}

go deeper

for a junior

Can say fail-fast means you need all results and it stops on a failure, while first-success means you need one and it stops on the first success.

for a middle

Maps each policy to a use case (aggregate-all vs race) and knows the outcome arrives at join(): returned or thrown since JDK 25, via throwIfFailed() or result() before.

for a senior

Explains cancellation propagation downward, error/result propagation upward, the invokeAll/invokeAny analogy, and the no-cancellation variant, naming the API for the JDK in use.

for a principal

Discusses choosing policies for resilience (hedging, fail-fast aggregation), interrupt cooperation in subtasks, tail-latency trade-offs, and the move from subclasses to Joiners across JDK previews.

## Why policies exist When you fork several subtasks, what should happen if one fails, or if you only need one to succeed? A **completion policy** answers that: it decides **when `join()` may return early** and what to do with the **other** subtasks. In JDK 21 to 24 the two classic policies were the subclasses `StructuredTaskScope.ShutdownOnFailure` and `ShutdownOnSuccess`. Since JDK 25 a policy is a **`Joiner`** passed to `StructuredTaskScope.open(...)`, and `StructuredTaskScope` is still a **preview API** at JDK 27 (`--enable-preview`). Key shared mechanic: stopping early **cancels** the scope — it stops new subtasks from starting and **interrupts every subtask that is still running**. (JDK 21 to 24 called this *shutdown*, with a public `shutdown()` method.) Interruption is how **cancellation propagates downward** from the scope to its children. The policy's outcome **propagates upward** to the owner: an exception, or the winning result. ## Fail-fast — "I need them all" Pattern: a **fan-out** where you need **every** result and any single failure ruins the operation. At JDK 27 this is the default policy of `open()`: ```java try (var scope = StructuredTaskScope.open()) { // default policy: fail fast Subtask<User> u = scope.fork(() -> fetchUser(id)); Subtask<Orders> o = scope.fork(() -> fetchOrders(id)); Subtask<Prefs> p = scope.fork(() -> fetchPrefs(id)); scope.join(); // waits for all, or throws ExecutionException on the first failure return new Page(u.get(), o.get(), p.get()); } ``` - If **all** succeed, `join()` returns normally and you read each `Subtask`. - If **any** subtask fails, the scope is cancelled at once — siblings still in flight are **interrupted** (no point computing results you'll throw away) — and `join()` throws `ExecutionException` with the first failure as its cause. JDK 25 and 26 throw the unchecked `StructuredTaskScope.FailedException` instead. This is **fail-fast**. - `Joiner.allSuccessfulOrThrow()` applies the same policy but makes `join()` return the list of results (a stream of subtasks at JDK 25), for subtasks that share one result type. - In JDK 21 to 24 the same code used `new StructuredTaskScope.ShutdownOnFailure()` and `scope.join().throwIfFailed()`. - **Use when:** aggregating multiple *required* results — building a page from several services, scatter-gather where partial results are useless. ## First-success — race / "I need just one" Pattern: a **race** among redundant attempts where the **first success wins** and the rest are wasted effort: ```java try (var scope = StructuredTaskScope.open(Joiner.<String>anySuccessfulOrThrow())) { scope.fork(() -> queryMirror("eu")); scope.fork(() -> queryMirror("us")); scope.fork(() -> queryMirror("ap")); return scope.join(); // the first successful result; the rest are cancelled } ``` - The **first subtask to succeed** cancels the scope: the **losing subtasks are interrupted** and `join()` returns the winner's value. - If **all** fail, `join()` throws `ExecutionException` with the exception from one of them as the cause. - JDK 25 names this joiner `anySuccessfulResultOrThrow()`; JDK 21 to 24 used `new StructuredTaskScope.ShutdownOnSuccess<T>()` and read the winner with `result()`. - **Use when:** hedged or redundant requests, latency reduction by querying several replicas and taking the fastest, fallback chains where any one source suffices. ## The propagation summary | | Fail-fast | First-success | |---|---|---| | Stops early on | first **failure** | first **success** | | Fate of siblings | interrupted | interrupted | | Outcome reaches the owner | `join()` throws | `join()` returns the winner | | You need… | **all** results | **any one** result | | JDK 27 API | `open()` or `Joiner.allSuccessfulOrThrow()` | `Joiner.anySuccessfulOrThrow()` | | JDK 21 to 24 API | `ShutdownOnFailure`, `throwIfFailed()` | `ShutdownOnSuccess`, `result()` | | Mental model | `invokeAll` + fail-fast | `invokeAny` | **Cancellation propagation (downward):** cancelling interrupts surviving children; well-behaved subtasks observe the interrupt (during blocking calls or by checking `Thread.currentThread().isInterrupted()`) and stop promptly. **Error/result propagation (upward):** the controlling outcome reaches the owner at `join()`. ## A neutral option Sometimes you want every subtask to run to completion and handle each outcome yourself (no fail-fast). JDK 21 to 24 did this with a plain `new StructuredTaskScope<>()`, and JDK 25 and 26 with `Joiner.awaitAll()`. JDK 27 removed `awaitAll()`; `Joiner.allUntil(...)` with a predicate that is never true waits for all subtasks and returns every `Subtask`, so you can inspect each one's `state()`: ```java <T> List<Subtask<T>> runAll(List<Callable<T>> tasks) throws InterruptedException { try (var scope = StructuredTaskScope.open(Joiner.<T>allUntil(_ -> false))) { tasks.forEach(scope::fork); return scope.join(); // every subtask, once all have completed } } ``` ## In an interview Lead with the semantics — first-failure-cancels-the-rest vs first-success-cancels-the-rest — then name the API of the JDK you are on: the subclasses through JDK 24, `Joiner`s since JDK 25, and a `join()` that throws `ExecutionException` from JDK 27.

  • When a fail-fast scope is cancelled, what happens to the subtasks still running?
    They are interrupted: cancellation propagates downward. Well-behaved subtasks observe the interrupt during blocking operations or by checking the interrupt flag and stop promptly, and close() waits for all of them to finish, so no work leaks past the block.
  • Give a realistic use case for a first-success policy.
    Hedged/redundant requests: query several replicas or mirrors of the same data in parallel and take whichever responds first, cancelling the slower ones to cut tail latency.
  • Is there a scope that doesn't stop early at all?
    Yes. JDK 21 to 24 used a plain new StructuredTaskScope<>(), and JDK 25 and 26 Joiner.awaitAll(). JDK 27 removed awaitAll(); Joiner.allUntil(s -> false) waits for every subtask, and join() returns them all so you can inspect each one's state.

  • Swapping them: thinking the first-success policy stops on a failure, or vice versa.
  • Claiming the losing or sibling subtasks keep running after the scope is cancelled — they're interrupted.
  • Saying fail-fast returns partial results — join() throws; you don't use the partial set.
  • Believing cancellation forcibly kills threads — it interrupts; subtasks must cooperate to stop promptly.
  • Still writing new ShutdownOnFailure() or throwIfFailed() on JDK 25 or later, where they no longer exist.

structured concurrency (StructuredTaskScope)
not finalpre-release 19
StructuredTaskScope.Joiner completion policies
not finalpre-release 25
ShutdownOnFailure and ShutdownOnSuccess subclasses
pre-release 19removed 25

Assumes JDK 27, where StructuredTaskScope is a preview API (an incubator API in JDK 19 and 20, preview since 21), policies are Joiners (since the JDK 25 preview) and join() throws ExecutionException. JDK 25 has the same Joiner shape but throws FailedException and names the race joiner anySuccessfulResultOrThrow(); the ShutdownOnFailure and ShutdownOnSuccess subclasses ran from the JDK 19 incubator through the JDK 24 preview.

context