Summary

Update the specification of java.util.concurrent.StructuredTaskScope.shutdown() to make it clear that the state of subtasks that complete around the time of shutdown is not defined.

Problem

The shutdown method is used for cases where the results of unfinished subtasks are no longer needed. The intention is that the subclass has captured any results/exceptions and then shuts down the scope as it doesn't care about the remaining subtasks.

Tests or nosy code that looks at the state of the remaining subtasks may observe a subtask state transition from "unavailable" to a terminal state (success or failed). This arises with subtasks that are completing around the time that the task scope is shutdown. The API docs could be a bit clearer on this point to avoid questions or bad tests.

Solution

Update the method description to make it clear that the state of subtasks that complete around the time of shutdown may change.

Specification

Add the following paragraph to the StructuredTaskScope.shutdown() method description:

+     * <p> The {@linkplain Subtask.State state} of unfinished subtasks that complete at
+     * around the time that the task scope is shutdown is not defined. A subtask that
+     * completes successfully with a result, or fails with an exception, at around
+     * the time that the task scope is shutdown may or may not <i>transition</i> to a
+     * terminal state.