Interface StructuredTaskScope.Joiner<T,R>

default boolean onFork(StructuredTaskScope.SubtaskPREVIEW<? extends T> subtask)

API Note:

This method is invoked by the fork methods. It should not be invoked directly.

Implementation Requirements:

The default implementation throws NullPointerException if the subtask is null. It throws IllegalArgumentException if the subtask is not in the UNAVAILABLE^PREVIEW state, it otherwise returns false.

Parameters:

subtask - the subtask

Returns:

true to cancel the scope, otherwise false

default boolean onComplete(StructuredTaskScope.SubtaskPREVIEW<? extends T> subtask)

API Note:

This method is invoked by subtasks when they complete. It should not be invoked directly.

Implementation Requirements:

The default implementation throws NullPointerException if the subtask is null. It throws IllegalArgumentException if the subtask is not in the SUCCESS^PREVIEW or FAILED^PREVIEW state, it otherwise returns false.

Parameters:

subtask - the subtask

Returns:

true to cancel the scope, otherwise false

R result() throws Throwable

API Note:

This method is invoked by the join method. It should not be invoked directly.

Returns:

the result

Throws:

Throwable - the exception

static <T> StructuredTaskScope.JoinerPREVIEW<T, Stream<StructuredTaskScope.SubtaskPREVIEW<T>>> allSuccessfulOrThrow()

API Note:

Joiners returned by this method are suited to cases where all subtasks return a result of the same type. Joiners returned by awaitAllSuccessfulOrThrow() are suited to cases where the subtasks return results of different types.

Type Parameters:

T - the result type of subtasks

Returns:

a new Joiner object that yields a stream of all subtasks when all subtasks complete successfully

static <T> StructuredTaskScope.JoinerPREVIEW<T,T> anySuccessfulResultOrThrow()

Type Parameters:

T - the result type of subtasks

Returns:

a new Joiner object that yields the result of any subtask that completed successfully

static <T> StructuredTaskScope.JoinerPREVIEW<T,Void> awaitAllSuccessfulOrThrow()

API Note:

Joiners returned by this method are suited to cases where subtasks return results of different types. Joiners returned by allSuccessfulOrThrow() are suited to cases where the subtasks return a result of the same type.

Type Parameters:

T - the result type of subtasks

Returns:

a new Joiner object that waits for subtasks to complete successfully

static <T> StructuredTaskScope.JoinerPREVIEW<T,Void> awaitAll()

API Note:

This Joiner is useful for cases where subtasks make use of side-effects rather than return results or fail with exceptions. The fork(Runnable)^PREVIEW method can be used to fork subtasks that do not return a result.

This Joiner can also be used for fan-in scenarios where subtasks are forked to handle incoming connections and the number of subtasks is unbounded. In this example, the thread executing the acceptLoop method will only stop when interrupted or the listener socket is closed asynchronously.

  void acceptLoop(ServerSocket listener) throws IOException, InterruptedException {
      try (var scope = StructuredTaskScope.open(Joiner.<Socket>awaitAll())) {
          while (true) {
              Socket socket = listener.accept();
              scope.fork(() -> handle(socket));
          }
      }
  }

Type Parameters:

T - the result type of subtasks

Returns:

a new Joiner object that waits for all subtasks to complete

static <T> StructuredTaskScope.JoinerPREVIEW<T, Stream<StructuredTaskScope.SubtaskPREVIEW<T>>> allUntil(Predicate<StructuredTaskScope.SubtaskPREVIEW<? extends T>> isDone)

   class CancelAfterTwoFailures<T> implements Predicate<Subtask<? extends T>> {
        private final AtomicInteger failedCount = new AtomicInteger();
        @Override
        public boolean test(Subtask<? extends T> subtask) {
            return subtask.state() == Subtask.State.FAILED
                    && failedCount.incrementAndGet() >= 2;
        }
    }

    var joiner = Joiner.all(new CancelAfterTwoFailures<String>());

   <T> List<Subtask<T>> invokeAll(Collection<Callable<T>> tasks) throws InterruptedException {
       try (var scope = StructuredTaskScope.open(Joiner.<T>allUntil(_ -> false))) {
           tasks.forEach(scope::fork);
           return scope.join().toList();
       }
   }

Type Parameters:

T - the result type of subtasks

Parameters:

isDone - the predicate to evaluate completed subtasks

Returns:

a new Joiner object that yields a stream of all subtasks when all subtasks complete or a predicate returns true to cancel the scope