JEP 525 Brings Timeout Handling and Joiner Refinements to Java’s Structured Concurrency

JEP 525, Structured Concurrency (Sixth Preview) has been completed for the upcoming JDK 26 release. JEP 525 continues the evolution of the structured concurrency API that has been refined across multiple preview rounds since JDK 21, aiming to make concurrent task management clearer, safer, and easier to reason about than traditional ExecutorService/Future patterns. While this iteration makes minor but useful tweaks, the core model remains stable.

Structured concurrency treats groups of related tasks as a single unit of work, improving cancellation, error propagation, and observability compared to ad-hoc thread management. The API centers on java.util.concurrent.StructuredTaskScope and the Joiner abstraction, which controls how and when results from forked subtasks are combined.

Unlike Preview 5, which replaced constructors with static factory methods and introduced richer Joiner policies, Preview 6 focuses on a set of small, incremental refinements to the API.

Structured concurrency scopes can be configured with a timeout. Prior to this preview, a timed-out scope.join() would immediately throw a TimeoutException. Preview 6 introduces a new onTimeout() callback on Joiner, letting custom joiners react to timeouts and return partial or fallback results instead of always throwing. This allows custom joiners to determine how structured concurrent work completes under time constraints.

The common joiner Joiner.allSuccessfulOrThrow() now returns a List<T> directly from scope.join() rather than a stream of Subtask handles. This reduces boilerplate for common use cases.

anySuccessfulResultOrThrow() has been renamed to anySuccessfulOrThrow() for brevity and clarity; the behavior remains the same (return the first successful result, cancel others).

The overload of StructuredTaskScope.open() that accepts a configuration modifier now expects a UnaryOperator<Configuration> instead of a Function, tightening the API and preventing unintended type mixing.

The basic usage pattern remains unchanged. A structured task scope is opened, related subtasks are forked, typically on virtual threads, and completion is awaited by invoking join(). The scope ensures that all subtasks are either completed or cancelled when the block exits.

try (var scope = StructuredTaskScope.open()) {
  var user = scope.fork(() -> fetchUser(userId));
  var order = scope.fork(() -> fetchOrder(userId));
  scope.join(); // wait for all subtasks
  String name = user.get();
  int count = order.get();
}

When a timeout is configured, a custom joiner may handle the timeout and return partial results rather than causing join() to fail with an exception.

class PartialCollector<T> implements StructuredTaskScope.Joiner<T, List<T>> {
  private final Queue<T> results = new ConcurrentLinkedQueue<>();

  @Override
  public boolean onComplete(StructuredTaskScope.Subtask<T> st) {
    if (st.state() == StructuredTaskScope.Subtask.State.SUCCESS) {
      results.add(st.get());
    }
    return false;
  }

  @Override
  public void onTimeout() {
    IO.println("Timed out, returning partial results");
  }

  @Override
  public List<T> result() {
    return List.copyOf(results);
  }
}

try (var scope = StructuredTaskScope.open(
    new PartialCollector<String>(),
    cfg -> cfg.withTimeout(Duration.ofSeconds(1)))) {
  scope.fork(() -> fetchA());
  scope.fork(() -> fetchB());
  List<String> partial = scope.join(); // partial results on timeout
  IO.println("Partial results: " + partial);
}

In this example, the custom joiner collects completed subtasks and returns the accumulated results when the scope times out, rather than failing the operation with a TimeoutException.

Preview 6 does not significantly change the API introduced in preview 5, but instead focuses on reducing friction and improving flexibility in common usage patterns. The new timeout hook enables more graceful handling of slow or unpredictable subtasks without weakening structured guarantees. Returning results as a list rather than a stream simplifies result handling, while consistent naming and tighter configuration APIs further polish the overall design.

For teams experimenting with virtual threads and structured task scopes, these refinements address friction observed in earlier previews while the feature remains in preview.

Structured concurrency is a key component of Project Loom’s broader concurrency roadmap. Used together with virtual threads, it enables a structured approach to managing related concurrent tasks with well-defined lifetimes. Preview 6 continues the iterative preview process, with changes informed by feedback from earlier previews.

Developers can experiment with structured concurrency by enabling preview features (--enable-preview) in JDK 26 early-access builds and provide feedback via the OpenJDK mailing lists.