Structured Concurrency

Joiner.allSuccessfulOrThrow() is the policy reached for most often: fork several subtasks that must all succeed for the overall unit of work to mean anything at all — fetching a user's profile and their account balance together, where there's no point rendering a page with only one of the two. The moment either fails, keeping the other one running is pure waste. Under this Joiner, the first subtask to fail triggers cancellation of every sibling automatically, and scope.join() itself throws — wrapping the original cause in a StructuredTaskScope.FailedException — rather than returning normally.

The opposite shape is Joiner.anySuccessfulResultOrThrow(): you don't need every subtask to succeed, you need any one of them to. This is the hedged-request pattern — ask several redundant sources the same question simultaneously, take whichever answers first, and stop caring about the rest. The moment one subtask succeeds, every other sibling is cancelled automatically, and scope.join() itself returns the winning result directly rather than requiring you to fetch it off a handle. This trades a small amount of extra load for a large reduction in worst-case latency — a well-documented technique for taming tail latency, since even a service that's fast on average occasionally takes far longer on an individual call. It should be reserved for idempotent, side-effect-free reads: a "losing" call may have already had a real-world effect before it gets cancelled.

Achieving either of these behaviors by hand with CompletableFuture means manually composing combinators and explicit cancel() calls across every branch. Here, that entire cancellation-propagation responsibility is handled by the Joiner itself — the code reads linearly, like ordinary sequential logic, because structurally it now behaves like ordinary sequential logic.

Reading state() or get() on a subtask handle before join() returns. This throws IllegalStateException immediately, by design — join() is the actual synchronization point that publishes every subtask's outcome safely to the owning thread, exactly analogous to a plain Thread.join()'s happens-before guarantee. There's no way around this; the outcome genuinely isn't safe to read until join() has returned.

Opening the StructuredTaskScope outside an active ScopedValue binding when the subtasks need that context. Structured subtasks correctly inherit a ScopedValue binding that's active in the dynamic scope the scope itself was opened within — but the nesting order matters and isn't cosmetic. If StructuredTaskScope.open() is called outside the ScopedValue.where(...).run(...) lambda that establishes the binding — or the binding has already closed before a subtask forked from that scope actually runs — reading the ScopedValue inside that subtask throws NoSuchElementException, the same fail-fast behavior a ScopedValue always has, now surfacing across a thread boundary instead of within one.

Using anySuccessfulResultOrThrow() for non-idempotent operations. The "losing" subtasks in a hedged race are cancelled, but cancellation happens after they've started running — a losing subtask that had already made a real side-effecting call (charging a card, sending a message) before being cancelled has still had that real-world effect. This pattern is safe specifically for idempotent, side-effect-free reads, not for writes or anything with an external effect that can't simply be discarded.

A Joiner is an interface, not a fixed pair of choices. allSuccessfulOrThrow() and anySuccessfulResultOrThrow() are simply the two most common built-in implementations of it, covering the overwhelming majority of real fan-out/fan-in code. But other shapes exist: "wait for at least 3 of 5 replicas to confirm a write" (a quorum), or "collect every outcome, successful or not, and report which ones failed" (partial success). A custom Joiner is notified as each forked subtask completes and decides two things: whether that particular completion should trigger cancelling the rest of the scope's subtasks, and what scope.join() should ultimately return or throw once the scope finishes collecting outcomes. A quorum-style Joiner, for instance, would count successes as they arrive and only signal "cancel the rest" once enough have accumulated — everything before that threshold behaves like the default no-cancellation Joiner. Because the two built-ins cover so much ground already, reaching for a custom one is genuinely uncommon — worth double-checking the defaults don't already fit before writing one.

ScopedValue propagation into structured subtasks works because it's tied to dynamic scope, not thread identity. A ScopedValue binding established via ScopedValue.where(...).run(...) is automatically visible to any structured subtask forked from a StructuredTaskScope opened within that binding's active extent — correctly, regardless of which thread (virtual or platform, freshly created or drawn from a carrier pool) ends up actually running that subtask. This is precisely the propagation guarantee InheritableThreadLocal could never provide for pooled threads, since that mechanism only ever copies a value at thread-construction time.