StructuredTaskScope.ShutdownOnFailure (Java SE 21 & JDK 21)
Description: declaration: module: java.base, package: java.util.concurrent, class: StructuredTaskScope, class: ShutdownOnFailure
Keywords: java.util.concurrent.StructuredTaskScope.ShutdownOnFailure class

Module java.base
Package java.util.concurrent

# Class StructuredTaskScope.ShutdownOnFailure

java.lang.Object
java.util.concurrent.StructuredTaskScopePREVIEW<Object>
java.util.concurrent.StructuredTaskScope.ShutdownOnFailure

All Implemented Interfaces:
  `AutoCloseable`

Enclosing class:
  `StructuredTaskScopePREVIEW<T>`

public static final class StructuredTaskScope.ShutdownOnFailure extends StructuredTaskScopePREVIEW<Object>
`ShutdownOnFailure` is a preview API of the Java platform.
Programs can only use `ShutdownOnFailure` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A `StructuredTaskScope` that captures the exception of the first subtask to failPREVIEW. 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 results for all subtasks are required ("invoke all"); if any subtask fails then 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.

API Note:
  This class implements a policy to shut down the task scope when a subtask fails. There shouldn't be any need to directly shut down the task scope with the `shutdown`PREVIEW method.
Since:
  21

- ## Nested Class Summary

  ## Nested classes/interfaces declared in class java.util.concurrent.StructuredTaskScopePREVIEW

  `StructuredTaskScope.ShutdownOnFailurePREVIEW, StructuredTaskScope.ShutdownOnSuccessPREVIEW<T>, StructuredTaskScope.SubtaskPREVIEW<T>`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ShutdownOnFailure()`
  Constructs a new unnamed `ShutdownOnFailure` that creates virtual threads.
  `ShutdownOnFailure(String name, ThreadFactory factory)`
  Constructs a new `ShutdownOnFailure` with the given name and thread factory.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Optional<Throwable>`
  `exception()`
  Returns the exception of the first subtask that failedPREVIEW.
  `StructuredTaskScope.ShutdownOnFailurePREVIEW`
  `join()`
  Wait for all subtasks started in this task scope to complete or for a subtask to failPREVIEW.
  `StructuredTaskScope.ShutdownOnFailurePREVIEW`
  `joinUntil(Instant deadline)`
  Wait for all subtasks started in this task scope to complete or for a subtask to failPREVIEW, up to the given deadline.
  `void`
  `throwIfFailed()`
  Throws if a subtask failedPREVIEW.
  `<X extends Throwable>
  void`
  `throwIfFailed(Function<Throwable,? extends X> esf)`
  Throws the exception produced by the given exception supplying function if a subtask failedPREVIEW.

  ### Methods declared in class java.util.concurrent.StructuredTaskScopePREVIEW

  `close, ensureOwnerAndJoined, fork, handleComplete, isShutdown, shutdown`

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ShutdownOnFailure

    public ShutdownOnFailure(String name, ThreadFactory factory)
    Constructs a new `ShutdownOnFailure` with the given name and thread factory. The task scope is optionally named for the purposes of monitoring and management. The thread factory is used to `create` threads 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 null
      `factory` - the thread factory

  - ### ShutdownOnFailure

    public ShutdownOnFailure()
    Constructs a new unnamed `ShutdownOnFailure` that creates virtual threads.
    Implementation Requirements:
      This constructor is equivalent to invoking the 2-arg constructor with a name of `null` and a thread factory that creates virtual threads.

- ## Method Details

  - ### join

    public StructuredTaskScope.ShutdownOnFailurePREVIEW join() throws InterruptedException
    Wait for all subtasks started in this task scope to complete or for a subtask to failPREVIEW.

    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 fails, or the current thread is interrupted. It also stops waiting if the `shutdown`PREVIEW method is invoked directly to shut down this task scope.

    This method may only be invoked by the task scope owner.

    Overrides:
      `join` in class `StructuredTaskScopePREVIEW<Object>`
    Returns:
      this task scope
    Throws:
      `IllegalStateException` - if this task scope is closed
      `WrongThreadException` - if the current thread is not the task scope owner
      `InterruptedException` - if interrupted while waiting

  - ### joinUntil

    public StructuredTaskScope.ShutdownOnFailurePREVIEW joinUntil(Instant deadline) throws InterruptedException, TimeoutException
    Wait for all subtasks started in this task scope to complete or for a subtask to failPREVIEW, 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 fails, the deadline is reached, or the current thread is interrupted. It also stops waiting if the `shutdown`PREVIEW method is invoked directly to shut down this task scope.

    This method may only be invoked by the task scope owner.

    Overrides:
      `joinUntil` in class `StructuredTaskScopePREVIEW<Object>`
    Parameters:
      `deadline` - the deadline
    Returns:
      this task scope
    Throws:
      `IllegalStateException` - if this task scope is closed
      `WrongThreadException` - if the current thread is not the task scope owner
      `InterruptedException` - if interrupted while waiting
      `TimeoutException` - if the deadline is reached while waiting

  - ### exception

    public Optional<Throwable> exception()
    Returns the exception of the first subtask that failedPREVIEW. If no subtasks failed then an empty `Optional` is returned.
    Returns:
      the exception for the first subtask to fail or an empty optional if no subtasks failed
    Throws:
      `WrongThreadException` - if the current thread is not the task scope owner
      `IllegalStateException` - if the task scope owner did not join after forking

  - ### throwIfFailed

    public void throwIfFailed() throws ExecutionException
    Throws if a subtask failedPREVIEW. If any subtask failed with an exception then `ExecutionException` is thrown with the exception of the first subtask to fail as the cause. This method does nothing if no subtasks failed.
    Throws:
      `ExecutionException` - if a subtask failed
      `WrongThreadException` - if the current thread is not the task scope owner
      `IllegalStateException` - if the task scope owner did not join after forking

  - ### throwIfFailed

    public <X extends Throwable> void throwIfFailed(Function<Throwable,? extends X> esf) throws X
    Throws the exception produced by the given exception supplying function if a subtask failedPREVIEW. If any subtask failed with an exception then the function is invoked with the exception of the first subtask to fail. The exception returned by the function is thrown. This method does nothing if no subtasks failed.
    Type Parameters:
      `X` - type of the exception to be thrown
    Parameters:
      `esf` - the exception supplying function
    Throws:
      `X` - produced by the exception supplying function
      `WrongThreadException` - if the current thread is not the task scope owner
      `IllegalStateException` - if the task scope owner did not join after forking