8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.util.concurrent;
26
27 import java.time.Duration;
28 import java.util.function.Function;
29 import java.util.function.Predicate;
30 import java.util.function.Supplier;
31 import java.util.stream.Stream;
32 import jdk.internal.javac.PreviewFeature;
33
34 /**
35 * An API for <em>structured concurrency</em>. {@code StructuredTaskScope} supports cases
36 * where execution of a <em>task</em> (a unit of work) splits into several concurrent
37 * subtasks, and where the subtasks must complete before the task continues. A {@code
38 * StructuredTaskScope} can be used to ensure that the lifetime of a concurrent operation
39 * is confined by a <em>syntax block</em>, similar to that of a sequential operation in
40 * structured programming.
41 *
42 * <p> {@code StructuredTaskScope} defines the static method {@link #open() open} to open
43 * a new {@code StructuredTaskScope} and the {@link #close() close} method to close it.
44 * The API is designed to be used with the {@code try}-with-resources statement where
45 * the {@code StructuredTaskScope} is opened as a resource and then closed automatically.
46 * The code inside the block uses the {@link #fork(Callable) fork} method to fork subtasks.
47 * After forking, it uses the {@link #join() join} method to wait for all subtasks to
48 * finish (or some other outcome) as a single operation. Forking a subtask starts a new
49 * {@link Thread} to run the subtask. The thread executing the task does not continue
50 * beyond the {@code close} method until all threads started to execute subtasks have finished.
51 * To ensure correct usage, the {@code fork}, {@code join} and {@code close} methods may
52 * only be invoked by the <em>owner thread</em> (the thread that opened the {@code
53 * StructuredTaskScope}), the {@code fork} method may not be called after {@code join},
54 * the {@code join} method may only be invoked once, and the {@code close} method throws
55 * an exception after closing if the owner did not invoke the {@code join} method after
56 * forking subtasks.
57 *
58 * <p> As a first example, consider a task that splits into two subtasks to concurrently
59 * fetch resources from two URL locations "left" and "right". Both subtasks may complete
60 * successfully, one subtask may succeed and the other may fail, or both subtasks may
61 * fail. The task in this example is interested in the successful result from both
62 * subtasks. It waits in the {@link #join() join} method for both subtasks to complete
63 * successfully or for either subtask to fail.
64 * {@snippet lang=java :
65 * // @link substring="open" target="#open()" :
66 * try (var scope = StructuredTaskScope.open()) {
67 *
68 * // @link substring="fork" target="#fork(Callable)" :
69 * Subtask<String> subtask1 = scope.fork(() -> query(left));
70 * Subtask<Integer> subtask2 = scope.fork(() -> query(right));
71 *
72 * // throws if either subtask fails
73 * scope.join(); // @link substring="join" target="#join()"
74 *
75 * // both subtasks completed successfully
76 * // @link substring="get" target="Subtask#get()" :
90 * <p> To allow for cancellation, subtasks must be coded so that they finish as soon as
91 * possible when interrupted. Subtasks that do not respond to interrupt, e.g. block on
92 * methods that are not interruptible, may delay the closing of a scope indefinitely. The
93 * {@link #close() close} method always waits for threads executing subtasks to finish,
94 * even if the scope is cancelled, so execution cannot continue beyond the {@code close}
95 * method until the interrupted threads finish.
96 *
97 * <p> In the example, the subtasks produce results of different types ({@code String} and
98 * {@code Integer}). In other cases the subtasks may all produce results of the same type.
99 * If the example had used {@code StructuredTaskScope.<String>open()} then it could
100 * only be used to fork subtasks that return a {@code String} result.
101 *
102 * <h2>Joiners</h2>
103 *
104 * <p> In the example above, the task fails if any subtask fails. If all subtasks
105 * succeed then the {@code join} method completes normally. Other policy and outcome is
106 * supported by creating a {@code StructuredTaskScope} with a {@link Joiner} that
107 * implements the desired policy. A {@code Joiner} handles subtask completion and produces
108 * the outcome for the {@link #join() join} method. In the example above, {@code join}
109 * returns {@code null}. Depending on the {@code Joiner}, {@code join} may return a
110 * result, a stream of elements, or some other object. The {@code Joiner} interface defines
111 * factory methods to create {@code Joiner}s for some common cases.
112 *
113 * <p> A {@code Joiner} may <a id="Cancallation">cancel</a> the scope (sometimes called
114 * "short-circuiting") when some condition is reached that does not require the result of
115 * subtasks that are still executing. Cancelling the scope prevents new threads from being
116 * started to execute further subtasks, {@linkplain Thread#interrupt() interrupts} the
117 * threads executing subtasks that have not completed, and causes the {@code join} method
118 * to wakeup with the outcome (result or exception). In the above example, the outcome is
119 * that {@code join} completes with a result of {@code null} when all subtasks succeed.
120 * The scope is cancelled if any of the subtasks fail and {@code join} throws {@code
121 * FailedException} with the exception from the failed subtask as the cause. Other {@code
122 * Joiner} implementations may cancel the scope for other reasons.
123 *
124 * <p> Now consider another example that splits into two subtasks. In this example,
125 * each subtask produces a {@code String} result and the task is only interested in
126 * the result from the first subtask to complete successfully. The example uses {@link
127 * Joiner#anySuccessfulResultOrThrow() Joiner.anySuccessfulResultOrThrow()} to
128 * create a {@code Joiner} that makes available the result of the first subtask to
129 * complete successfully. The type parameter in the example is "{@code String}" so that
130 * only subtasks that return a {@code String} can be forked.
131 * {@snippet lang=java :
132 * // @link substring="open" target="#open(Joiner)" :
133 * try (var scope = StructuredTaskScope.open(Joiner.<String>anySuccessfulResultOrThrow())) {
134 *
135 * scope.fork(callable1);
136 * scope.fork(callable2);
137 *
138 * // throws if both subtasks fail
139 * String firstResult = scope.join();
140 *
141 * }
142 * }
143 *
144 * <p> In the example, the task forks the two subtasks, then waits in the {@code
145 * join} method for either subtask to complete successfully or for both subtasks to fail.
146 * If one of the subtasks completes successfully then the {@code Joiner} causes the other
147 * subtask to be cancelled (this will interrupt the thread executing the subtask), and
148 * the {@code join} method returns the result from the successful subtask. Cancelling the
149 * other subtask avoids the task waiting for a result that it doesn't care about. If
150 * both subtasks fail then the {@code join} method throws {@code FailedException} with the
151 * exception from one of the subtasks as the {@linkplain Throwable#getCause() cause}.
152 *
153 * <p> Whether code uses the {@code Subtask} returned from {@code fork} will depend on
154 * the {@code Joiner} and usage. Some {@code Joiner} implementations are suited to subtasks
155 * that return results of the same type and where the {@code join} method returns a result
156 * for the task to use. Code that forks subtasks that return results of different
157 * types, and uses a {@code Joiner} such as {@code Joiner.awaitAllSuccessfulOrThrow()} that
158 * does not return a result, will use {@link Subtask#get() Subtask.get()} after joining.
159 *
160 * <h2>Exception handling</h2>
161 *
162 * <p> A {@code StructuredTaskScope} is opened with a {@link Joiner Joiner} that
163 * handles subtask completion and produces the outcome for the {@link #join() join} method.
164 * In some cases, the outcome will be a result, in other cases it will be an exception.
165 * If the outcome is an exception then the {@code join} method throws {@link
166 * FailedException} with the exception as the {@linkplain Throwable#getCause()
167 * cause}. For many {@code Joiner} implementations, the exception will be an exception
168 * thrown by a subtask that failed. In the case of {@link Joiner#allSuccessfulOrThrow()
169 * allSuccessfulOrThrow} and {@link Joiner#awaitAllSuccessfulOrThrow() awaitAllSuccessfulOrThrow}
170 * for example, the exception is from the first subtask to fail.
171 *
172 * <p> Many of the details for how exceptions are handled will depend on usage. In some
173 * cases it may be useful to add a {@code catch} block to the {@code try}-with-resources
174 * statement to catch {@code FailedException}. The exception handling may use {@code
175 * instanceof} with pattern matching to handle specific causes.
176 * {@snippet lang=java :
177 * try (var scope = StructuredTaskScope.open()) {
178 *
181 * } catch (StructuredTaskScope.FailedException e) {
182 *
183 * Throwable cause = e.getCause();
184 * switch (cause) {
185 * case IOException ioe -> ..
186 * default -> ..
187 * }
188 *
189 * }
190 * }
191 * In other cases it may not be useful to catch {@code FailedException} but instead leave
192 * it to propagate to the configured {@linkplain Thread.UncaughtExceptionHandler uncaught
193 * exception handler} for logging purposes.
194 *
195 * <p> For cases where a specific exception triggers the use of a default result then it
196 * may be more appropriate to handle this in the subtask itself rather than the subtask
197 * failing and the scope owner handling the exception.
198 *
199 * <h2>Configuration</h2>
200 *
201 *
202 * A {@code StructuredTaskScope} is opened with {@linkplain Configuration configuration}
203 * that consists of a {@link ThreadFactory} to create threads, an optional name for
204 * monitoring and management purposes, and an optional timeout.
205 *
206 * <p> The {@link #open()} and {@link #open(Joiner)} methods create a {@code StructuredTaskScope}
207 * with the <a id="DefaultConfiguration"> <em>default configuration</em></a>. The default
208 * configuration has a {@code ThreadFactory} that creates unnamed
209 * <a href="{@docRoot}/java.base/java/lang/Thread.html#virtual-threads">virtual threads</a>,
210 * is unnamed for monitoring and management purposes, and has no timeout.
211 *
212 * <p> The 2-arg {@link #open(Joiner, Function) open} method can be used to create a
213 * {@code StructuredTaskScope} that uses a different {@code ThreadFactory}, has a name for
214 * the purposes of monitoring and management, or has a timeout that cancels the scope if
215 * the timeout expires before or while waiting for subtasks to complete. The {@code open}
216 * method is called with a {@linkplain Function function} that is applied to the default
217 * configuration and returns a {@link Configuration Configuration} for the
218 * {@code StructuredTaskScope} under construction.
219 *
220 * <p> The following example opens a new {@code StructuredTaskScope} with a {@code
221 * ThreadFactory} that creates virtual threads {@linkplain Thread#setName(String) named}
222 * "duke-0", "duke-1" ...
223 * {@snippet lang = java:
224 * // @link substring="name" target="Thread.Builder#name(String, long)" :
225 * ThreadFactory factory = Thread.ofVirtual().name("duke-", 0).factory();
226 *
227 * // @link substring="withThreadFactory" target="Configuration#withThreadFactory(ThreadFactory)" :
228 * try (var scope = StructuredTaskScope.open(joiner, cf -> cf.withThreadFactory(factory))) {
229 *
230 * scope.fork( .. ); // runs in a virtual thread with name "duke-0"
231 * scope.fork( .. ); // runs in a virtual thread with name "duke-1"
232 *
233 * scope.join();
234 *
235 * }
236 *}
237 *
238 * <p> A second example sets a timeout, represented by a {@link Duration}. The timeout
239 * starts when the new scope is opened. If the timeout expires before the {@code join}
240 * method has completed then the scope is <a href="#Cancallation">cancelled</a>. This
241 * interrupts the threads executing the two subtasks and causes the {@link #join() join}
242 * method to throw {@link TimeoutException}.
243 * {@snippet lang=java :
244 * Duration timeout = Duration.ofSeconds(10);
245 *
246 * // @link substring="allSuccessfulOrThrow" target="Joiner#allSuccessfulOrThrow()" :
247 * try (var scope = StructuredTaskScope.open(Joiner.<String>allSuccessfulOrThrow(),
248 * // @link substring="withTimeout" target="Configuration#withTimeout(Duration)" :
249 * cf -> cf.withTimeout(timeout))) {
250 *
251 * scope.fork(callable1);
252 * scope.fork(callable2);
253 *
254 * List<String> result = scope.join()
255 * .map(Subtask::get)
256 * .toList();
257 *
258 * }
259 * }
260 *
261 * <h2>Inheritance of scoped value bindings</h2>
262 *
263 * {@link ScopedValue} supports the execution of a method with a {@code ScopedValue} bound
264 * to a value for the bounded period of execution of the method by the <em>current thread</em>.
265 * It allows a value to be safely and efficiently shared to methods without using method
266 * parameters.
267 *
268 * <p> When used in conjunction with a {@code StructuredTaskScope}, a {@code ScopedValue}
269 * can also safely and efficiently share a value to methods executed by subtasks forked
270 * in the scope. When a {@code ScopedValue} object is bound to a value in the thread
271 * executing the task then that binding is inherited by the threads created to
272 * execute the subtasks. The thread executing the task does not continue beyond the
273 * {@link #close() close} method until all threads executing the subtasks have finished.
274 * This ensures that the {@code ScopedValue} is not reverted to being {@linkplain
275 * ScopedValue#isBound() unbound} (or its previous value) while subtasks are executing.
276 * In addition to providing a safe and efficient means to inherit a value into subtasks,
297 * USERNAME, then value "duke" will be returned.
298 * {@snippet lang=java :
299 * // @link substring="newInstance" target="ScopedValue#newInstance()" :
300 * private static final ScopedValue<String> USERNAME = ScopedValue.newInstance();
301 *
302 * // @link substring="where" target="ScopedValue#where(ScopedValue, Object)" :
303 * MyResult result = ScopedValue.where(USERNAME, "duke").call(() -> {
304 *
305 * try (var scope = StructuredTaskScope.open()) {
306 *
307 * Subtask<String> subtask1 = scope.fork( .. ); // inherits binding
308 * Subtask<Integer> subtask2 = scope.fork( .. ); // inherits binding
309 *
310 * scope.join();
311 * return new MyResult(subtask1.get(), subtask2.get());
312 * }
313 *
314 * });
315 * }
316 *
317 * <p> A scoped value inherited into a subtask may be
318 * <a href="{@docRoot}/java.base/java/lang/ScopedValue.html#rebind">rebound</a> to a new
319 * value in the subtask for the bounded execution of some method executed in the subtask.
320 * When the method completes, the value of the {@code ScopedValue} reverts to its previous
321 * value, the value inherited from the thread executing the task.
322 *
323 * <p> A subtask may execute code that itself opens a new {@code StructuredTaskScope}.
324 * A task executing in thread T1 opens a {@code StructuredTaskScope} and forks a
325 * subtask that runs in thread T2. The scoped value bindings captured when T1 opens the
326 * scope are inherited into T2. The subtask (in thread T2) executes code that opens a
327 * new {@code StructuredTaskScope} and forks a subtask that runs in thread T3. The scoped
328 * value bindings captured when T2 opens the scope are inherited into T3. These
329 * include (or may be the same) as the bindings that were inherited from T1. In effect,
330 * scoped values are inherited into a tree of subtasks, not just one level of subtask.
331 *
332 * <h2>Memory consistency effects</h2>
333 *
334 * <p> Actions in the owner thread of a {@code StructuredTaskScope} prior to
335 * {@linkplain #fork forking} of a subtask
336 * <a href="{@docRoot}/java.base/java/util/concurrent/package-summary.html#MemoryVisibility">
337 * <i>happen-before</i></a> any actions taken by that subtask, which in turn
338 * <i>happen-before</i> the subtask result is {@linkplain Subtask#get() retrieved}.
339 *
340 * <h2>General exceptions</h2>
341 *
342 * <p> Unless otherwise specified, passing a {@code null} argument to a method in this
343 * class will cause a {@link NullPointerException} to be thrown.
344 *
345 * @param <T> the result type of subtasks executed in the scope
346 * @param <R> the result type of the scope
347 *
348 * @jls 17.4.5 Happens-before Order
349 * @since 21
350 */
351 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
352 public sealed interface StructuredTaskScope<T, R>
353 extends AutoCloseable
354 permits StructuredTaskScopeImpl {
355
356 /**
357 * Represents a subtask forked with {@link #fork(Callable)} or {@link #fork(Runnable)}.
358 *
388 /**
389 * The subtask failed with an exception. The {@link Subtask#exception()
390 * Subtask.exception()} method can be used to get the exception. This is a
391 * terminal state.
392 */
393 FAILED,
394 }
395
396 /**
397 * {@return the subtask state}
398 */
399 State state();
400
401 /**
402 * Returns the result of this subtask if it completed successfully. If the subtask
403 * was forked with {@link #fork(Callable) fork(Callable)} then the result from the
404 * {@link Callable#call() call} method is returned. If the subtask was forked with
405 * {@link #fork(Runnable) fork(Runnable)} then {@code null} is returned.
406 *
407 * <p> Code executing in the scope owner thread can use this method to get the
408 * result of a successful subtask only after it has {@linkplain #join() joined}.
409 *
410 * <p> Code executing in the {@code Joiner} {@link Joiner#onComplete(Subtask)
411 * onComplete} method should test that the {@linkplain #state() subtask state} is
412 * {@link State#SUCCESS SUCCESS} before using this method to get the result.
413 *
414 * @return the possibly-null result
415 * @throws IllegalStateException if the subtask has not completed, did not complete
416 * successfully, or the current thread is the scope owner invoking this
417 * method before {@linkplain #join() joining}
418 * @see State#SUCCESS
419 */
420 T get();
421
422 /**
423 * {@return the exception or error thrown by this subtask if it failed}
424 * If the subtask was forked with {@link #fork(Callable) fork(Callable)} then the
425 * exception or error thrown by the {@link Callable#call() call} method is returned.
426 * If the subtask was forked with {@link #fork(Runnable) fork(Runnable)} then the
427 * exception or error thrown by the {@link Runnable#run() run} method is returned.
428 *
429 * <p> Code executing in the scope owner thread can use this method to get the
430 * exception thrown by a failed subtask only after it has {@linkplain #join() joined}.
431 *
432 * <p> Code executing in a {@code Joiner} {@link Joiner#onComplete(Subtask)
433 * onComplete} method should test that the {@linkplain #state() subtask state} is
434 * {@link State#FAILED FAILED} before using this method to get the exception.
435 *
436 * @throws IllegalStateException if the subtask has not completed, completed with
437 * a result, or the current thread is the scope owner invoking this method
438 * before {@linkplain #join() joining}
439 * @see State#FAILED
440 */
441 Throwable exception();
442 }
443
444 /**
445 * An object used with a {@link StructuredTaskScope} to handle subtask completion and
446 * produce the result for the scope owner waiting in the {@link #join() join} method
447 * for subtasks to complete.
448 *
449 * <p> Joiner defines static methods to create {@code Joiner} objects for common cases:
450 * <ul>
451 * <li> {@link #allSuccessfulOrThrow() allSuccessfulOrThrow()} creates a {@code Joiner}
452 * that yields a stream of the completed subtasks for {@code join} to return when
453 * all subtasks complete successfully. It cancels the scope and causes {@code join}
454 * to throw if any subtask fails.
455 * <li> {@link #anySuccessfulResultOrThrow() anySuccessfulResultOrThrow()} creates a
456 * {@code Joiner} that yields the result of the first subtask to succeed for {@code
457 * join} to return. It causes {@code join} to throw if all subtasks fail.
458 * <li> {@link #awaitAllSuccessfulOrThrow() awaitAllSuccessfulOrThrow()} creates a
459 * {@code Joiner} that waits for all successful subtasks. It cancels the scope and
460 * causes {@code join} to throw if any subtask fails.
461 * <li> {@link #awaitAll() awaitAll()} creates a {@code Joiner} that waits for all
462 * subtasks. It does not cancel the scope or cause {@code join} to throw.
463 * </ul>
464 *
465 * <p> In addition to the methods to create {@code Joiner} objects for common cases,
466 * the {@link #allUntil(Predicate) allUntil(Predicate)} method is defined to create a
467 * {@code Joiner} that yields a stream of all subtasks. It is created with a {@link
468 * Predicate Predicate} that determines if the scope should continue or be cancelled.
469 * This {@code Joiner} can be built upon to create custom policies that cancel the
470 * scope based on some condition.
471 *
472 * <p> More advanced policies can be developed by implementing the {@code Joiner}
473 * interface. The {@link #onFork(Subtask)} method is invoked when subtasks are forked.
474 * The {@link #onComplete(Subtask)} method is invoked when subtasks complete with a
475 * result or exception. These methods return a {@code boolean} to indicate if scope
476 * should be cancelled. These methods can be used to collect subtasks, results, or
477 * exceptions, and control when to cancel the scope. The {@link #result()} method
478 * must be implemented to produce the result (or exception) for the {@code join}
479 * method.
480 *
481 * <p> Unless otherwise specified, passing a {@code null} argument to a method
482 * in this class will cause a {@link NullPointerException} to be thrown.
483 *
484 * @implSpec Implementations of this interface must be thread safe. The {@link
485 * #onComplete(Subtask)} method defined by this interface may be invoked by several
486 * threads concurrently.
487 *
488 * @apiNote It is very important that a new {@code Joiner} object is created for each
489 * {@code StructuredTaskScope}. {@code Joiner} objects should never be shared with
490 * different scopes or re-used after a task is closed.
491 *
492 * <p> Designing a {@code Joiner} should take into account the code at the use-site
493 * where the results from the {@link StructuredTaskScope#join() join} method are
494 * processed. It should be clear what the {@code Joiner} does vs. the application
495 * code at the use-site. In general, the {@code Joiner} implementation is not the
496 * place for "business logic". A {@code Joiner} should be designed to be as general
497 * purpose as possible.
498 *
499 * @param <T> the result type of subtasks executed in the scope
500 * @param <R> the result type of the scope
501 * @since 25
502 * @see #open(Joiner)
503 */
504 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
505 @FunctionalInterface
506 interface Joiner<T, R> {
507 /**
508 * Invoked by {@link #fork(Callable) fork(Callable)} and {@link #fork(Runnable)
509 * fork(Runnable)} when forking a subtask. The method is invoked from the task
510 * owner thread. The method is invoked before a thread is created to run the
511 * subtask.
512 *
513 * @implSpec The default implementation throws {@code NullPointerException} if the
514 * subtask is {@code null}. It throws {@code IllegalArgumentException} if the
515 * subtask is not in the {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state, it
516 * otherwise returns {@code false}.
517 *
518 * @apiNote This method is invoked by the {@code fork} methods. It should not be
519 * invoked directly.
520 *
521 * @param subtask the subtask
522 * @return {@code true} to cancel the scope, otherwise {@code false}
523 */
524 default boolean onFork(Subtask<? extends T> subtask) {
525 if (subtask.state() != Subtask.State.UNAVAILABLE) {
526 throw new IllegalArgumentException("Subtask not in UNAVAILABLE state");
527 }
528 return false;
529 }
530
531 /**
532 * Invoked by the thread started to execute a subtask after the subtask completes
533 * successfully or fails with an exception. This method is not invoked if a
534 * subtask completes after the scope is cancelled.
535 *
536 * @implSpec The default implementation throws {@code NullPointerException} if the
537 * subtask is {@code null}. It throws {@code IllegalArgumentException} if the
538 * subtask is not in the {@link Subtask.State#SUCCESS SUCCESS} or {@link
539 * Subtask.State#FAILED FAILED} state, it otherwise returns {@code false}.
540 *
541 * @apiNote This method is invoked by subtasks when they complete. It should not
542 * be invoked directly.
543 *
544 * @param subtask the subtask
545 * @return {@code true} to cancel the scope, otherwise {@code false}
546 */
547 default boolean onComplete(Subtask<? extends T> subtask) {
548 if (subtask.state() == Subtask.State.UNAVAILABLE) {
549 throw new IllegalArgumentException("Subtask has not completed");
550 }
551 return false;
552 }
553
554 /**
555 * Invoked by the {@link #join() join()} method to produce the result (or exception)
556 * after waiting for all subtasks to complete or the scope cancelled. The result
557 * from this method is returned by the {@code join} method. If this method throws,
558 * then {@code join} throws {@link FailedException} with the exception thrown by
559 * this method as the cause.
560 *
561 * <p> In normal usage, this method will be called at most once by the {@code join}
562 * method to produce the result (or exception). The behavior of this method when
563 * invoked directly, and invoked more than once, is undefined. Where possible, an
564 * implementation should return an equal result (or throw the same exception) on
565 * second or subsequent calls to produce the outcome.
566 *
567 * @apiNote This method is invoked by the {@code join} method. It should not be
568 * invoked directly.
569 *
570 * @return the result
571 * @throws Throwable the exception
572 */
573 R result() throws Throwable;
574
575 /**
576 * {@return a new Joiner object that yields a stream of all subtasks when all
577 * subtasks complete successfully}
578 * The {@code Joiner} <a href="StructuredTaskScope.html#Cancallation">cancels</a>
579 * the scope and causes {@code join} to throw if any subtask fails.
580 *
581 * <p> If all subtasks complete successfully, the joiner's {@link Joiner#result()}
582 * method returns a stream of all subtasks in the order that they were forked.
583 * If any subtask failed then the {@code result} method throws the exception from
584 * the first subtask to fail.
585 *
586 * @apiNote Joiners returned by this method are suited to cases where all subtasks
587 * return a result of the same type. Joiners returned by {@link
588 * #awaitAllSuccessfulOrThrow()} are suited to cases where the subtasks return
589 * results of different types.
590 *
591 * @param <T> the result type of subtasks
592 */
593 static <T> Joiner<T, Stream<Subtask<T>>> allSuccessfulOrThrow() {
594 return new Joiners.AllSuccessful<>();
595 }
596
597 /**
598 * {@return a new Joiner object that yields the result of any subtask that
599 * completed successfully}
600 * The {@code Joiner} causes {@code join} to throw if all subtasks fail.
601 *
602 * <p> The joiner's {@link Joiner#result()} method returns the result of a subtask
603 * that completed successfully. If all subtasks fail then the {@code result} method
604 * throws the exception from one of the failed subtasks. The {@code result} method
605 * throws {@code NoSuchElementException} if no subtasks were forked.
606 *
607 * @param <T> the result type of subtasks
608 */
609 static <T> Joiner<T, T> anySuccessfulResultOrThrow() {
610 return new Joiners.AnySuccessful<>();
611 }
612
613 /**
614 * {@return a new Joiner object that waits for subtasks to complete successfully}
615 * The {@code Joiner} <a href="StructuredTaskScope.html#Cancallation">cancels</a>
616 * the scope and causes {@code join} to throw if any subtask fails.
617 *
618 * <p> The joiner's {@link Joiner#result() result} method returns {@code null}
619 * if all subtasks complete successfully, or throws the exception from the first
620 * subtask to fail.
621 *
622 * @apiNote Joiners returned by this method are suited to cases where subtasks
623 * return results of different types. Joiners returned by {@link #allSuccessfulOrThrow()}
624 * are suited to cases where the subtasks return a result of the same type.
625 *
626 * @param <T> the result type of subtasks
627 */
628 static <T> Joiner<T, Void> awaitAllSuccessfulOrThrow() {
629 return new Joiners.AwaitSuccessful<>();
630 }
631
632 /**
633 * {@return a new Joiner object that waits for all subtasks to complete}
634 * The {@code Joiner} does not cancel the scope if a subtask fails.
635 *
636 * <p> The joiner's {@link Joiner#result() result} method returns {@code null}.
637 *
638 * @apiNote This Joiner is useful for cases where subtasks make use of
639 * <em>side-effects</em> rather than return results or fail with exceptions.
640 * The {@link #fork(Runnable) fork(Runnable)} method can be used to fork subtasks
641 * that do not return a result.
642 *
643 * <p> This Joiner can also be used for <em>fan-in</em> scenarios where subtasks
644 * are forked to handle incoming connections and the number of subtasks is unbounded.
645 * In this example, the thread executing the {@code acceptLoop} method will only
646 * stop when interrupted or the listener socket is closed asynchronously.
647 * {@snippet lang=java :
648 * void acceptLoop(ServerSocket listener) throws IOException, InterruptedException {
649 * try (var scope = StructuredTaskScope.open(Joiner.<Socket>awaitAll())) {
650 * while (true) {
651 * Socket socket = listener.accept();
652 * scope.fork(() -> handle(socket));
653 * }
654 * }
655 * }
656 * }
657 *
658 * @param <T> the result type of subtasks
659 */
660 static <T> Joiner<T, Void> awaitAll() {
661 // ensure that new Joiner object is returned
662 return new Joiner<T, Void>() {
663 @Override
664 public Void result() {
665 return null;
666 }
667 };
668 }
669
670 /**
671 * {@return a new Joiner object that yields a stream of all subtasks when all
672 * subtasks complete or a predicate returns {@code true} to cancel the scope}
673 *
674 * <p> The joiner's {@link Joiner#onComplete(Subtask)} method invokes the
675 * predicate's {@link Predicate#test(Object) test} method with the subtask that
676 * completed successfully or failed with an exception. If the {@code test} method
677 * returns {@code true} then <a href="StructuredTaskScope.html#Cancallation">
678 * the scope is cancelled</a>. The {@code test} method must be thread safe as it
679 * may be invoked concurrently from several threads. If the {@code test} method
680 * completes with an exception or error, then the thread that executed the subtask
681 * invokes the {@linkplain Thread.UncaughtExceptionHandler uncaught exception handler}
682 * with the exception or error before the thread terminates.
683 *
684 * <p> The joiner's {@link #result()} method returns the stream of all subtasks,
685 * in fork order. The stream may contain subtasks that have completed
686 * (in {@link Subtask.State#SUCCESS SUCCESS} or {@link Subtask.State#FAILED FAILED}
687 * state) or subtasks in the {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state
688 * if the scope was cancelled before all subtasks were forked or completed.
689 *
690 * <p> The following example uses this method to create a {@code Joiner} that
691 * <a href="StructuredTaskScope.html#Cancallation">cancels</a> the scope when
692 * two or more subtasks fail.
693 * {@snippet lang=java :
694 * class CancelAfterTwoFailures<T> implements Predicate<Subtask<? extends T>> {
695 * private final AtomicInteger failedCount = new AtomicInteger();
696 * @Override
697 * public boolean test(Subtask<? extends T> subtask) {
698 * return subtask.state() == Subtask.State.FAILED
699 * && failedCount.incrementAndGet() >= 2;
700 * }
701 * }
702 *
703 * var joiner = Joiner.allUntil(new CancelAfterTwoFailures<String>());
704 * }
705 *
706 * <p> The following example uses {@code allUntil} to wait for all subtasks to
707 * complete without any cancellation. This is similar to {@link #awaitAll()}
708 * except that it yields a list of the completed subtasks.
709 * {@snippet lang=java :
710 * <T> List<Subtask<T>> invokeAll(Collection<Callable<T>> tasks) throws InterruptedException {
711 * try (var scope = StructuredTaskScope.open(Joiner.<T>allUntil(_ -> false))) {
712 * tasks.forEach(scope::fork);
713 * return scope.join().toList();
714 * }
715 * }
716 * }
717 *
718 * @param isDone the predicate to evaluate completed subtasks
719 * @param <T> the result type of subtasks
720 */
721 static <T> Joiner<T, Stream<Subtask<T>>> allUntil(Predicate<Subtask<? extends T>> isDone) {
722 return new Joiners.AllSubtasks<>(isDone);
723 }
724 }
725
726 /**
727 * Represents the configuration for a {@code StructuredTaskScope}.
728 *
729 * <p> The configuration for a {@code StructuredTaskScope} consists of a {@link
730 * ThreadFactory} to create threads, an optional name for the purposes of monitoring
731 * and management, and an optional timeout.
732 *
733 * <p> Creating a {@code StructuredTaskScope} with {@link #open()} or {@link #open(Joiner)}
734 * uses the <a href="StructuredTaskScope.html#DefaultConfiguration">default
735 * configuration</a>. The default configuration consists of a thread factory that
736 * creates unnamed <a href="{@docRoot}/java.base/java/lang/Thread.html#virtual-threads">
737 * virtual threads</a>, no name for monitoring and management purposes, and no timeout.
738 *
739 * <p> Creating a {@code StructuredTaskScope} with its 2-arg {@link #open(Joiner, Function)
740 * open} method allows a different configuration to be used. The function specified
741 * to the {@code open} method is applied to the default configuration and returns the
742 * configuration for the {@code StructuredTaskScope} under construction. The function
743 * can use the {@code with-} prefixed methods defined here to specify the components
744 * of the configuration to use.
745 *
746 * <p> Unless otherwise specified, passing a {@code null} argument to a method
747 * in this class will cause a {@link NullPointerException} to be thrown.
748 *
749 * @since 25
750 */
751 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
752 sealed interface Configuration permits StructuredTaskScopeImpl.ConfigImpl {
753 /**
754 * {@return a new {@code Configuration} object with the given thread factory}
755 * The other components are the same as this object. The thread factory is used by
756 * a scope to create threads when {@linkplain #fork(Callable) forking} subtasks.
757 * @param threadFactory the thread factory
758 *
759 * @apiNote The thread factory will typically create
760 * <a href="{@docRoot}/java.base/java/lang/Thread.html#virtual-threads">virtual threads</a>,
761 * maybe with names for monitoring purposes, an {@linkplain Thread.UncaughtExceptionHandler
762 * uncaught exception handler}, or other properties configured.
763 *
764 * @see #fork(Callable)
765 */
766 Configuration withThreadFactory(ThreadFactory threadFactory);
767
768 /**
769 * {@return a new {@code Configuration} object with the given name}
770 * The other components are the same as this object. A scope is optionally
771 * named for the purposes of monitoring and management.
772 * @param name the name
773 */
774 Configuration withName(String name);
775
776 /**
777 * {@return a new {@code Configuration} object with the given timeout}
778 * The other components are the same as this object.
779 * @param timeout the timeout
780 *
781 * @apiNote Applications using deadlines, expressed as an {@link java.time.Instant},
782 * can use {@link Duration#between Duration.between(Instant.now(), deadline)} to
783 * compute the timeout for this method.
784 *
785 * @see #join()
786 */
787 Configuration withTimeout(Duration timeout);
788 }
789
790 /**
791 * Exception thrown by {@link #join()} when the outcome is an exception rather than a
792 * result.
793 *
794 * @since 25
795 */
796 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
797 final class FailedException extends RuntimeException {
798 @java.io.Serial
799 static final long serialVersionUID = -1533055100078459923L;
800
801 /**
802 * Constructs a {@code FailedException} with the specified cause.
803 *
804 * @param cause the cause, can be {@code null}
805 */
806 FailedException(Throwable cause) {
807 super(cause);
808 }
809 }
810
811 /**
812 * Exception thrown by {@link #join()} if the scope was created with a timeout and
813 * the timeout expired before or while waiting in {@code join}.
814 *
815 * @since 25
816 * @see Configuration#withTimeout(Duration)
817 */
818 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
819 final class TimeoutException extends RuntimeException {
820 @java.io.Serial
821 static final long serialVersionUID = 705788143955048766L;
822
823 /**
824 * Constructs a {@code TimeoutException} with no detail message.
825 */
826 TimeoutException() { }
827 }
828
829 /**
830 * Opens a new {@code StructuredTaskScope} to use the given {@code Joiner} object and
831 * with configuration that is the result of applying the given function to the
832 * <a href="#DefaultConfiguration">default configuration</a>.
833 *
834 * <p> The {@code configFunction} is called with the default configuration and returns
835 * the configuration for the new scope. The function may, for example, set the
836 * {@linkplain Configuration#withThreadFactory(ThreadFactory) ThreadFactory} or set a
837 * {@linkplain Configuration#withTimeout(Duration) timeout}. If the function completes
838 * with an exception or error then it is propagated by this method. If the function
839 * returns {@code null} then {@code NullPointerException} is thrown.
840 *
841 * <p> If a {@code ThreadFactory} is set then its {@link ThreadFactory#newThread(Runnable)
842 * newThread} method will be called to create threads when {@linkplain #fork(Callable)
843 * forking} subtasks in this scope. If a {@code ThreadFactory} is not set then
844 * forking subtasks will create an unnamed virtual thread for each subtask.
845 *
846 * <p> If a {@linkplain Configuration#withTimeout(Duration) timeout} is set then it
847 * starts when the scope is opened. If the timeout expires before the scope has
848 * {@linkplain #join() joined} then the scope is <a href="#Cancallation">cancelled</a>
849 * and the {@code join} method throws {@link TimeoutException}.
850 *
851 * <p> The new scope is owned by the current thread. Only code executing in this
852 * thread can {@linkplain #fork(Callable) fork}, {@linkplain #join() join}, or
853 * {@linkplain #close close} the scope.
854 *
855 * <p> Construction captures the current thread's {@linkplain ScopedValue scoped
856 * value} bindings for inheritance by threads started in the scope.
857 *
858 * @param joiner the joiner
859 * @param configFunction a function to produce the configuration
860 * @return a new scope
861 * @param <T> the result type of subtasks executed in the scope
862 * @param <R> the result type of the scope
863 * @since 25
864 */
865 static <T, R> StructuredTaskScope<T, R> open(Joiner<? super T, ? extends R> joiner,
866 Function<Configuration, Configuration> configFunction) {
867 return StructuredTaskScopeImpl.open(joiner, configFunction);
868 }
869
870 /**
871 * Opens a new {@code StructuredTaskScope}to use the given {@code Joiner} object. The
872 * scope is created with the <a href="#DefaultConfiguration">default configuration</a>.
873 * The default configuration has a {@code ThreadFactory} that creates unnamed
874 * <a href="{@docRoot}/java.base/java/lang/Thread.html#virtual-threads">virtual threads</a>,
875 * is unnamed for monitoring and management purposes, and has no timeout.
876 *
877 * @implSpec
878 * This factory method is equivalent to invoking the 2-arg open method with the given
879 * joiner and the {@linkplain Function#identity() identity function}.
880 *
881 * @param joiner the joiner
882 * @return a new scope
883 * @param <T> the result type of subtasks executed in the scope
884 * @param <R> the result type of the scope
885 * @since 25
886 */
887 static <T, R> StructuredTaskScope<T, R> open(Joiner<? super T, ? extends R> joiner) {
888 return open(joiner, Function.identity());
889 }
890
891 /**
892 * Opens a new {@code StructuredTaskScope} that can be used to fork subtasks that return
893 * results of any type. The scope's {@link #join()} method waits for all subtasks to
894 * succeed or any subtask to fail.
895 *
896 * <p> The {@code join} method returns {@code null} if all subtasks complete successfully.
897 * It throws {@link FailedException} if any subtask fails, with the exception from
898 * the first subtask to fail as the cause.
899 *
900 * <p> The scope is created with the <a href="#DefaultConfiguration">default
901 * configuration</a>. The default configuration has a {@code ThreadFactory} that creates
902 * unnamed <a href="{@docRoot}/java.base/java/lang/Thread.html#virtual-threads">virtual
903 * threads</a>, is unnamed for monitoring and management purposes, and has no timeout.
904 *
905 * @implSpec
906 * This factory method is equivalent to invoking the 2-arg open method with a joiner
907 * created with {@link Joiner#awaitAllSuccessfulOrThrow() awaitAllSuccessfulOrThrow()}
908 * and the {@linkplain Function#identity() identity function}.
909 *
910 * @param <T> the result type of subtasks
911 * @return a new scope
912 * @since 25
913 */
914 static <T> StructuredTaskScope<T, Void> open() {
915 return open(Joiner.awaitAllSuccessfulOrThrow(), Function.identity());
916 }
917
918 /**
919 * Fork a subtask by starting a new thread in this scope to execute a value-returning
920 * method. The new thread executes the subtask concurrently with the current thread.
921 * The parameter to this method is a {@link Callable}, the new thread executes its
922 * {@link Callable#call() call()} method.
923 *
924 * <p> This method first creates a {@link Subtask Subtask} object to represent the
925 * <em>forked subtask</em>. It invokes the joiner's {@link Joiner#onFork(Subtask) onFork}
926 * method with the subtask in the {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state.
927 * If the {@code onFork} completes with an exception or error then it is propagated by
928 * the {@code fork} method without creating a thread. If the scope is already
929 * <a href="#Cancallation">cancelled</a>, or {@code onFork} returns {@code true} to
930 * cancel the scope, then this method returns the {@code Subtask}, in the
931 * {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state, without creating a thread to
932 * execute the subtask.
933 *
934 * <p> If the scope is not cancelled, and the {@code onFork} method returns {@code false},
935 * then a thread is created with the {@link ThreadFactory} configured when the scope
936 * was opened, and the thread is started. Forking a subtask inherits the current thread's
937 * {@linkplain ScopedValue scoped value} bindings. The bindings must match the bindings
938 * captured when the scope was opened. If the subtask completes (successfully or with
939 * an exception) before the scope is cancelled, then the thread invokes the joiner's
940 * {@link Joiner#onComplete(Subtask) onComplete} method with the subtask in the
941 * {@link Subtask.State#SUCCESS SUCCESS} or {@link Subtask.State#FAILED FAILED} state.
942 * If the {@code onComplete} method completes with an exception or error, then the
943 * {@linkplain Thread.UncaughtExceptionHandler uncaught exception handler} is invoked
944 * with the exception or error before the thread terminates.
945 *
946 * <p> This method returns the {@link Subtask Subtask} object. In some usages, this
947 * object may be used to get its result. In other cases it may be used for correlation
948 * or be discarded. To ensure correct usage, the {@link Subtask#get() Subtask.get()}
949 * method may only be called by the scope owner to get the result after it has
976 * parameter to this method is a {@link Runnable}, the new thread executes its
977 * {@link Runnable#run() run} method, and {@link Subtask#get() Subtask.get()} returns
978 * {@code null} if the subtask completes successfully.
979 *
980 * @param task the task for the thread to execute
981 * @param <U> the result type
982 * @return the subtask
983 * @throws WrongThreadException if the current thread is not the scope owner
984 * @throws IllegalStateException if the owner has already {@linkplain #join() joined}
985 * or the scope is closed
986 * @throws StructureViolationException if the current scoped value bindings are not
987 * the same as when the scope was created
988 * @throws RejectedExecutionException if the thread factory rejected creating a
989 * thread to run the subtask
990 * @since 25
991 */
992 <U extends T> Subtask<U> fork(Runnable task);
993
994 /**
995 * Returns the result, or throws, after waiting for all subtasks to complete or
996 * the scope to be <a href="#Cancallation">cancelled</a>.
997 *
998 * <p> This method waits for all subtasks started in this scope to complete or the
999 * scope to be cancelled. If a {@linkplain Configuration#withTimeout(Duration) timeout}
1000 * is configured and the timeout expires before or while waiting, then the scope is
1001 * cancelled and {@link TimeoutException TimeoutException} is thrown. Once finished
1002 * waiting, the {@code Joiner}'s {@link Joiner#result() result()} method is invoked
1003 * to get the result or throw an exception. If the {@code result()} method throws
1004 * then this method throws {@code FailedException} with the exception as the cause.
1005 *
1006 * <p> This method may only be invoked by the scope owner, and only once.
1007 *
1008 * @return the result
1009 * @throws WrongThreadException if the current thread is not the scope owner
1010 * @throws IllegalStateException if already joined or this scope is closed
1011 * @throws FailedException if the <i>outcome</i> is an exception, thrown with the
1012 * exception from {@link Joiner#result() Joiner.result()} as the cause
1013 * @throws TimeoutException if a timeout is set and the timeout expires before or
1014 * while waiting
1015 * @throws InterruptedException if interrupted while waiting
1016 * @since 25
1017 */
1018 R join() throws InterruptedException;
1019
1020 /**
1021 * {@return {@code true} if this scope is <a href="#Cancallation">cancelled</a> or in
1022 * the process of being cancelled, otherwise {@code false}}
1023 *
1024 * <p> Cancelling the scope prevents new threads from starting in the scope and
1025 * {@linkplain Thread#interrupt() interrupts} threads executing unfinished subtasks.
1026 * It may take some time before the interrupted threads finish execution; this
1027 * method may return {@code true} before all threads have been interrupted or before
1028 * all threads have finished.
1029 *
1030 * @apiNote A task with a lengthy "forking phase" (the code that executes before
1031 * it invokes {@link #join() join}) may use this method to avoid doing work in cases
1032 * where scope is cancelled by the completion of a previously forked subtask or timeout.
1033 *
1034 * @since 25
1035 */
1036 boolean isCancelled();
1037
1038 /**
1039 * Closes this scope.
1040 *
1041 * <p> This method first <a href="#Cancallation">cancels</a> the scope, if not
1042 * already cancelled. This interrupts the threads executing unfinished subtasks. This
1043 * method then waits for all threads to finish. If interrupted while waiting then it
1044 * will continue to wait until the threads finish, before completing with the interrupt
1045 * status set.
1046 *
1047 * <p> This method may only be invoked by the scope owner. If the scope
1048 * is already closed then the scope owner invoking this method has no effect.
1049 *
1050 * <p> A {@code StructuredTaskScope} is intended to be used in a <em>structured
1051 * manner</em>. If this method is called to close a scope before nested task
1052 * scopes are closed then it closes the underlying construct of each nested scope
1053 * (in the reverse order that they were created in), closes this scope, and then
1054 * throws {@link StructureViolationException}.
1055 * Similarly, if this method is called to close a scope while executing with
1056 * {@linkplain ScopedValue scoped value} bindings, and the scope was created
1057 * before the scoped values were bound, then {@code StructureViolationException} is
1058 * thrown after closing the scope.
1059 * If a thread terminates without first closing scopes that it owns then
1060 * termination will cause the underlying construct of each of its open tasks scopes to
1061 * be closed. Closing is performed in the reverse order that the scopes were
1062 * created in. Thread termination may therefore be delayed when the scope owner
1063 * has to wait for threads forked in these scopes to finish.
1064 *
1065 * @throws IllegalStateException thrown after closing the scope if the scope
1066 * owner did not attempt to join after forking
1067 * @throws WrongThreadException if the current thread is not the scope owner
1068 * @throws StructureViolationException if a structure violation was detected
1069 */
1070 @Override
1071 void close();
1072 }
|
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.util.concurrent;
26
27 import java.time.Duration;
28 import java.util.List;
29 import java.util.function.Predicate;
30 import java.util.function.Supplier;
31 import java.util.function.UnaryOperator;
32 import jdk.internal.javac.PreviewFeature;
33
34 /**
35 * An API for <em>structured concurrency</em>. {@code StructuredTaskScope} supports cases
36 * where execution of a <em>task</em> (a unit of work) splits into several concurrent
37 * subtasks, and where the subtasks must complete before the task continues. A {@code
38 * StructuredTaskScope} can be used to ensure that the lifetime of a concurrent operation
39 * is confined by a <em>syntax block</em>, similar to that of a sequential operation in
40 * structured programming.
41 *
42 * <p> {@code StructuredTaskScope} defines the static method {@link #open() open} to open
43 * a new {@code StructuredTaskScope} and the {@link #close() close} method to close it.
44 * The API is designed to be used with the {@code try}-with-resources statement where
45 * the {@code StructuredTaskScope} is opened as a resource and then closed automatically.
46 * The code inside the block uses the {@link #fork(Callable) fork} method to fork subtasks.
47 * After forking, it uses the {@link #join() join} method to wait for all subtasks to
48 * finish (or some other outcome) as a single operation. Forking a subtask starts a new
49 * {@link Thread} to run the subtask. The thread executing the task does not continue
50 * beyond the {@code close} method until all threads started to execute subtasks have finished.
51 * To ensure correct usage, the {@code fork}, {@code join} and {@code close} methods may
52 * only be invoked by the <em>owner thread</em> (the thread that opened the {@code
53 * StructuredTaskScope}), the {@code fork} method may not be called after {@code join},
54 * the {@code join} method must be invoked to get the outcome after forking subtasks, and
55 * the {@code close} method throws an exception after closing if the owner did not invoke
56 * the {@code join} method after forking subtasks.
57 *
58 * <p> As a first example, consider a task that splits into two subtasks to concurrently
59 * fetch resources from two URL locations "left" and "right". Both subtasks may complete
60 * successfully, one subtask may succeed and the other may fail, or both subtasks may
61 * fail. The task in this example is interested in the successful result from both
62 * subtasks. It waits in the {@link #join() join} method for both subtasks to complete
63 * successfully or for either subtask to fail.
64 * {@snippet lang=java :
65 * // @link substring="open" target="#open()" :
66 * try (var scope = StructuredTaskScope.open()) {
67 *
68 * // @link substring="fork" target="#fork(Callable)" :
69 * Subtask<String> subtask1 = scope.fork(() -> query(left));
70 * Subtask<Integer> subtask2 = scope.fork(() -> query(right));
71 *
72 * // throws if either subtask fails
73 * scope.join(); // @link substring="join" target="#join()"
74 *
75 * // both subtasks completed successfully
76 * // @link substring="get" target="Subtask#get()" :
90 * <p> To allow for cancellation, subtasks must be coded so that they finish as soon as
91 * possible when interrupted. Subtasks that do not respond to interrupt, e.g. block on
92 * methods that are not interruptible, may delay the closing of a scope indefinitely. The
93 * {@link #close() close} method always waits for threads executing subtasks to finish,
94 * even if the scope is cancelled, so execution cannot continue beyond the {@code close}
95 * method until the interrupted threads finish.
96 *
97 * <p> In the example, the subtasks produce results of different types ({@code String} and
98 * {@code Integer}). In other cases the subtasks may all produce results of the same type.
99 * If the example had used {@code StructuredTaskScope.<String>open()} then it could
100 * only be used to fork subtasks that return a {@code String} result.
101 *
102 * <h2>Joiners</h2>
103 *
104 * <p> In the example above, the task fails if any subtask fails. If all subtasks
105 * succeed then the {@code join} method completes normally. Other policy and outcome is
106 * supported by creating a {@code StructuredTaskScope} with a {@link Joiner} that
107 * implements the desired policy. A {@code Joiner} handles subtask completion and produces
108 * the outcome for the {@link #join() join} method. In the example above, {@code join}
109 * returns {@code null}. Depending on the {@code Joiner}, {@code join} may return a
110 * result, a list of elements, or some other object. The {@code Joiner} interface defines
111 * factory methods to create {@code Joiner}s for some common cases.
112 *
113 * <p> A {@code Joiner} may <a id="Cancellation">cancel</a> the scope (sometimes called
114 * "short-circuiting") when some condition is reached that does not require the result of
115 * subtasks that are still executing. Cancelling the scope prevents new threads from being
116 * started to execute further subtasks, {@linkplain Thread#interrupt() interrupts} the
117 * threads executing subtasks that have not completed, and causes the {@code join} method
118 * to wakeup with the outcome (result or exception). In the above example, the outcome is
119 * that {@code join} completes with a result of {@code null} when all subtasks succeed.
120 * The scope is cancelled if any of the subtasks fail and {@code join} throws {@code
121 * FailedException} with the exception from the failed subtask as the cause. Other {@code
122 * Joiner} implementations may cancel the scope for other reasons.
123 *
124 * <p> Now consider another example that splits into two subtasks. In this example,
125 * each subtask produces a {@code String} result and the task is only interested in
126 * the result from the first subtask to complete successfully. The example uses {@link
127 * Joiner#anySuccessfulOrThrow() Joiner.anySuccessfulOrThrow()} to create a {@code Joiner}
128 * that makes available the result of the first subtask to complete successfully. The type
129 * parameter in the example is "{@code String}" so that only subtasks that return a
130 * {@code String} can be forked.
131 * {@snippet lang=java :
132 * // @link substring="open" target="#open(Joiner)" :
133 * try (var scope = StructuredTaskScope.open(Joiner.<String>anySuccessfulOrThrow())) {
134 *
135 * scope.fork(callable1);
136 * scope.fork(callable2);
137 *
138 * // throws if both subtasks fail
139 * String firstResult = scope.join();
140 *
141 * }
142 * }
143 *
144 * <p> In the example, the task forks the two subtasks, then waits in the {@code
145 * join} method for either subtask to complete successfully or for both subtasks to fail.
146 * If one of the subtasks completes successfully then the {@code Joiner} causes the other
147 * subtask to be cancelled (this will interrupt the thread executing the subtask), and
148 * the {@code join} method returns the result from the successful subtask. Cancelling the
149 * other subtask avoids the task waiting for a result that it doesn't care about. If
150 * both subtasks fail then the {@code join} method throws {@code FailedException} with the
151 * exception from one of the subtasks as the {@linkplain Throwable#getCause() cause}.
152 *
153 * <p> Whether code uses the {@code Subtask} returned from {@code fork} will depend on
154 * the {@code Joiner} and usage. Some {@code Joiner} implementations are suited to subtasks
155 * that return results of the same type and where the {@code join} method returns a result
156 * for the task to use. Code that forks subtasks that return results of different
157 * types, and uses a {@code Joiner} such as {@link Joiner#awaitAllSuccessfulOrThrow()
158 * awaitAllSuccessfulOrThrow} that does not return a result, will use {@link Subtask#get()
159 * Subtask.get()} after joining.
160 *
161 * <h2>Exception handling</h2>
162 *
163 * <p> A {@code StructuredTaskScope} is opened with a {@link Joiner Joiner} that
164 * handles subtask completion and produces the outcome for the {@link #join() join} method.
165 * In some cases, the outcome will be a result, in other cases it will be an exception.
166 * If the outcome is an exception then the {@code join} method throws {@link
167 * FailedException} with the exception as the {@linkplain Throwable#getCause()
168 * cause}. For many {@code Joiner} implementations, the exception will be an exception
169 * thrown by a subtask that failed. In the case of {@link Joiner#allSuccessfulOrThrow()
170 * allSuccessfulOrThrow} and {@link Joiner#awaitAllSuccessfulOrThrow() awaitAllSuccessfulOrThrow}
171 * for example, the exception is from the first subtask to fail.
172 *
173 * <p> Many of the details for how exceptions are handled will depend on usage. In some
174 * cases it may be useful to add a {@code catch} block to the {@code try}-with-resources
175 * statement to catch {@code FailedException}. The exception handling may use {@code
176 * instanceof} with pattern matching to handle specific causes.
177 * {@snippet lang=java :
178 * try (var scope = StructuredTaskScope.open()) {
179 *
182 * } catch (StructuredTaskScope.FailedException e) {
183 *
184 * Throwable cause = e.getCause();
185 * switch (cause) {
186 * case IOException ioe -> ..
187 * default -> ..
188 * }
189 *
190 * }
191 * }
192 * In other cases it may not be useful to catch {@code FailedException} but instead leave
193 * it to propagate to the configured {@linkplain Thread.UncaughtExceptionHandler uncaught
194 * exception handler} for logging purposes.
195 *
196 * <p> For cases where a specific exception triggers the use of a default result then it
197 * may be more appropriate to handle this in the subtask itself rather than the subtask
198 * failing and the scope owner handling the exception.
199 *
200 * <h2>Configuration</h2>
201 *
202 * A {@code StructuredTaskScope} is opened with {@linkplain Configuration configuration}
203 * that consists of a {@link ThreadFactory} to create threads, an optional name for the
204 * scope, and an optional timeout. The name is intended for monitoring and management
205 * purposes.
206 *
207 * <p> The {@link #open()} and {@link #open(Joiner)} methods create a {@code StructuredTaskScope}
208 * with the <a id="DefaultConfiguration"> <em>default configuration</em></a>. The default
209 * configuration has a {@code ThreadFactory} that creates unnamed {@linkplain
210 * Thread##virtual-threads virtual threads}, does not name the scope, and has no timeout.
211 *
212 * <p> The 2-arg {@link #open(Joiner, UnaryOperator) open} method can be used to create a
213 * {@code StructuredTaskScope} that uses a different {@code ThreadFactory}, is named for
214 * monitoring and management purposes, or has a timeout that cancels the scope if the
215 * timeout expires before or while waiting for subtasks to complete. The {@code open}
216 * method is called with an {@linkplain UnaryOperator operator} that is applied to the
217 * default configuration and returns a {@link Configuration Configuration} for the
218 * {@code StructuredTaskScope} under construction.
219 *
220 * <p> The following example opens a new {@code StructuredTaskScope} with a {@code
221 * ThreadFactory} that creates virtual threads {@linkplain Thread#setName(String) named}
222 * "duke-0", "duke-1" ...
223 * {@snippet lang = java:
224 * // @link substring="name" target="Thread.Builder#name(String, long)" :
225 * ThreadFactory factory = Thread.ofVirtual().name("duke-", 0).factory();
226 *
227 * // @link substring="withThreadFactory" target="Configuration#withThreadFactory(ThreadFactory)" :
228 * try (var scope = StructuredTaskScope.open(joiner, cf -> cf.withThreadFactory(factory))) {
229 *
230 * scope.fork( .. ); // runs in a virtual thread with name "duke-0"
231 * scope.fork( .. ); // runs in a virtual thread with name "duke-1"
232 *
233 * scope.join();
234 *
235 * }
236 *}
237 *
238 * <p> A second example sets a timeout, represented by a {@link Duration}. The timeout
239 * starts when the new scope is opened. If the timeout expires before the {@code join}
240 * method has completed then the scope is {@linkplain ##Cancellation cancelled} (this
241 * interrupts the threads executing the two subtasks), and the {@code join} method
242 * throws {@link TimeoutException TimeoutException}.
243 * {@snippet lang=java :
244 * Duration timeout = Duration.ofSeconds(10);
245 *
246 * // @link substring="allSuccessfulOrThrow" target="Joiner#allSuccessfulOrThrow()" :
247 * try (var scope = StructuredTaskScope.open(Joiner.<String>allSuccessfulOrThrow(),
248 * // @link substring="withTimeout" target="Configuration#withTimeout(Duration)" :
249 * cf -> cf.withTimeout(timeout))) {
250 *
251 * scope.fork(callable1);
252 * scope.fork(callable2);
253 *
254 * List<String> results = scope.join();
255 *
256 * }
257 * }
258 *
259 * <h2>Inheritance of scoped value bindings</h2>
260 *
261 * {@link ScopedValue} supports the execution of a method with a {@code ScopedValue} bound
262 * to a value for the bounded period of execution of the method by the <em>current thread</em>.
263 * It allows a value to be safely and efficiently shared to methods without using method
264 * parameters.
265 *
266 * <p> When used in conjunction with a {@code StructuredTaskScope}, a {@code ScopedValue}
267 * can also safely and efficiently share a value to methods executed by subtasks forked
268 * in the scope. When a {@code ScopedValue} object is bound to a value in the thread
269 * executing the task then that binding is inherited by the threads created to
270 * execute the subtasks. The thread executing the task does not continue beyond the
271 * {@link #close() close} method until all threads executing the subtasks have finished.
272 * This ensures that the {@code ScopedValue} is not reverted to being {@linkplain
273 * ScopedValue#isBound() unbound} (or its previous value) while subtasks are executing.
274 * In addition to providing a safe and efficient means to inherit a value into subtasks,
295 * USERNAME, then value "duke" will be returned.
296 * {@snippet lang=java :
297 * // @link substring="newInstance" target="ScopedValue#newInstance()" :
298 * private static final ScopedValue<String> USERNAME = ScopedValue.newInstance();
299 *
300 * // @link substring="where" target="ScopedValue#where(ScopedValue, Object)" :
301 * MyResult result = ScopedValue.where(USERNAME, "duke").call(() -> {
302 *
303 * try (var scope = StructuredTaskScope.open()) {
304 *
305 * Subtask<String> subtask1 = scope.fork( .. ); // inherits binding
306 * Subtask<Integer> subtask2 = scope.fork( .. ); // inherits binding
307 *
308 * scope.join();
309 * return new MyResult(subtask1.get(), subtask2.get());
310 * }
311 *
312 * });
313 * }
314 *
315 * <p> A scoped value inherited into a subtask may be {@linkplain ScopedValue##rebind
316 * rebound} to a new value in the subtask for the bounded execution of some method executed
317 * in the subtask. When the method completes, the value of the {@code ScopedValue} reverts
318 * to its previous value, the value inherited from the thread executing the task.
319 *
320 * <p> A subtask may execute code that itself opens a new {@code StructuredTaskScope}.
321 * A task executing in thread T1 opens a {@code StructuredTaskScope} and forks a
322 * subtask that runs in thread T2. The scoped value bindings captured when T1 opens the
323 * scope are inherited into T2. The subtask (in thread T2) executes code that opens a
324 * new {@code StructuredTaskScope} and forks a subtask that runs in thread T3. The scoped
325 * value bindings captured when T2 opens the scope are inherited into T3. These
326 * include (or may be the same) as the bindings that were inherited from T1. In effect,
327 * scoped values are inherited into a tree of subtasks, not just one level of subtask.
328 *
329 * <h2>Memory consistency effects</h2>
330 *
331 * <p> Actions in the owner thread of a {@code StructuredTaskScope} prior to {@linkplain
332 * #fork forking} of a subtask {@linkplain java.util.concurrent##MemoryVisibility
333 * <i>happen-before</i>} any actions taken by the thread that executes the subtask, which
334 * in turn <i>happen-before</i> actions in any thread that successfully obtains the
335 * subtask outcome with {@link Subtask#get() Subtask.get()} or {@link Subtask#exception()
336 * Subtask.exception()}. If a subtask's outcome contributes to the result or exception
337 * from {@link #join()}, then any actions taken by the thread executing that subtask
338 * <i>happen-before</i> the owner thread returns from {@code join} with a result or
339 * {@link FailedException FailedException}.
340 *
341 * <h2>General exceptions</h2>
342 *
343 * <p> Unless otherwise specified, passing a {@code null} argument to a method in this
344 * class will cause a {@link NullPointerException} to be thrown.
345 *
346 * @param <T> the result type of subtasks executed in the scope
347 * @param <R> the result type of the scope
348 *
349 * @jls 17.4.5 Happens-before Order
350 * @since 21
351 */
352 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
353 public sealed interface StructuredTaskScope<T, R>
354 extends AutoCloseable
355 permits StructuredTaskScopeImpl {
356
357 /**
358 * Represents a subtask forked with {@link #fork(Callable)} or {@link #fork(Runnable)}.
359 *
389 /**
390 * The subtask failed with an exception. The {@link Subtask#exception()
391 * Subtask.exception()} method can be used to get the exception. This is a
392 * terminal state.
393 */
394 FAILED,
395 }
396
397 /**
398 * {@return the subtask state}
399 */
400 State state();
401
402 /**
403 * Returns the result of this subtask if it completed successfully. If the subtask
404 * was forked with {@link #fork(Callable) fork(Callable)} then the result from the
405 * {@link Callable#call() call} method is returned. If the subtask was forked with
406 * {@link #fork(Runnable) fork(Runnable)} then {@code null} is returned.
407 *
408 * <p> Code executing in the scope owner thread can use this method to get the
409 * result of a successful subtask after it has {@linkplain #join() joined}.
410 *
411 * <p> Code executing in the {@code Joiner} {@link Joiner#onComplete(Subtask)
412 * onComplete} method should test that the {@linkplain #state() subtask state} is
413 * {@link State#SUCCESS SUCCESS} before using this method to get the result.
414 *
415 * <p> This method may be invoked by any thread after the scope owner has joined.
416 * The only case where this method can be used to get the result before the scope
417 * owner has joined is when called from the {@code onComplete(Subtask)} method.
418 *
419 * @return the possibly-null result
420 * @throws IllegalStateException if the subtask has not completed or did not
421 * complete successfully, or this method if invoked outside the context of the
422 * {@code onComplete(Subtask)} method before the owner thread has joined
423 * @see State#SUCCESS
424 */
425 T get();
426
427 /**
428 * {@return the exception or error thrown by this subtask if it failed}
429 * If the subtask was forked with {@link #fork(Callable) fork(Callable)} then the
430 * exception or error thrown by the {@link Callable#call() call} method is returned.
431 * If the subtask was forked with {@link #fork(Runnable) fork(Runnable)} then the
432 * exception or error thrown by the {@link Runnable#run() run} method is returned.
433 *
434 * <p> Code executing in the scope owner thread can use this method to get the
435 * exception thrown by a failed subtask after it has {@linkplain #join() joined}.
436 *
437 * <p> Code executing in a {@code Joiner} {@link Joiner#onComplete(Subtask)
438 * onComplete} method should test that the {@linkplain #state() subtask state} is
439 * {@link State#FAILED FAILED} before using this method to get the exception.
440 *
441 * <p> This method may be invoked by any thread after the scope owner has joined.
442 * The only case where this method can be used to get the exception before the scope
443 * owner has joined is when called from the {@code onComplete(Subtask)} method.
444 *
445 * @throws IllegalStateException if the subtask has not completed or completed
446 * with a result, or this method if invoked outside the context of the {@code
447 * onComplete(Subtask)} method before the owner thread has joined
448 * @see State#FAILED
449 */
450 Throwable exception();
451 }
452
453 /**
454 * An object used with a {@link StructuredTaskScope} to handle subtask completion and
455 * produce the result for the scope owner waiting in the {@link #join() join} method
456 * for subtasks to complete.
457 *
458 * <p> Joiner defines static methods to create {@code Joiner} objects for common cases:
459 * <ul>
460 * <li> {@link #allSuccessfulOrThrow() allSuccessfulOrThrow()} creates a {@code Joiner}
461 * that yields a list of all results for {@code join} to return when all subtasks
462 * complete successfully. It cancels the scope and causes {@code join} to throw if
463 * any subtask fails.
464 * <li> {@link #anySuccessfulOrThrow() anySuccessfulOrThrow()} creates a {@code Joiner}
465 * that yields the result of the first subtask to succeed for {@code join} to return.
466 * It causes {@code join} to throw if all subtasks fail.
467 * <li> {@link #awaitAllSuccessfulOrThrow() awaitAllSuccessfulOrThrow()} creates a
468 * {@code Joiner} that waits for all successful subtasks. It cancels the scope and
469 * causes {@code join} to throw if any subtask fails.
470 * <li> {@link #awaitAll() awaitAll()} creates a {@code Joiner} that waits for all
471 * subtasks to complete. It does not cancel the scope or cause {@code join} to throw.
472 * </ul>
473 *
474 * <p> In addition to the methods to create {@code Joiner} objects for common cases,
475 * the {@link #allUntil(Predicate) allUntil(Predicate)} method is defined to create a
476 * {@code Joiner} that yields a list of all subtasks. It is created with a {@link
477 * Predicate Predicate} that determines if the scope should continue or be cancelled.
478 * This {@code Joiner} can be built upon to create custom policies that cancel the
479 * scope based on some condition.
480 *
481 * <p> More advanced policies can be developed by implementing the {@code Joiner}
482 * interface. The {@link #onFork(Subtask)} method is invoked when subtasks are forked.
483 * The {@link #onComplete(Subtask)} method is invoked when subtasks complete with a
484 * result or exception. These methods return a {@code boolean} to indicate if the scope
485 * should be cancelled. These methods can be used to collect subtasks, results, or
486 * exceptions, and control when to cancel the scope. The {@link #result()} method
487 * must be implemented to produce the result (or exception) for the {@code join}
488 * method.
489 *
490 * <p> If a {@code StructuredTaskScope} is opened with a {@linkplain
491 * Configuration#withTimeout(Duration) timeout}, and the timeout expires before or
492 * while waiting in {@link StructuredTaskScope#join() join()}, then the scope is
493 * {@linkplain StructuredTaskScope##Cancellation cancelled}, and the {@code Joiners}'s
494 * {@link #onTimeout()} method is invoked to notify the {@code Joiner} and optionally
495 * throw {@link TimeoutException TimeoutException}. If the {@code onTimeout()} method
496 * does not throw then the {@code join()} method will invoke the {@link #result()}
497 * method to produce a result. This result may be based on the outcome of subtasks
498 * that completed before the timeout expired.
499 *
500 * <p> Unless otherwise specified, passing a {@code null} argument to a method
501 * in this class will cause a {@link NullPointerException} to be thrown.
502 *
503 * @implSpec Implementations of this interface must be thread safe. The {@link
504 * #onComplete(Subtask)} method defined by this interface may be invoked by several
505 * threads concurrently, concurrently with the owner thread invoking the {@link
506 * #onFork(Subtask)} method, or if a timeout is configured, concurrently with the owner
507 * thread invoking the {@link #onTimeout()} method.
508 *
509 * @apiNote It is very important that a new {@code Joiner} object is created for each
510 * {@code StructuredTaskScope}. {@code Joiner} objects should never be shared with
511 * different scopes or re-used after a scope is closed.
512 *
513 * <p> Designing a {@code Joiner} should take into account the code at the use-site
514 * where the results from the {@link StructuredTaskScope#join() join} method are
515 * processed. It should be clear what the {@code Joiner} does vs. the application
516 * code at the use-site. In general, the {@code Joiner} implementation is not the
517 * place for "business logic". A {@code Joiner} should be designed to be as general
518 * purpose as possible.
519 *
520 * @param <T> the result type of subtasks executed in the scope
521 * @param <R> the result type of the scope
522 * @since 25
523 * @see #open(Joiner)
524 */
525 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
526 interface Joiner<T, R> {
527 /**
528 * Invoked by {@link #fork(Callable) fork(Callable)} and {@link #fork(Runnable)
529 * fork(Runnable)} when forking a subtask. The method is invoked before a thread
530 * is created to run the subtask.
531 *
532 * @implSpec The default implementation throws {@code NullPointerException} if the
533 * subtask is {@code null}. It throws {@code IllegalArgumentException} if the
534 * subtask is not in the {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state, it
535 * otherwise returns {@code false}.
536 *
537 * @apiNote This method is invoked by the {@code fork} methods. It should not be
538 * invoked directly.
539 *
540 * @param subtask the subtask
541 * @return {@code true} to cancel the scope, otherwise {@code false}
542 */
543 default boolean onFork(Subtask<T> subtask) {
544 if (subtask.state() != Subtask.State.UNAVAILABLE) {
545 throw new IllegalArgumentException("Subtask not in UNAVAILABLE state");
546 }
547 return false;
548 }
549
550 /**
551 * Invoked by the thread started to execute a subtask after the subtask completes
552 * successfully or fails with an exception. This method is not invoked if a
553 * subtask completes after the scope is cancelled.
554 *
555 * @implSpec The default implementation throws {@code NullPointerException} if the
556 * subtask is {@code null}. It throws {@code IllegalArgumentException} if the
557 * subtask is not in the {@link Subtask.State#SUCCESS SUCCESS} or {@link
558 * Subtask.State#FAILED FAILED} state, it otherwise returns {@code false}.
559 *
560 * @apiNote This method is invoked by subtasks when they complete. It should not
561 * be invoked directly.
562 *
563 * @param subtask the subtask
564 * @return {@code true} to cancel the scope, otherwise {@code false}
565 */
566 default boolean onComplete(Subtask<T> subtask) {
567 if (subtask.state() == Subtask.State.UNAVAILABLE) {
568 throw new IllegalArgumentException("Subtask has not completed");
569 }
570 return false;
571 }
572
573 /**
574 * Invoked by the {@link #join() join()} method if the scope was opened with a
575 * timeout, and the timeout expires before or while waiting in the {@code join}
576 * method.
577 *
578 * @implSpec The default implementation throws {@link TimeoutException TimeoutException}.
579 *
580 * @apiNote This method is intended for {@code Joiner} implementations that do not
581 * throw {@link TimeoutException TimeoutException}, or require a notification when
582 * the timeout expires before or while waiting in {@code join}.
583 *
584 * <p> This method is invoked by the {@code join} method. It should not be
585 * invoked directly.
586 *
587 * @throws TimeoutException for {@code join} to throw
588 * @since 26
589 */
590 default void onTimeout() {
591 throw new TimeoutException();
592 }
593
594 /**
595 * Invoked by the {@link #join() join()} method to produce the result (or exception)
596 * after waiting for all subtasks to complete or the scope cancelled. The result
597 * from this method is returned by the {@code join} method. If this method throws,
598 * then {@code join} throws {@link FailedException} with the exception thrown by
599 * this method as the cause.
600 *
601 * <p> In normal usage, this method will be called at most once by the {@code join}
602 * method to produce the result (or exception). The behavior of this method when
603 * invoked directly is undefined.
604 *
605 * @apiNote This method is invoked by the {@code join} method. It should not be
606 * invoked directly.
607 *
608 * @return the result
609 * @throws Throwable the exception
610 */
611 R result() throws Throwable;
612
613 /**
614 * {@return a new Joiner object that yields a list of all results when all
615 * subtasks complete successfully}
616 * The {@code Joiner} {@linkplain StructuredTaskScope##Cancellation cancels}
617 * the scope and causes {@code join} to throw if any subtask fails.
618 *
619 * <p> If all subtasks complete successfully then the joiner's {@link
620 * Joiner#result()} method returns a list of all results, in the order that the
621 * subtasks were forked, for the {@link StructuredTaskScope#join() join()} to return.
622 * If the scope was opened with a {@linkplain Configuration#withTimeout(Duration)
623 * timeout}, and the timeout expires before or while waiting for all subtasks to
624 * complete, then the {@code join} method throws {@code TimeoutException}.
625 *
626 * @apiNote Joiners returned by this method are suited to cases where all subtasks
627 * return a result of the same type. Joiners returned by {@link
628 * #awaitAllSuccessfulOrThrow()} are suited to cases where the subtasks return
629 * results of different types.
630 *
631 * @param <T> the result type of subtasks
632 */
633 static <T> Joiner<T, List<T>> allSuccessfulOrThrow() {
634 return new Joiners.AllSuccessful<>();
635 }
636
637 /**
638 * {@return a new Joiner object that yields the result of any subtask that
639 * completed successfully}
640 * The {@code Joiner} causes {@code join} to throw if all subtasks fail.
641 *
642 * <p> The joiner's {@link Joiner#result()} method returns the result of a subtask,
643 * that completed successfully, for the {@link StructuredTaskScope#join() join()}
644 * to return. If all subtasks fail then the {@code result} method throws the
645 * exception from one of the failed subtasks. The {@code result} method throws
646 * {@code NoSuchElementException} if no subtasks were forked. If the scope was
647 * opened with a {@linkplain Configuration#withTimeout(Duration) timeout}, and
648 * the timeout expires before or while waiting for any subtask to complete
649 * successfully, then the {@code join} method throws {@code TimeoutException}.
650 *
651 * @param <T> the result type of subtasks
652 * @since 26
653 */
654 static <T> Joiner<T, T> anySuccessfulOrThrow() {
655 return new Joiners.AnySuccessful<>();
656 }
657
658 /**
659 * {@return a new Joiner object that waits for subtasks to complete successfully}
660 * The {@code Joiner} {@linkplain StructuredTaskScope##Cancellation cancels}
661 * the scope and causes {@code join} to throw if any subtask fails.
662 *
663 * <p> The joiner's {@link Joiner#result() result} method returns {@code null}
664 * if all subtasks complete successfully, or throws the exception from the first
665 * subtask to fail. If the scope was opened with a {@linkplain
666 * Configuration#withTimeout(Duration) timeout}, and the timeout expires before or
667 * while waiting for all subtasks to complete, then the {@code join} method throws
668 * {@code TimeoutException}.
669 *
670 * @apiNote Joiners returned by this method are suited to cases where subtasks
671 * return results of different types. Joiners returned by {@link #allSuccessfulOrThrow()}
672 * are suited to cases where the subtasks return a result of the same type.
673 *
674 * @param <T> the result type of subtasks
675 */
676 static <T> Joiner<T, Void> awaitAllSuccessfulOrThrow() {
677 return new Joiners.AwaitSuccessful<>();
678 }
679
680 /**
681 * {@return a new Joiner object that waits for all subtasks to complete}
682 * The {@code Joiner} does not cancel the scope if a subtask fails.
683 *
684 * <p> The joiner's {@link Joiner#result() result} method returns {@code null}.
685 * If the scope was opened with a {@linkplain Configuration#withTimeout(Duration)
686 * timeout}, and the timeout expires before or while waiting for all subtasks to
687 * complete, then the {@code join} method throws {@code TimeoutException}.
688 *
689 * @apiNote This Joiner is useful for cases where subtasks make use of
690 * <em>side-effects</em> rather than return results or fail with exceptions.
691 * The {@link #fork(Runnable) fork(Runnable)} method can be used to fork subtasks
692 * that do not return a result.
693 *
694 * <p> This Joiner can also be used for <em>fan-in</em> scenarios where subtasks
695 * are forked to handle incoming connections and the number of subtasks is unbounded.
696 * In this example, the thread executing the {@code acceptLoop} method will only
697 * stop when interrupted or the listener socket is closed asynchronously.
698 * {@snippet lang=java :
699 * void acceptLoop(ServerSocket listener) throws IOException, InterruptedException {
700 * try (var scope = StructuredTaskScope.open(Joiner.<Socket>awaitAll())) {
701 * while (true) {
702 * Socket socket = listener.accept();
703 * scope.fork(() -> handle(socket));
704 * }
705 * }
706 * }
707 * }
708 *
709 * @param <T> the result type of subtasks
710 */
711 static <T> Joiner<T, Void> awaitAll() {
712 // ensure that new Joiner object is returned
713 return new Joiner<T, Void>() {
714 @Override
715 public Void result() {
716 return null;
717 }
718 };
719 }
720
721 /**
722 * {@return a new Joiner object that yields a list of all subtasks when all
723 * subtasks complete or a predicate returns {@code true} to cancel the scope}
724 *
725 * <p> The joiner's {@link #onComplete(Subtask)} method invokes the predicate's
726 * {@link Predicate#test(Object) test} method with the subtask that completed
727 * successfully or failed with an exception. If the {@code test} method
728 * returns {@code true} then {@linkplain StructuredTaskScope##Cancellation
729 * the scope is cancelled}. The {@code test} method must be thread safe as it
730 * may be invoked concurrently from several threads. If the {@code test} method
731 * completes with an exception or error, then the thread that executed the subtask
732 * invokes the {@linkplain Thread.UncaughtExceptionHandler uncaught exception handler}
733 * with the exception or error before the thread terminates.
734 *
735 * <p> The joiner's {@link #result()} method returns the list of all subtasks,
736 * in fork order. The list may contain subtasks that have completed
737 * (in {@link Subtask.State#SUCCESS SUCCESS} or {@link Subtask.State#FAILED FAILED}
738 * state) or subtasks in the {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state
739 * if the scope was cancelled before all subtasks were forked or completed.
740 *
741 * <p> The joiner's {@link #onTimeout()} method does nothing. If configured with
742 * a {@linkplain Configuration#withTimeout(Duration) timeout}, and the timeout
743 * expires before or while waiting in {@link StructuredTaskScope#join() join},
744 * then the {@link #result()} method returns the list of all subtasks.
745 * Subtasks that did not complete before the timeout expired will be in the
746 * {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state.
747 *
748 * <p> The following example uses this method to create a {@code Joiner} that
749 * {@linkplain StructuredTaskScope##Cancellation cancels} the scope when two or
750 * more subtasks fail.
751 * {@snippet lang=java :
752 * class CancelAfterTwoFailures<T> implements Predicate<Subtask<T>> {
753 * private final AtomicInteger failedCount = new AtomicInteger();
754 * @Override
755 * public boolean test(Subtask<T> subtask) {
756 * return subtask.state() == Subtask.State.FAILED
757 * && failedCount.incrementAndGet() >= 2;
758 * }
759 * }
760 *
761 * var joiner = Joiner.allUntil(new CancelAfterTwoFailures<String>());
762 * }
763 *
764 * <p> The following example uses {@code allUntil} to wait for all subtasks to
765 * complete without any cancellation. This is similar to {@link #awaitAll()}
766 * except that it yields a list of the completed subtasks.
767 * {@snippet lang=java :
768 * <T> List<Subtask<T>> invokeAll(Collection<Callable<T>> tasks) throws InterruptedException {
769 * try (var scope = StructuredTaskScope.open(Joiner.<T>allUntil(_ -> false))) {
770 * tasks.forEach(scope::fork);
771 * return scope.join();
772 * }
773 * }
774 * }
775 *
776 * <p> The following example uses {@code allUntil} to get the results of all
777 * subtasks that complete successfully within a timeout period.
778 * {@snippet lang=java :
779 * <T> List<T> invokeAll(Collection<Callable<T>> tasks, Duration timeout) throws InterruptedException {
780 * try (var scope = StructuredTaskScope.open(Joiner.<T>allUntil(_ -> false), cf -> cf.withTimeout(timeout))) {
781 * tasks.forEach(scope::fork);
782 * return scope.join()
783 * .stream()
784 * .filter(s -> s.state() == Subtask.State.SUCCESS)
785 * .map(Subtask::get)
786 * .toList();
787 * }
788 * }
789 * }
790 *
791 * @param isDone the predicate to evaluate completed subtasks
792 * @param <T> the result type of subtasks
793 */
794 static <T> Joiner<T, List<Subtask<T>>> allUntil(Predicate<Subtask<T>> isDone) {
795 return new Joiners.AllSubtasks<>(isDone);
796 }
797 }
798
799 /**
800 * Represents the configuration for a {@code StructuredTaskScope}.
801 *
802 * <p> The configuration for a {@code StructuredTaskScope} consists of a {@link
803 * ThreadFactory} to create threads, an optional name for the scope, and an optional
804 * timeout. The name is intended for monitoring and management purposes.
805 *
806 * <p> Creating a {@code StructuredTaskScope} with its 2-arg {@link #open(Joiner, UnaryOperator)
807 * open} method allows a different configuration to be used. The operator specified
808 * to the {@code open} method is applied to the default configuration and returns the
809 * configuration for the {@code StructuredTaskScope} under construction. The operator
810 * can use the {@code with-} prefixed methods defined here to specify the components
811 * of the configuration to use.
812 *
813 * <p> Unless otherwise specified, passing a {@code null} argument to a method
814 * in this class will cause a {@link NullPointerException} to be thrown.
815 *
816 * @since 25
817 */
818 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
819 sealed interface Configuration permits StructuredTaskScopeImpl.ConfigImpl {
820 /**
821 * {@return a new {@code Configuration} object with the given thread factory}
822 * The other components are the same as this object. The thread factory is used by
823 * a scope to create threads when {@linkplain #fork(Callable) forking} subtasks.
824 * @param threadFactory the thread factory
825 *
826 * @apiNote The thread factory will typically create {@linkplain Thread##virtual-threads
827 * virtual threads}, maybe with names for monitoring purposes, an {@linkplain
828 * Thread.UncaughtExceptionHandler uncaught exception handler}, or other properties
829 * configured.
830 *
831 * @see #fork(Callable)
832 */
833 Configuration withThreadFactory(ThreadFactory threadFactory);
834
835 /**
836 * {@return a new {@code Configuration} object with the given scope name}
837 * The other components are the same as this object. A scope is optionally
838 * named for the purposes of monitoring and management.
839 * @param name the name
840 */
841 Configuration withName(String name);
842
843 /**
844 * {@return a new {@code Configuration} object with the given timeout}
845 * The other components are the same as this object.
846 * @param timeout the timeout
847 *
848 * @apiNote Applications using deadlines, expressed as an {@link java.time.Instant},
849 * can use {@link Duration#between Duration.between(Instant.now(), deadline)} to
850 * compute the timeout for this method.
851 *
852 * @see #join()
853 * @see Joiner#onTimeout()
854 */
855 Configuration withTimeout(Duration timeout);
856 }
857
858 /**
859 * Exception thrown by {@link #join()} when the outcome is an exception rather than a
860 * result.
861 *
862 * @since 25
863 */
864 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
865 final class FailedException extends RuntimeException {
866 @java.io.Serial
867 static final long serialVersionUID = -1533055100078459923L;
868
869 /**
870 * Constructs a {@code FailedException} with the specified cause.
871 *
872 * @param cause the cause, can be {@code null}
873 */
874 FailedException(Throwable cause) {
875 super(cause);
876 }
877 }
878
879 /**
880 * Exception thrown by {@link #join()} if the scope was opened with a timeout,
881 * the timeout expired before or while waiting in {@code join}, and the {@link
882 * Joiner#onTimeout() Joiner.onTimeout} method throws this exception.
883 *
884 * @since 25
885 * @see Configuration#withTimeout(Duration)
886 * @see Joiner#onTimeout()
887 */
888 @PreviewFeature(feature = PreviewFeature.Feature.STRUCTURED_CONCURRENCY)
889 final class TimeoutException extends RuntimeException {
890 @java.io.Serial
891 static final long serialVersionUID = 705788143955048766L;
892
893 /**
894 * Constructs a {@code TimeoutException} with no detail message.
895 */
896 TimeoutException() { }
897 }
898
899 /**
900 * Opens a new {@code StructuredTaskScope} to use the given {@code Joiner} object and
901 * with configuration that is the result of applying the given operator to the
902 * {@linkplain ##DefaultConfiguration default configuration}.
903 *
904 * <p> The {@code configOperator} is called with the default configuration and returns
905 * the configuration for the new scope. The operator may, for example, set the
906 * {@linkplain Configuration#withThreadFactory(ThreadFactory) ThreadFactory} or set a
907 * {@linkplain Configuration#withTimeout(Duration) timeout}. If the operator completes
908 * with an exception or error then it is propagated by this method. If the operator
909 * returns {@code null} then {@code NullPointerException} is thrown.
910 *
911 * <p> If a {@code ThreadFactory} is set then its {@link ThreadFactory#newThread(Runnable)
912 * newThread} method will be called to create threads when {@linkplain #fork(Callable)
913 * forking} subtasks in this scope. If a {@code ThreadFactory} is not set then
914 * forking subtasks will create an unnamed virtual thread for each subtask.
915 *
916 * <p> If a {@linkplain Configuration#withTimeout(Duration) timeout} is set then it
917 * starts when the scope is opened. If the timeout expires before the scope has
918 * {@linkplain #join() joined} then the scope is {@linkplain ##Cancellation cancelled}
919 * and the {@code Joiner}'s {@link Joiner#onTimeout()} method is invoked to throw
920 * optionally throw {@link TimeoutException TimeoutException}.
921 *
922 * <p> The new scope is owned by the current thread. Only code executing in this
923 * thread can {@linkplain #fork(Callable) fork}, {@linkplain #join() join}, or
924 * {@linkplain #close close} the scope.
925 *
926 * <p> Construction captures the current thread's {@linkplain ScopedValue scoped
927 * value} bindings for inheritance by threads started in the scope.
928 *
929 * @param joiner the joiner
930 * @param configOperator the operator to produce the configuration
931 * @return a new scope
932 * @param <T> the result type of subtasks executed in the scope
933 * @param <R> the result type of the scope
934 * @since 26
935 */
936 static <T, R> StructuredTaskScope<T, R> open(Joiner<? super T, ? extends R> joiner,
937 UnaryOperator<Configuration> configOperator) {
938 return StructuredTaskScopeImpl.open(joiner, configOperator);
939 }
940
941 /**
942 * Opens a new {@code StructuredTaskScope}to use the given {@code Joiner} object. The
943 * scope is created with the {@linkplain ##DefaultConfiguration default configuration}.
944 * The default configuration has a {@code ThreadFactory} that creates unnamed
945 * {@linkplain Thread##irtual-threads virtual threads}, does not name the scope, and
946 * has no timeout.
947 *
948 * @implSpec
949 * This factory method is equivalent to invoking the 2-arg open method with the given
950 * joiner and the {@linkplain UnaryOperator#identity() identity operator}.
951 *
952 * @param joiner the joiner
953 * @return a new scope
954 * @param <T> the result type of subtasks executed in the scope
955 * @param <R> the result type of the scope
956 * @since 25
957 */
958 static <T, R> StructuredTaskScope<T, R> open(Joiner<? super T, ? extends R> joiner) {
959 return open(joiner, UnaryOperator.identity());
960 }
961
962 /**
963 * Opens a new {@code StructuredTaskScope} that can be used to fork subtasks that return
964 * results of any type. The scope's {@link #join()} method waits for all subtasks to
965 * succeed or any subtask to fail.
966 *
967 * <p> The {@code join} method returns {@code null} if all subtasks complete successfully.
968 * It throws {@link FailedException} if any subtask fails, with the exception from
969 * the first subtask to fail as the cause.
970 *
971 * <p> The scope is created with the {@linkplain ##DefaultConfiguration default
972 * configuration}. The default configuration has a {@code ThreadFactory} that creates
973 * unnamed {@linkplain Thread##virtual-threads virtual threads}, does not name the
974 * scope, and has no timeout.
975 *
976 * @implSpec
977 * This factory method is equivalent to invoking the 2-arg open method with a joiner
978 * created with {@link Joiner#awaitAllSuccessfulOrThrow() awaitAllSuccessfulOrThrow()}
979 * and the {@linkplain UnaryOperator#identity() identity operator}.
980 *
981 * @param <T> the result type of subtasks
982 * @return a new scope
983 * @since 25
984 */
985 static <T> StructuredTaskScope<T, Void> open() {
986 return open(Joiner.awaitAllSuccessfulOrThrow(), UnaryOperator.identity());
987 }
988
989 /**
990 * Fork a subtask by starting a new thread in this scope to execute a value-returning
991 * method. The new thread executes the subtask concurrently with the current thread.
992 * The parameter to this method is a {@link Callable}, the new thread executes its
993 * {@link Callable#call() call()} method.
994 *
995 * <p> This method first creates a {@link Subtask Subtask} object to represent the
996 * <em>forked subtask</em>. It invokes the joiner's {@link Joiner#onFork(Subtask) onFork}
997 * method with the subtask in the {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state.
998 * If the {@code onFork} completes with an exception or error then it is propagated by
999 * the {@code fork} method without creating a thread. If the scope is already
1000 * {@linkplain ##Cancellation cancelled}, or {@code onFork} returns {@code true} to
1001 * cancel the scope, then this method returns the {@code Subtask}, in the
1002 * {@link Subtask.State#UNAVAILABLE UNAVAILABLE} state, without creating a thread to
1003 * execute the subtask.
1004 *
1005 * <p> If the scope is not cancelled, and the {@code onFork} method returns {@code false},
1006 * then a thread is created with the {@link ThreadFactory} configured when the scope
1007 * was opened, and the thread is started. Forking a subtask inherits the current thread's
1008 * {@linkplain ScopedValue scoped value} bindings. The bindings must match the bindings
1009 * captured when the scope was opened. If the subtask completes (successfully or with
1010 * an exception) before the scope is cancelled, then the thread invokes the joiner's
1011 * {@link Joiner#onComplete(Subtask) onComplete} method with the subtask in the
1012 * {@link Subtask.State#SUCCESS SUCCESS} or {@link Subtask.State#FAILED FAILED} state.
1013 * If the {@code onComplete} method completes with an exception or error, then the
1014 * {@linkplain Thread.UncaughtExceptionHandler uncaught exception handler} is invoked
1015 * with the exception or error before the thread terminates.
1016 *
1017 * <p> This method returns the {@link Subtask Subtask} object. In some usages, this
1018 * object may be used to get its result. In other cases it may be used for correlation
1019 * or be discarded. To ensure correct usage, the {@link Subtask#get() Subtask.get()}
1020 * method may only be called by the scope owner to get the result after it has
1047 * parameter to this method is a {@link Runnable}, the new thread executes its
1048 * {@link Runnable#run() run} method, and {@link Subtask#get() Subtask.get()} returns
1049 * {@code null} if the subtask completes successfully.
1050 *
1051 * @param task the task for the thread to execute
1052 * @param <U> the result type
1053 * @return the subtask
1054 * @throws WrongThreadException if the current thread is not the scope owner
1055 * @throws IllegalStateException if the owner has already {@linkplain #join() joined}
1056 * or the scope is closed
1057 * @throws StructureViolationException if the current scoped value bindings are not
1058 * the same as when the scope was created
1059 * @throws RejectedExecutionException if the thread factory rejected creating a
1060 * thread to run the subtask
1061 * @since 25
1062 */
1063 <U extends T> Subtask<U> fork(Runnable task);
1064
1065 /**
1066 * Returns the result, or throws, after waiting for all subtasks to complete or
1067 * the scope to be {@linkplain ##Cancellation cancelled}.
1068 *
1069 * <p> This method waits for all subtasks started in this scope to complete or the
1070 * scope to be cancelled. Once finished waiting, the {@code Joiner}'s {@link
1071 * Joiner#result() result()} method is invoked to get the result or throw an exception.
1072 * If the {@code result()} method throws then {@code join()} throws
1073 * {@code FailedException} with the exception from the {@code Joiner} as the cause.
1074 *
1075 * <p> If a {@linkplain Configuration#withTimeout(Duration) timeout} is configured,
1076 * and the timeout expires before or while waiting, then the scope is cancelled and
1077 * the {@code Joiner}'s {@link Joiner#onTimeout() onTimeout()} method is invoked
1078 * before calling the {@code Joiner}'s {@code result()} method. If the {@code onTimeout()}
1079 * method throws {@link TimeoutException TimeoutException} (or throws any exception
1080 * or error), then it is propagated by this method. If the {@code onTimeout()} method
1081 * does not throw then the {@code Joiner}'s {@code result()} method is invoked to
1082 * get the result or throw.
1083 *
1084 * <p> This method may only be invoked by the scope owner. Once the result or
1085 * exception outcome is obtained, this method may not be invoked again. The only
1086 * case where the method may be called again is where {@code InterruptedException}
1087 * is thrown while waiting.
1088 *
1089 * @return the result
1090 * @throws WrongThreadException if the current thread is not the scope owner
1091 * @throws IllegalStateException if already joined or this scope is closed
1092 * @throws FailedException if the <i>outcome</i> is an exception, thrown with the
1093 * exception from {@link Joiner#result() Joiner.result()} as the cause
1094 * @throws TimeoutException if a timeout is set, the timeout expires before or while
1095 * waiting, and {@link Joiner#onTimeout() Joiner.onTimeout()} throws this exception
1096 * @throws InterruptedException if interrupted while waiting
1097 * @since 25
1098 */
1099 R join() throws InterruptedException;
1100
1101 /**
1102 * {@return {@code true} if this scope is {@linkplain ##Cancellation cancelled} or in
1103 * the process of being cancelled, otherwise {@code false}}
1104 *
1105 * <p> Cancelling the scope prevents new threads from starting in the scope and
1106 * {@linkplain Thread#interrupt() interrupts} threads executing unfinished subtasks.
1107 * It may take some time before the interrupted threads finish execution; this
1108 * method may return {@code true} before all threads have been interrupted or before
1109 * all threads have finished.
1110 *
1111 * @apiNote A task with a lengthy "forking phase" (the code that executes before
1112 * it invokes {@link #join() join}) may use this method to avoid doing work in cases
1113 * where scope is cancelled by the completion of a previously forked subtask or timeout.
1114 *
1115 * @since 25
1116 */
1117 boolean isCancelled();
1118
1119 /**
1120 * Closes this scope.
1121 *
1122 * <p> This method first {@linkplain ##Cancellation cancels} the scope, if not
1123 * already cancelled. This interrupts the threads executing unfinished subtasks. This
1124 * method then waits for all threads to finish. If interrupted while waiting then it
1125 * will continue to wait until the threads finish, before completing with the
1126 * {@linkplain Thread#isInterrupted() interrupted status} set.
1127 *
1128 * <p> This method may only be invoked by the scope owner. If the scope
1129 * is already closed then the scope owner invoking this method has no effect.
1130 *
1131 * <p> A {@code StructuredTaskScope} is intended to be used in a <em>structured
1132 * manner</em>. If this method is called to close a scope before nested task
1133 * scopes are closed then it closes the underlying construct of each nested scope
1134 * (in the reverse order that they were created in), closes this scope, and then
1135 * throws {@link StructureViolationException}.
1136 * Similarly, if this method is called to close a scope while executing with
1137 * {@linkplain ScopedValue scoped value} bindings, and the scope was created
1138 * before the scoped values were bound, then {@code StructureViolationException} is
1139 * thrown after closing the scope.
1140 * If a thread terminates without first closing scopes that it owns then
1141 * termination will cause the underlying construct of each of its open tasks scopes to
1142 * be closed. Closing is performed in the reverse order that the scopes were
1143 * created in. Thread termination may therefore be delayed when the scope owner
1144 * has to wait for threads forked in these scopes to finish.
1145 *
1146 * @throws IllegalStateException thrown after closing the scope if the scope
1147 * owner did not attempt to join after forking
1148 * @throws WrongThreadException if the current thread is not the scope owner
1149 * @throws StructureViolationException if a structure violation was detected
1150 */
1151 @Override
1152 void close();
1153 }
|