Summary

Update java.util.concurrent.StructuredTaskScope for JEP 505: Structured Concurrency (Fifth Preview).

Problem

StructuredTaskScope has a public constructor and requires subclassing to implement different policies/outcome. The API includes ShutdownOnFailure and ShutdownOnSuccess for common cases; developers can extend StructuredTaskScope to implement other policies and APIs that make available the outcome. This design put constraints on future evolution of the base class.

StructuredTaskScope::join does not propagate exceptions. When using ShutdownOnFailure you need to call throwIfFailed after joining, otherwise the exceptions are lost. This is a hazard.

Solution

The main changes to the API are:

• Change the API from using constructors to using static factory methods.

• Introduce a new interface named Joiner to handle subtask completion and produce the result for a main task waiting in the join method. Specifying a Joiner to the static open method in the updated API is equivalent to using a subclass in the existing API. The Joiner interface defines methods to obtain a Joiner for common cases.

• Remove ShutdownOnFailure and ShutdownOnSuccess.

• Change the join method so that it returns the outcome or throws.

In addition, there are a number of other small updates:

• The fork method is changed so that it cannot be called after joining.
• The join method is changed so that it can only be called once.
• Configuration that was provided with parameters for the constructor is changed so that it can be provided by a configuration function.
• joinUntil(Instant) is removed and replaced by allowing a timeout be configured by the configuration function. The scope is cancelled if the timeout expires before the scope is closed.
• join now throws StructuredTaskScope.FailedException or StructuredTaskScope.TimeoutException when the scope fails or the timeout elapses

Specification

A zip file of the API diffs is attached.

The API docs in the EA builds can also be browsed here: https://download.java.net/java/early_access/loom/docs/api/java.base/java/util/concurrent/StructuredTaskScope.html