Класс 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^PREVIEW для разделения подзадач на набор подзадач, завершившихся успешно, и набор подзадач, завершившихся неудачно.

    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^PREVIEW захватывает результат первой подзадачи, завершившейся успешно. После захвата он останавливает область задачи, прерывает незавершенные потоки и будит владельца. Этот класс предназначен для случаев, когда результат любой подзадачи подходит ("вызвать любую") и нет необходимости ожидать результатов других незавершенных подзадач. Он определяет методы для получения первого результата или выброса исключения, если все подзадачи завершатся неудачно.
2. ShutdownOnFailure^PREVIEW захватывает исключение первой подзадачи, завершившейся неудачно. После захвата он останавливает область задачи, прерывает незавершенные потоки и будит владельца. Этот класс предназначен для случаев, когда результаты всех подзадач необходимы ("вызвать все"); если какая-либо подзадача завершится неудачно, результаты других незавершенных подзадач больше не нужны. Он определяет методы для выброса исключения, если какая-либо из подзадач завершится неудачно.

Ниже приведены два примера использования этих двух классов. В обоих случаях создается пара подзадач для получения ресурсов из двух URL-локаций "left" и "right". Первый пример создает объект ShutdownOnSuccess для захвата результата первой подзадачи, завершившейся успешно, прерывая другую с помощью остановки области задачи. Главная задача ожидает в join, пока либо подзадача завершится с результатом, либо обе подзадачи завершатся неудачно. Он вызывает метод result(Function)^PREVIEW для получения полученного результата. Если обе подзадачи завершатся неудачно, этот метод выбросит 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".

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

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

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

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

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

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

    ...

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

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

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

Последствия для согласованности памяти

Действия в потоке владельца или в потоке, содержащемся в области задачи, до создания вилки подзадачи fork предшествуют любым действиям, выполняемым этой подзадачей, которые, в свою очередь, предшествуют получению результата подзадачи retrieved^PREVIEW или предшествуют любым действиям в потоке после присоединения join области задачи.