- Type Parameters:
T- the result type
- All Implemented Interfaces:
AutoCloseable
- Enclosing class:
StructuredTaskScopePREVIEW<T>
ShutdownOnSuccess is a preview API of the Java platform.
StructuredTaskScope that captures the result of the first subtask to
complete successfullyPREVIEW. Once captured, it
shuts downPREVIEW the task scope to interrupt unfinished threads
and wakeup the task scope owner. The policy implemented by this class is intended
for cases where the result of any subtask will do ("invoke any") and where the
results of other unfinished subtasks are no longer needed.
Unless otherwise specified, passing a null argument to a method
in this class will cause a NullPointerException to be thrown.
-
Nested Class Summary
Nested classes/interfaces declared in class java.util.concurrent.StructuredTaskScopePREVIEW
StructuredTaskScope.ShutdownOnFailurePREVIEW, StructuredTaskScope.ShutdownOnSuccessPREVIEW<T>, StructuredTaskScope.SubtaskPREVIEW<T> -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a new unnamedShutdownOnSuccessthat creates virtual threads.ShutdownOnSuccess(String name, ThreadFactory factory) Constructs a newShutdownOnSuccesswith the given name and thread factory. -
Method Summary
Modifier and TypeMethodDescriptionjoin()Wait for a subtask started in this task scope to complete successfullyPREVIEW or all subtasks to complete.Wait for a subtask started in this task scope to complete successfullyPREVIEW or all subtasks to complete, up to the given deadline.result()Returns the result of the first subtask that completed successfullyPREVIEW.Returns the result of the first subtask that completed successfullyPREVIEW, otherwise throws an exception produced by the given exception supplying function.Methods declared in class java.util.concurrent.StructuredTaskScopePREVIEW
close, ensureOwnerAndJoined, fork, handleComplete, isShutdown, shutdown
-
Constructor Details
-
ShutdownOnSuccess
Constructs a newShutdownOnSuccesswith the given name and thread factory. The task scope is optionally named for the purposes of monitoring and management. The thread factory is used tocreatethreads when subtasks are forkedPREVIEW. The task scope is owned by the current thread.Construction captures the current thread's scoped valuePREVIEW bindings for inheritance by threads started in the task scope. The Tree Structure section in the class description details how parent-child relations are established implicitly for the purpose of inheritance of scoped value bindings.
- Parameters:
name- the name of the task scope, can be nullfactory- the thread factory
-
ShutdownOnSuccess
public ShutdownOnSuccess()Constructs a new unnamedShutdownOnSuccessthat creates virtual threads.- Implementation Requirements:
- This constructor is equivalent to invoking the 2-arg constructor with
a name of
nulland a thread factory that creates virtual threads.
-
-
Method Details
-
join
Wait for a subtask started in this task scope to complete successfullyPREVIEW or all subtasks to complete.This method waits for all subtasks by waiting for all threads startedPREVIEW in this task scope to finish execution. It stops waiting when all threads finish, a subtask completes successfully, or the current thread is interrupted. It also stops waiting if the
shutdownPREVIEW method is invoked directly to shut down this task scope.This method may only be invoked by the task scope owner.
- Overrides:
joinin classStructuredTaskScopePREVIEW<T>- Returns:
- this task scope
- Throws:
IllegalStateException- if this task scope is closedWrongThreadException- if the current thread is not the task scope ownerInterruptedException- if interrupted while waiting
-
joinUntil
public StructuredTaskScope.ShutdownOnSuccessPREVIEW<T> joinUntil(Instant deadline) throws InterruptedException, TimeoutException Wait for a subtask started in this task scope to complete successfullyPREVIEW or all subtasks to complete, up to the given deadline.This method waits for all subtasks by waiting for all threads startedPREVIEW in this task scope to finish execution. It stops waiting when all threads finish, a subtask completes successfully, the deadline is reached, or the current thread is interrupted. It also stops waiting if the
shutdownPREVIEW method is invoked directly to shut down this task scope.This method may only be invoked by the task scope owner.
- Overrides:
joinUntilin classStructuredTaskScopePREVIEW<T>- Parameters:
deadline- the deadline- Returns:
- this task scope
- Throws:
IllegalStateException- if this task scope is closedWrongThreadException- if the current thread is not the task scope ownerInterruptedException- if interrupted while waitingTimeoutException- if the deadline is reached while waiting
-
result
Returns the result of the first subtask that completed successfullyPREVIEW.When no subtask completed successfully, but a subtask failedPREVIEW then
ExecutionExceptionis thrown with the subtask's exception as the cause.- Returns:
- the result of the first subtask that completed successfullyPREVIEW
- Throws:
ExecutionException- if no subtasks completed successfully but at least one subtask failedIllegalStateException- if no subtasks completed or the task scope owner did not join after forkingWrongThreadException- if the current thread is not the task scope owner
-
result
Returns the result of the first subtask that completed successfullyPREVIEW, otherwise throws an exception produced by the given exception supplying function.When no subtask completed successfully, but a subtask failedPREVIEW, then the exception supplying function is invoked with subtask's exception.
- Type Parameters:
X- type of the exception to be thrown- Parameters:
esf- the exception supplying function- Returns:
- the result of the first subtask that completed with a result
- Throws:
X- if no subtasks completed successfully but at least one subtask failedIllegalStateException- if no subtasks completed or the task scope owner did not join after forkingWrongThreadException- if the current thread is not the task scope owner
-
ShutdownOnSuccesswhen preview features are enabled.