RFR: 8367857: Implement JEP 525: Structured Concurrency (Sixth Preview)

[Viktor Klang]

On Fri, 19 Sep 2025 14:49:52 GMT, Alan Bateman <alanb at openjdk.org> wrote:

> Updates for JEP 525.
> 
> - The join method is changed to invoke `Joiner::onTimeout` if a timeout is configured and the timeout expires before or while waiting.
> - `Joiner.allUntil(Predicate`) is changed to allow join return the stream of all forked subtasks when the timeout expires.
> - The `join` method is now specified to allow it be called again if interrupted.
> - The configFunction parameter to the 3-arg open is changed from `Function<Configuration, Configuration>` to `UnaryOperator<Configuration>`.
> - Joiner is no longer a `@FunctionalInterface`.
> 
> Most of the changes are to API docs and tests. Some links are changed to use double hash mark.

src/java.base/share/classes/java/util/concurrent/StructuredTaskScope.java line 208:

> 206:  * with the <a id="DefaultConfiguration"> <em>default configuration</em></a>. The default
> 207:  * configuration has a {@code ThreadFactory} that creates unnamed {@linkplain
> 208:  * Thread##virtual-threads virtual threads}, is unnamed for monitoring and management

Is the second "unnamed" referring to the ThreadGroup itself? If so, it might be clearer to say "configuration has an unnamed ThreadFactory that creates unnamed virtual threads"

src/java.base/share/classes/java/util/concurrent/StructuredTaskScope.java line 242:

> 240:  * interrupts the threads executing the two subtasks) and the {@code Joiner}'s {@link
> 241:  * Joiner#onTimeout() onTimeout} method is invoked to throw {@link TimeoutException
> 242:  * TimeoutException}.

Might be worth mentioning that said TimeoutException will then propagate upon the invocation of STS::join()?

src/java.base/share/classes/java/util/concurrent/StructuredTaskScope.java line 499:

> 497:      * @apiNote It is very important that a new {@code Joiner} object is created for each
> 498:      * {@code StructuredTaskScope}. {@code Joiner} objects should never be shared with
> 499:      * different scopes or re-used after a scope is closed.

Nice catch!

src/java.base/share/classes/java/util/concurrent/StructuredTaskScope.java line 1069:

> 1067:      * invoked to optionally throw {@link TimeoutException TimeoutException}. If the
> 1068:      * {@code onTimeout} method throws another exception or error then it is propagated
> 1069:      * by this method. Once finished waiting, and {@code onTimeout} does not throw, the

Might be worth clarifying "Once finished waiting," to clarify what it is waiting for.

test/jdk/java/util/concurrent/StructuredTaskScope/StructuredTaskScopeTest.java line 1048:

> 1046:     void testOnTimeoutInvoked() throws Exception {
> 1047:         var scopeRef = new AtomicReference<StructuredTaskScope<?, ?>>();
> 1048:         Thread owner = Thread.currentThread();

Suggestion:

        var owner = Thread.currentThread();

test/jdk/java/util/concurrent/StructuredTaskScope/StructuredTaskScopeTest.java line 1669:

> 1667:             assertEquals(2, subtasks.size());
> 1668:             assertSame(subtask1, subtasks.get(0));
> 1669:             assertSame(subtask2, subtasks.get(1));

Suggestion:

            assertEquals(List.of(subtask1, subtask2), subtasks);

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/27392#discussion_r2371596118
PR Review Comment: https://git.openjdk.org/jdk/pull/27392#discussion_r2371600873
PR Review Comment: https://git.openjdk.org/jdk/pull/27392#discussion_r2371607212
PR Review Comment: https://git.openjdk.org/jdk/pull/27392#discussion_r2371730054
PR Review Comment: https://git.openjdk.org/jdk/pull/27392#discussion_r2371809709
PR Review Comment: https://git.openjdk.org/jdk/pull/27392#discussion_r2371818362