Интерфейс StructuredTaskScope.Joiner<T, R, R_X extends Throwable>

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

Примечание API:

Этот метод вызывается методами fork. Его не следует вызывать напрямую.

Требования к реализации:

Реализация по умолчанию выбрасывает NullPointerException, если подзадача — null. Она выбрасывает IllegalArgumentException, если подзадача не находится в состоянии UNAVAILABLE^PREVIEW, в противном случае она возвращает false.

Параметры:

subtask — подзадача

Возвращает:

true для отмены области видимости, в противном случае — false

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

Примечание API:

Этот метод вызывается подзадачами при их завершении. Его не следует вызывать напрямую.

Требования к реализации:

Реализация по умолчанию выбрасывает NullPointerException, если подзадача — null. Она выбрасывает IllegalArgumentException, если подзадача не находится в состоянии SUCCESS^PREVIEW или FAILED^PREVIEW, в противном случае она возвращает false.

Параметры:

subtask — подзадача

Возвращает:

true для отмены области видимости, в противном случае — false

R result() throws R_X

Примечание API:

Этот метод вызывается методом join(). Его не следует вызывать напрямую.

Возвращает:

результат

Выбрасывает:

R_X — если результатом является исключение

R timeout() throws R_X

Примечание API:

Этот метод вызывается методом join(). Его не следует вызывать напрямую.

Возвращает:

результат

Выбрасывает:

R_X — с причиной CancelledByTimeoutException, если результатом является исключение

Начиная с:

27

static <T, R_X extends Throwable> StructuredTaskScope.JoinerPREVIEW<T,List<T>,R_X> allSuccessfulOrThrow(Function<Throwable, R_X> esf)

Примечание API:

Joiner, возвращаемые этим методом, подходят для случаев, когда все подзадачи возвращают результат одного типа. Они избавляют от необходимости вести учёт и хранить ссылку на объекты Subtask^PREVIEW, возвращаемые методом fork(Callable)^PREVIEW. Joiner, возвращаемые методами awaitAllSuccessfulOrThrow(Function) и awaitAllSuccessfulOrThrow(), подходят для случаев, когда подзадачи возвращают результаты разных типов и необходимо хранить ссылку на объекты Subtask.

В следующем примере показан метод, который открывает StructuredTaskScope с Joiner, созданным с помощью allSuccessfulOrThrow(Function). Метод вызывается с коллекцией объектов Callable. Он запускает^PREVIEW подзадачу для выполнения каждого объекта Callable, ожидает завершения всех подзадач без ошибок в join()^PREVIEW, а затем возвращает список результатов. Если какая-либо подзадача завершается с ошибкой, метод выбрасывает исключение времени выполнения CompletionException, причиной которого является исключение первой завершившейся с ошибкой подзадачи.

  <T> List<T> invokeAll(Collection<Callable<T>> tasks) throws InterruptedException {
        try (var scope = StructuredTaskScope.open(
                Joiner.<T, CompletionException>allSuccessfulOrThrow(CompletionException::new))) {
            tasks.forEach(scope::fork);
            List<T> results = scope.join();
            return results;
        }
  }

Параметры типа:

T — тип результата подзадач

R_X — тип исключения, выбрасываемого методом join()^PREVIEW

Параметры:

esf — функция, предоставляющая исключение

Возвращает:

новый Joiner, формирующий список всех результатов, если все подзадачи завершаются успешно

Начиная с:

27

См. также:

• allSuccessfulOrThrow()

static <T> StructuredTaskScope.JoinerPREVIEW<T, List<T>, ExecutionException> allSuccessfulOrThrow()

Требования к реализации:

Joiner, возвращаемый этим методом, эквивалентен вызову allSuccessfulOrThrow(ExecutionException::new).

Параметры типа:

T — тип результата подзадач

Возвращает:

новый Joiner, формирующий список всех результатов, если все подзадачи завершаются успешно

static <T, R_X extends Throwable> StructuredTaskScope.JoinerPREVIEW<T,T,R_X> anySuccessfulOrThrow(Function<Throwable, R_X> esf)

Примечание API:

В следующем примере показан метод, который открывает StructuredTaskScope с Joiner, созданным с помощью anySuccessfulOrThrow(Function). Метод вызывается с коллекцией объектов Callable. Он запускает^PREVIEW подзадачу для выполнения каждого объекта Callable и ожидает в join()^PREVIEW успешного завершения любой подзадачи, возвращая её результат. Если все подзадачи завершаются с ошибкой, метод выбрасывает исключение времени выполнения CompletionException, причиной которого является исключение завершившейся с ошибкой подзадачи.

  <T> T invokeAny(Collection<Callable<T>> tasks) throws InterruptedException {
        try (var scope = StructuredTaskScope.open(
              Joiner.<T, CompletionException>anySuccessfulOrThrow(CompletionException::new))) {
            tasks.forEach(scope::fork);
            T result = scope.join();
            return result;
        }
  }

