Класс StructuredTaskScope<T>

Базовая операция

    Callable<String> task1 = ...
    Callable<Integer> task2 = ...

    try (var scope = new StructuredTaskScope<Object>()) {

        Subtask<String> subtask1 = scope.fork(task1);
        Subtask<Integer> subtask2 = scope.fork(task2);

        scope.join();

        ... process results/exceptions ...

    } // close

В следующем примере создаётся набор однородных подзадач, ожидают завершения всех из них с помощью метода join и используются метод Subtask.State^ПРЕВЬЮ для разделения подзадач на набор подзадач, завершившихся успешно, и набор подзадач, завершившихся неудачно.

    List<Callable<String>> callables = ...

    try (var scope = new StructuredTaskScope<String>()) {

        List<Subtask<String>> subtasks = callables.stream().map(scope::fork).toList();

        scope.join();

        Map<Boolean, Set<Subtask<String>>> map = subtasks.stream()
                .collect(Collectors.partitioningBy(h -> h.state() == Subtask.State.SUCCESS,
                                                   Collectors.toSet()));

    } // close

Для обеспечения корректного использования, методы join и close могут быть вызваны только владельцем (потоком, который открыл/создал область задачи), и метод close выбрасывает исключение после закрытия, если владелец не вызвал метод join после создания подзадач.

StructuredTaskScope определяет метод shutdown для остановки области задачи без её закрытия. Метод shutdown() прерывает все незавершенные подзадачи, прерывая потоки. Он предотвращает запуск новых потоков в области задачи. Если владелец ожидает в методе join, он проснётся.

Остановка используется для прерывания и позволяет подклассам реализовывать политику, которая не требует завершения всех подзадач.

Подклассы с политиками для общих случаев

1. ShutdownOnSuccess^ПРЕВЬЮ захватывает результат первой подзадачи, завершившейся успешно. После захвата он останавливает область задачи, прерывает незавершенные потоки и разбуживает владельца. Этот класс предназначен для случаев, когда результат любой подзадачи подойдёт ("вызвать любую"), и нет необходимости ожидать результатов других незавершенных подзадач. Он определяет методы для получения первого результата или выбрасывает исключение, если все подзадачи завершатся неудачно.
2. ShutdownOnFailure^ПРЕВЬЮ захватывает исключение первой подзадачи, завершившейся неудачно. После захвата он останавливает область задачи, прерывает незавершенные потоки и разбуживает владельца. Этот класс предназначен для случаев, когда результаты всех подзадач необходимы ("вызвать все"); если любая подзадача завершится неудачно, результаты других незавершенных подзадач больше не нужны. Он определяет методы для выбрасывания исключения, если любая из подзадач завершится неудачно.

Ниже приведены два примера, использующих эти два класса. В обоих случаях создаётся пара подзадач для получения ресурсов из двух URL-местоположений "left" и "right". Первый пример создаёт объект ShutdownOnSuccess для захвата результата первой подзадачи, завершившейся успешно, прерывая другие посредством остановки области задачи. Главная задача ожидает в join до тех пор, пока либо подзадача завершится с результатом, либо обе подзадачи завершатся неудачно. Он вызывает метод result(Function)^ПРЕВЬЮ для получения захваченного результата. Если обе подзадачи завершатся неудачно, этот метод выбрасывает WebApplicationException с исключением одной из подзадач в качестве причины.

    try (var scope = new StructuredTaskScope.ShutdownOnSuccess<String>()) {

        scope.fork(() -> fetch(left));
        scope.fork(() -> fetch(right));

        scope.join();

        String result = scope.result(e -> new WebApplicationException(e));

        ...
    }

   Instant deadline = ...

   try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {

        Supplier<String> supplier1 = scope.fork(() -> query(left));
        Supplier<String> supplier2 = scope.fork(() -> query(right));

        scope.joinUntil(deadline);

        scope.throwIfFailed(e -> new WebApplicationException(e));

        // both subtasks completed successfully
        String result = Stream.of(supplier1, supplier2)
                .map(Supplier::get)
                .collect(Collectors.joining(", ", "{ ", " }"));

        ...
    }

Расширение StructuredTaskScope

Подкласс обычно определяет методы для предоставления результатов, состояния или других результатов коду, выполняющемуся после метода join . Подкласс, собирающий результаты и игнорирующий подзадачи, завершившиеся неудачно, может определить метод, возвращающий результаты. Подкласс, реализующий политику остановки при завершении подзадачи неудачно, может определить метод для получения исключения первой подзадачи, завершившейся неудачно.

Ниже приведён пример простой реализации StructuredTaskScope , которая собирает однородные подзадачи, завершившиеся успешно. Он определяет метод "completedSuccessfully()", который главная задача может вызвать после объединения.

    class CollectingScope<T> extends StructuredTaskScope<T> {
        private final Queue<Subtask<? extends T>> subtasks = new LinkedTransferQueue<>();

        @Override
        protected void handleComplete(Subtask<? extends T> subtask) {
            if (subtask.state() == Subtask.State.SUCCESS) {
                subtasks.add(subtask);
            }
        }

        @Override
        public CollectingScope<T> join() throws InterruptedException {
            super.join();
            return this;
        }

        public Stream<Subtask<? extends T>> completedSuccessfully() {
            super.ensureOwnerAndJoined();
            return subtasks.stream();
        }
    }

Реализация метода completedSuccessfully() в примере вызывает ensureOwnerAndJoined() для обеспечения того, что метод может быть вызван только владельческим потоком и только после того, как он объединился.

Деревовидная структура

• Родительско-дочернее отношение устанавливается, когда поток, запущенный в области задачи, открывает свою собственную область задачи. Поток, запущенный в области задачи "A", открывающий область задачи "B", устанавливает родительско-дочернее отношение, где область задачи "A" является родителем области задачи "B".
• Родительско-дочернее отношение устанавливается при вложенности. Если поток открывает область задачи "B", а затем открывает область задачи "C" (перед закрытием "B"), то содержащая область задачи "B" является родителем вложенной области задачи "C".

Структура дерева поддерживает:

• Наследование связанных значений^ПРЕВЬЮ через потоки.
• Проверки ограничения. Фраза "потоки, содержащиеся в области задачи", в описаниях методов, означает потоки, запущенные в области задачи или вложенных областях.

Следующий пример демонстрирует наследование связанного значения. Связанное значение USERNAME привязано к значению "duke". Создаётся StructuredTaskScope и вызывается его метод fork для запуска потока для выполнения childTask. Поток наследует связанные значения, захваченные при создании области задачи. Код в childTask использует значение связанного значения и, таким образом, читает значение "duke".

    private static final ScopedValue<String> USERNAME = ScopedValue.newInstance();

    ScopedValue.runWhere(USERNAME, "duke", () -> {
        try (var scope = new StructuredTaskScope<String>()) {

            scope.fork(() -> childTask());
            ...
         }
    });

    ...

    String childTask() {
        String name = USERNAME.get();   // "duke"
        ...
    }

StructuredTaskScope в данный момент не определяет API, которые экспонируют структуру дерева.

Если не указано иное, передача аргумента null в конструктор или метод в этом классе приведёт к выбрасыванию NullPointerException.

Влияние на согласованность памяти

Действия в собственном потоке области задачи или потоке, содержащемся в области задачи, до создания подзадачи с помощью fork предшествуют любым действиям, выполненным этой подзадачей, которые, в свою очередь, предшествуют получению результата подзадачи с помощью get^ПРЕВЬЮ или предшествуют любым действиям, выполненным в потоке после объединения области задачи с помощью join.