Параметры типа:

T — тип результата подзадач

R_X — тип исключения, выбрасываемого методом join()^PREVIEW

Параметры:

esf — функция, предоставляющая исключение

Возвращает:

новый Joiner, формирующий результат любой успешно завершившейся подзадачи

Начиная с:

27

См. также:

• anySuccessfulOrThrow()

static <T> StructuredTaskScope.JoinerPREVIEW<T, T, ExecutionException> anySuccessfulOrThrow()

Требования к реализации:

Joiner, возвращаемый этим методом, эквивалентен вызову anySuccessfulOrThrow(ExecutionException::new).

Параметры типа:

T — тип результата подзадач

Возвращает:

новый Joiner, формирующий результат любой успешно завершившейся подзадачи

Начиная с:

26

static <T, R_X extends Throwable> StructuredTaskScope.JoinerPREVIEW<T,Void,R_X> awaitAllSuccessfulOrThrow(Function<Throwable, R_X> esf)

Примечание API:

Joiner, возвращаемые этим методом, подходят для случаев, когда подзадачи возвращают результаты разных типов и необходимо хранить ссылку на каждый объект Subtask^PREVIEW. Joiner, возвращаемые методами allSuccessfulOrThrow(Function) и allSuccessfulOrThrow(), подходят для случаев, когда подзадачи возвращают результат одного типа.

В следующем примере открывается StructuredTaskScope с Joiner, созданным с помощью awaitAllSuccessfulOrThrow(). Запускаются две подзадачи с помощью вызова fork^PREVIEW, после чего выполняется ожидание в join()^PREVIEW успешного завершения обеих подзадач или сбоя любой из них. Если обе подзадачи завершаются успешно, для получения их результатов вызывается Subtask.get()^PREVIEW для каждой подзадачи. Если какая-либо подзадача завершается с ошибкой, выбрасывается исключение времени выполнения CompletionException, причиной которого является исключение завершившейся с ошибкой подзадачи.

  try (var scope = StructuredTaskScope.open(
           Joiner.awaitAllSuccessfulOrThrow(CompletionException::new))) {
      Subtask<String> subtask1 = scope.fork(callable1);
      Subtask<Integer> subtask2 = scope.fork(callable2);

      // throws CompletionException if either subtask fails
      scope.join();

      // both subtasks completed successfully
      var result = new MyResult(subtask1.get(), subtask2.get());
  }

Параметры типа:

T — тип результата подзадач

R_X — тип исключения, выбрасываемого методом join()^PREVIEW

Параметры:

esf — функция, предоставляющая исключение

Возвращает:

новый Joiner, который заставляет метод join()^PREVIEW ожидать успешного завершения всех подзадач

Начиная с:

27

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

Требования к реализации:

Joiner, возвращаемый этим методом, эквивалентен вызову awaitAllSuccessfulOrThrow(ExecutionException::new).

Параметры типа:

T — тип результата подзадач

Возвращает:

новый Joiner, который заставляет метод join()^{ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ} ожидать успешного завершения всех подзадач

См. также:

• StructuredTaskScope.open()^{ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ}
• StructuredTaskScope.open(UnaryOperator)^{ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ}

static <T> StructuredTaskScope.JoinerPREVIEW<T, List<StructuredTaskScope.SubtaskPREVIEW<T>>, RuntimeException> allUntil(Predicate<? super StructuredTaskScope.SubtaskPREVIEW<T>> isDone)

Примечание к API:

В следующем примере используется allUntil для создания Joiner, который отменяет область, если две или более подзадачи завершаются с ошибкой.

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

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

В следующем примере используется allUntil для создания Joiner, который отменяет область, если какая-либо подзадача завершается успешно. Подзадачи группируются по их состоянию, чтобы создать карту с не более чем тремя парами «ключ-значение». Ключом карты является состояние подзадачи, а значением — список подзадач в этом состоянии.

    Predicate<Subtask<?>> isSuccessful = s -> s.state() == Subtask.State.SUCCESS;

    try (var scope = StructuredTaskScope.open(Joiner.<String>allUntil(isSuccessful))) {
        tasks.forEach(scope::fork);

        Map<Subtask.State, List<Subtask<String>>> subtasksByState = scope.join()
                .stream()
                .collect(Collectors.groupingBy(Subtask::state));
    }

В следующем примере показан метод, использующий allUntil для создания Joiner, который не отменяет область. Метод ожидает завершения всех подзадач или истечения тайм-аута. Он возвращает список всех подзадач в том же порядке, что и коллекция вызываемых объектов, даже если тайм-аут истекает до вызова join() или во время его выполнения.

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

Параметры типа:

T — тип результата подзадач

Параметры:

isDone — предикат для вычисления по завершившимся подзадачам

Возвращает:

новый Joiner, который формирует список всех подзадач после завершения всех подзадач или если вычисление предиката для завершившейся подзадачи приводит к отмене области