Класс ForkJoinTask<V>

java.lang.Object

java.util.concurrent.ForkJoinTask<V>

Type Parameters:: V - тип результата задачи

Все реализуемые интерфейсы:: Serializable, Future<V>

Прямые известные подклассы:: CountedCompleter, RecursiveAction, RecursiveTask

public abstract class ForkJoinTask<V> extends Object implements Future<V>, Serializable

Абстрактный базовый класс для задач, выполняемых в ForkJoinPool. ForkJoinTask — это потокоподобный объект, значительно более лёгкий, чем обычный поток. Большое количество задач и подзадач может обрабатываться небольшим количеством фактических потоков в ForkJoinPool, ценой некоторых ограничений в использовании.

Основная ForkJoinTask начинает выполнение, когда она явно отправляется в ForkJoinPool, или, если она ещё не участвует в вычислениях ForkJoin, запускается в ForkJoinPool.commonPool() через fork(), invoke() или родственные методы. После запуска она обычно запускает другие подзадачи. Как указано в названии этого класса, многие программы, использующие ForkJoinTask, используют только методы fork() и join(), или производные, такие как invokeAll. Однако этот класс также предоставляет ряд других методов, которые могут использоваться в расширенных применениях, а также механизмы расширения, которые позволяют поддерживать новые формы обработки fork/join.

ForkJoinTask — это лёгкая форма Future. Эффективность ForkJoinTask обусловлена набором ограничений (которые только частично статически проверяемы), отражающих их основное использование как вычислительных задач, вычисляющих чистые функции или работающих с чисто изолированными объектами. Основные механизмы координации — fork(), который организует асинхронное выполнение, и join(), который не продолжает выполнение до тех пор, пока результат задачи не будет вычислен. Вычисления должны по возможности избегать synchronized методы или блоки, и должны минимизировать другие блокирующие синхронизации, кроме объединения других задач или использования синхронизаторов, таких как Phasers, которые рекламируются для сотрудничества с планированием fork/join. Разделяемые задачи также не должны выполнять блокирующее ввод-вывод и должны по возможности обращаться к переменным, которые полностью независимы от тех, к которым обращаются другие выполняемые задачи. Эти рекомендации слабо контролируются, так как не допускается выбрасывание проверочных исключений, таких как IOExceptions. Однако вычисления всё ещё могут столкнуться с необработанными исключениями, которые перебрасываются вызывающим сторонам, пытающимся их объединить. Эти исключения могут также включать RejectedExecutionException, возникающие из-за исчерпания внутренних ресурсов, таких как невозможность выделения внутренних очередей задач. Переброшенные исключения ведут себя так же, как обычные исключения, но, по возможности, содержат трассировки стека (например, отображаемые с помощью ex.printStackTrace()) как потока, инициировавшего вычисление, так и потока, фактически столкнувшегося с исключением; по минимуму только последнего.

Возможна разработка и использование ForkJoinTasks, которые могут блокироваться, но это требует трёх дополнительных соображений: (1) Завершение небольшого количества или отсутствия других задач не должно зависеть от задачи, блокирующей внешнюю синхронизацию или ввод-вывод. Задачи типа async, которые никогда не объединяются (например, подклассы CountedCompleter) часто попадают в эту категорию. (2) Для минимизации воздействия на ресурсы задачи должны быть небольшими; в идеале выполняющие только (возможно) блокирующую операцию. (3) Если не используется API ForkJoinPool.ManagedBlocker или количество, возможно, заблокированных задач известно, что меньше уровня ForkJoinPool.getParallelism() пула, пул не может гарантировать, что будет достаточно потоков для обеспечения прогресса или хорошей производительности.

Основной метод ожидания завершения и извлечения результатов задачи — join(), но существуют и несколько вариантов: Методы Future.get() поддерживают прерываемые и/или временные ожидания завершения и сообщают результаты, используя Future соглашения. Метод invoke() семантически эквивалентен fork(); join(), но всегда пытается начать выполнение в текущем потоке. «Тихие» формы этих методов не извлекают результаты или не сообщают об исключениях. Они могут быть полезны, когда множество задач выполняется, и вам нужно отложить обработку результатов или исключений до тех пор, пока все не завершатся. Метод invokeAll (доступен в нескольких вариантах) выполняет наиболее распространённую форму параллельного вызова: создание набора задач и их объединение.

В самых типичных случаях пара fork-join действует как вызов (fork) и возврат (join) из параллельной рекурсивной функции. Как и в случае с другими формами рекурсивных вызовов, возвраты (joins) должны выполняться вложенным первым. Например, a.fork(); b.fork(); b.join(); a.join();, вероятно, будет значительно эффективнее, чем объединение a перед b.

Статус выполнения задач можно запросить на нескольких уровнях детализации: isDone() равно true, если задача завершилась каким-либо способом (включая случай, когда задача была отменена без выполнения); isCompletedNormally() равно true, если задача завершилась без отмены или возникновения исключения; isCancelled() равно true, если задача была отменена (в этом случае getException(boolean) возвращает CancellationException); и isCompletedAbnormally() равно true, если задача была либо отменена, либо столкнулась с исключением, в этом случае getException(boolean) вернёт либо возникшее исключение, либо CancellationException.

Класс ForkJoinTask обычно не наследуется напрямую. Вместо этого вы наследуетесь от одного из абстрактных классов, поддерживающих определённый стиль обработки fork/join, обычно RecursiveAction для большинства вычислений, не возвращающих результаты, RecursiveTask для тех, которые возвращают результаты, и CountedCompleter для тех, в которых завершённые действия запускают другие действия. Обычно конкретный подкласс ForkJoinTask объявляет поля, составляющие его параметры, установленные в конструкторе, а затем определяет метод compute, который каким-то образом использует методы управления, предоставляемые этим базовым классом.

Метод join() и его варианты подходят только для использования в том случае, если зависимости завершения ацикличны; то есть параллельное вычисление можно описать как ориентированный ациклический граф (DAG). В противном случае выполнение может столкнуться с формой тупика, так как задачи циклически ожидают друг друга. Однако этот фреймворк поддерживает другие методы и техники (например, использование Phaser, helpQuiesce() и complete(V)), которые могут быть полезны при создании пользовательских подклассов для проблем, которые не являются статически структурированными как DAG. Для поддержки таких применений ForkJoinTask может атомарно быть помечен значением short с помощью setForkJoinTaskTag(short) или compareAndSetForkJoinTaskTag(short, short) и проверяться с помощью getForkJoinTaskTag(). Реализация ForkJoinTask не использует эти protected методы или метки ни для какой цели, но они могут быть полезны при создании специализированных подклассов. Например, параллельные обходы графов могут использовать предоставленные методы, чтобы избежать повторного посещения узлов/задач, которые уже были обработаны. (Имена методов для маркировки в части громоздки, чтобы стимулировать определение методов, которые отражают их схемы использования).

Большинство базовых поддерживающих методов являются final, чтобы предотвратить переопределение реализаций, которые неразрывно связаны с основополагающей лёгкой системой планирования задач. Разработчики, создающие новые базовые стили обработки fork/join, должны по меньшей мере реализовать protected методы exec(), setRawResult(V) и getRawResult(), а также добавить абстрактный вычислительный метод, который может быть реализован в его подклассах, возможно, опираясь на другие protected методы, предоставляемые этим классом.

ForkJoinTasks должны выполнять относительно небольшие объёмы вычислений. Большие задачи должны быть разделены на более мелкие подзадачи, обычно через рекурсивную декомпозицию. В качестве очень приблизительного правила, задача должна выполнять более 100 и менее 10000 базовых вычислительных шагов и должна избегать бесконечных циклов. Если задачи слишком велики, то параллелизм не может улучшить производительность. Если слишком малы, то накладные расходы памяти и внутренней поддержки задач могут переполнить обработку.

Этот класс предоставляет adapt методы для Runnable и Callable, которые могут быть полезны при смешивании выполнения ForkJoinTasks с другими типами задач. Когда все задачи имеют эту форму, рассмотрите возможность использования пула, созданного в режиме asyncMode.

ForkJoinTasks являются Serializable, что позволяет использовать их в расширениях, таких как фреймворки удалённого выполнения. Очевидно, задачи сериализуются только до или после, но не во время выполнения. Сериализация не используется во время самого выполнения.

Since:

1.7

См. также:

Краткое описание вложенных классов

Вложенные классы/интерфейсы, объявленные в интерфейсе java.util.concurrent.Future

Future.State

Краткое описание конструкторов

Конструктор	Описание
`ForkJoinTask()`	Конструктор для вызова подклассами.

Краткое описание методов

Модификатор и тип	Метод	Описание
`static ForkJoinTask<?>`	`adapt(Runnable runnable)`	Возвращает новый `ForkJoinTask`, который выполняет метод `run` заданного `Runnable` в качестве своего действия, и возвращает null в результате при `join()`.
`static <T> ForkJoinTask<T>`	`adapt(Runnable runnable, T result)`	Возвращает новый `ForkJoinTask`, который выполняет метод `run` заданного `Runnable` в качестве своего действия, и возвращает заданный результат при `join()`.
`static <T> ForkJoinTask<T>`	`adapt(Callable<? extends T> callable)`	Возвращает новый `ForkJoinTask`, который выполняет метод `call` заданного `Callable` в качестве своего действия, и возвращает его результат при `join()`, переводя любые возникшие checked исключения в `RuntimeException`.
`static ForkJoinTask<?>`	`adaptInterruptible(Runnable runnable)`	Возвращает новый `ForkJoinTask`, который выполняет метод `run` заданного `Runnable` в качестве своего действия, и возвращает null в результате при `join()`, переводя любые возникшие checked исключения в `RuntimeException`.
`static <T> ForkJoinTask<T>`	`adaptInterruptible(Runnable runnable, T result)`	Возвращает новый `ForkJoinTask`, который выполняет метод `run` заданного `Runnable` в качестве своего действия, и возвращает заданный результат при `join()`, переводя любые возникшие checked исключения в `RuntimeException`.
`static <T> ForkJoinTask<T>`	`adaptInterruptible(Callable<? extends T> callable)`	Возвращает новый `ForkJoinTask`, который выполняет метод `call` заданного `Callable` в качестве своего действия, и возвращает его результат при `join()`, переводя любые возникшие checked исключения в `RuntimeException`.
`boolean`	`cancel(boolean mayInterruptIfRunning)`	Попытка отменить выполнение этой задачи.
`final boolean`	`compareAndSetForkJoinTaskTag(short expect, short update)`	Атомарно условно устанавливает значение тега для этой задачи.
`void`	`complete(V value)`	Завершает эту задачу, и если она ещё не прервана или отменена, возвращает заданное значение в качестве результата последующих вызовов `join` и связанных операций.
`void`	`completeExceptionally(Throwable ex)`	Завершает эту задачу аномально, и если она ещё не прервана или отменена, вызывает заданное исключение при `join` и связанных операциях.
`Throwable`	`exceptionNow()`	Возвращает исключение, брошенное задачей, без ожидания.
`protected abstract boolean`	`exec()`	Немедленно выполняет базовое действие этой задачи и возвращает true, если после возврата из этого метода эта задача гарантированно завершится.
`final ForkJoinTask<V>`	`fork()`	Организует асинхронное выполнение этой задачи в пуле, в котором выполняется текущая задача, если применимо, или используя `ForkJoinPool.commonPool()`, если нет `inForkJoinPool()`.
`final V`	`get()`	Ждёт, если необходимо, завершения вычисления, а затем извлекает его результат.
`final V`	`get(long timeout, TimeUnit unit)`	Ждёт, если необходимо, не более заданного времени завершения вычисления, а затем извлекает его результат, если он доступен.
`final Throwable`	`getException()`	Возвращает исключение, брошенное базовым вычислением, или `CancellationException`, если отменено, или `null`, если нет или если метод ещё не завершён.
`final short`	`getForkJoinTaskTag()`	Возвращает тег для этой задачи.
`static ForkJoinPool`	`getPool()`	Возвращает пул, содержащий текущую нить, или `null`, если текущая нить выполняется вне ForkJoinPool.
`static int`	`getQueuedTaskCount()`	Возвращает оценку количества задач, которые были разветвлены текущей рабочей нитью, но ещё не выполнены.
`abstract V`	`getRawResult()`	Возвращает результат, который был бы возвращён `join()`, даже если эта задача завершилась аномально, или `null`, если эта задача не известна как завершённая.
`static int`	`getSurplusQueuedTaskCount()`	Возвращает оценку того, на сколько больше локально очереди задач хранится в текущей рабочей нити, чем других рабочих нитей, которые могут их украсть, или ноль, если эта нить не работает в ForkJoinPool.
`static void`	`helpQuiesce()`	Возможная обработка задач до тех пор, пока пул, содержащий текущую задачу, не будет бездействовать.
`static boolean`	`inForkJoinPool()`	Возвращает `true`, если текущая нить является `ForkJoinWorkerThread` и выполняется как вычисление ForkJoinPool.
`final V`	`invoke()`	Начинает выполнение этой задачи, ждёт её завершения, если необходимо, и возвращает её результат или бросает (непроверенное) `RuntimeException` или `Error`, если это сделало базовое вычисление.
`static <T extends ForkJoinTask<?>> Collection<T>`	`invokeAll(Collection<T> tasks)`	Разветвляет все задачи в указанном наборе, возвращаясь, когда `isDone` выполняется для каждой задачи или возникает (непроверенное) исключение, в этом случае исключение перебрасывается.
`static void`	`invokeAll(ForkJoinTask<?>... tasks)`	Разветвляет заданные задачи, возвращаясь, когда `isDone` выполняется для каждой задачи или возникает (непроверенное) исключение, в этом случае исключение перебрасывается.
`static void`	`invokeAll(ForkJoinTask<?> t1, ForkJoinTask<?> t2)`	Разветвляет заданные задачи, возвращаясь, когда `isDone` выполняется для каждой задачи или возникает (непроверенное) исключение, в этом случае исключение перебрасывается.
`final boolean`	`isCancelled()`	Возвращает `true`, если эта задача была отменена до её нормального завершения.
`final boolean`	`isCompletedAbnormally()`	Возвращает `true`, если эта задача бросила исключение или была отменена.
`final boolean`	`isCompletedNormally()`	Возвращает `true`, если эта задача завершилась без бросания исключения и не была отменена.
`final boolean`	`isDone()`	Возвращает `true`, если эта задача завершена.
`final V`	`join()`	Возвращает результат вычисления, когда оно завершено.
`protected static ForkJoinTask<?>`	`peekNextLocalTask()`	Возвращает, но не отменяет и не выполняет, задачу, поставленную в очередь текущей нитью, но ещё не выполненную, если она немедленно доступна.
`protected static ForkJoinTask<?>`	`pollNextLocalTask()`	Отменяет и возвращает, без выполнения, следующую задачу, поставленную в очередь текущей нитью, но ещё не выполненную, если текущая нить работает в ForkJoinPool.
`protected static ForkJoinTask<?>`	`pollSubmission()`	Если текущая нить работает в ForkJoinPool, отменяет и возвращает, без выполнения, задачу, внешне переданную в пул, если она доступна.
`protected static ForkJoinTask<?>`	`pollTask()`	Если текущая нить работает в ForkJoinPool, отменяет и возвращает, без выполнения, следующую задачу, поставленную в очередь текущей нитью, но ещё не выполненную, если она доступна, или если нет, задачу, разветвленную другой нитью, если она доступна.
`final void`	`quietlyComplete()`	Завершает эту задачу нормально без установки значения.
`final void`	`quietlyInvoke()`	Начинает выполнение этой задачи и ждёт её завершения, если необходимо, без возврата её результата или бросания её исключения.
`final void`	`quietlyJoin()`	Присоединяется к этой задаче без возврата её результата или бросания её исключения.
`final boolean`	`quietlyJoin(long timeout, TimeUnit unit)`	Пытается присоединиться к этой задаче, возвращая true, если она завершилась (возможно, с исключением) до истечения заданного таймаута и текущая нить не была прервана.
`final boolean`	`quietlyJoinUninterruptibly(long timeout, TimeUnit unit)`	Пытается присоединиться к этой задаче, возвращая true, если она завершилась (возможно, с исключением) до истечения заданного таймаута.
`void`	`reinitialize()`	Сбрасывает внутреннее состояние учёта этой задачи, позволяя последующее `fork`.

END_OF_DOCUMENT_MARKER

`V`	`resultNow()`	Возвращает вычисленный результат, без ожидания.
`final short`	`setForkJoinTaskTag(short newValue)`	Атомарно устанавливает значение тега для этой задачи и возвращает старое значение.
`protected abstract void`	`setRawResult(V value)`	Вынуждает возвращение заданного значения в качестве результата.
`Future.State`	`state()`	Возвращает состояние вычисления.
`boolean`	`tryUnfork()`	Пытается отменить планирование этой задачи для выполнения.

Методы, объявленные в классе java.lang.Object

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

Подробное описание конструкторов

ForkJoinTask

public ForkJoinTask()

Конструктор для вызова подклассами.

Подробное описание методов

fork

public final ForkJoinTask<V> fork()

Организует асинхронное выполнение этой задачи в пуле, в котором выполняется текущая задача, если применимо, или с использованием ForkJoinPool.commonPool(), если нет inForkJoinPool(). Хотя это не обязательно, ошибка заключается в том, чтобы форкать задачу более одного раза, если она не завершена и не перезапущена. Последующие изменения состояния этой задачи или любых данных, с которыми она работает, не обязательно согласованно наблюдаются ни одним потоком, кроме того, который её выполняет, если не предшествуют вызову join() или связанным методам, или вызову isDone(), возвращающему


 true

Возвращает:: this, для упрощения использования

join

public final V join()

Возвращает результат вычисления, когда он завершен. Этот метод отличается от get() тем, что результаты аномального завершения приводят к RuntimeException или Error, а не к ExecutionException, и что прерывания вызывающего потока не приводят к внезапному возврату с выбрасыванием InterruptedException.

Возвращает:: вычисленный результат

invoke

public final V invoke()

Начинает выполнение этой задачи, ожидает её завершения при необходимости и возвращает её результат или выбрасывает (непроверенное) RuntimeException или Error, если это сделал вызов в вычислениях.

Возвращает:: вычисленный результат

invokeAll

public static void invokeAll(ForkJoinTask<?> t1, ForkJoinTask<?> t2)

Запускает заданные задачи, возвращаясь, когда isDone выполняется для каждой задачи или возникает (непроверенное) исключение, в этом случае исключение повторно выбрасывается. Если более чем одна задача сталкивается с исключением, этот метод выбрасывает любое из этих исключений. Если какая-либо задача сталкивается с исключением, другая может быть отменена. Однако состояние выполнения отдельных задач не гарантируется при возврате с исключением. Статус каждой задачи можно получить, используя getException() и связанные методы для проверки, были ли они отменены, завершены нормально или с исключением, или остались необработанными.

Параметры:: t1 - первая задача; t2 - вторая задача
Исключения:: NullPointerException - если какая-либо задача равна null

invokeAll

public static void invokeAll(ForkJoinTask<?>... tasks)

Запускает заданные задачи, возвращаясь, когда isDone выполняется для каждой задачи или возникает (непроверенное) исключение, в этом случае исключение повторно выбрасывается. Если более чем одна задача сталкивается с исключением, этот метод выбрасывает любое из этих исключений. Если какая-либо задача сталкивается с исключением, другие могут быть отменены. Однако состояние выполнения отдельных задач не гарантируется при возврате с исключением. Статус каждой задачи можно получить, используя getException() и связанные методы для проверки, были ли они отменены, завершены нормально или с исключением, или остались необработанными.

Параметры:: tasks - задачи
Исключения:: NullPointerException - если какая-либо задача равна null

invokeAll

public static <T extends ForkJoinTask<?>> Collection<T> invokeAll(Collection<T> tasks)

Запускает все задачи в указанном наборе, возвращаясь, когда isDone выполняется для каждой задачи или возникает (непроверенное) исключение, в этом случае исключение повторно выбрасывается. Если более чем одна задача сталкивается с исключением, этот метод выбрасывает любое из этих исключений. Если какая-либо задача сталкивается с исключением, другие могут быть отменены. Однако состояние выполнения отдельных задач не гарантируется при возврате с исключением. Статус каждой задачи можно получить, используя getException() и связанные методы для проверки, были ли они отменены, завершены нормально или с исключением, или остались необработанными.

Тип параметров:: T - тип значений, возвращаемых задачами
Параметры:: tasks - набор задач
Возвращает:: аргумент tasks, для упрощения использования
Исключения:: NullPointerException - если tasks или любой элемент равны null

cancel

public boolean cancel(boolean mayInterruptIfRunning)

Попытка отменить выполнение этой задачи. Эта попытка завершится неудачей, если задача уже завершена или не может быть отменена по какой-либо другой причине. При успехе, если эта задача не стартовала, когда cancel вызвана, выполнение этой задачи подавляется. После успешного возврата этого метода, если не будет промежуточного вызова reinitialize(), последующие вызовы isCancelled(), isDone() и cancel вернут true, и вызовы join() и связанных методов приведут к CancellationException.

Этот метод может быть переопределён в подклассах, но в таком случае должен гарантировать сохранение этих свойств. В частности, сам метод cancel не должен выбрасывать исключений.

Этот метод предназначен для вызова другими задачами. Для завершения текущей задачи можно просто вернуть или бросить непроверенное исключение из её метода вычислений или вызвать completeExceptionally(Throwable).

Указано в:: cancel в интерфейсе Future<V>
Параметры:: mayInterruptIfRunning - это значение не влияет на реализацию по умолчанию, потому что прерывания не используются для управления отменой.
Возвращает:: true, если эта задача теперь отменена

isDone

public final boolean isDone()

Описание скопировано из интерфейса: Future

Возвращает true, если эта задача завершена. Завершение может быть вызвано нормальным завершением, исключением или отменой — во всех этих случаях этот метод вернёт true.

Указано в:: isDone в интерфейсе Future<V>
Возвращает:: true, если эта задача завершена

isCancelled

public final boolean isCancelled()

Описание скопировано из интерфейса: Future

Возвращает true, если эта задача была отменена до нормального завершения.

Указано в:: isCancelled в интерфейсе Future<V>
Возвращает:: true, если эта задача была отменена до завершения

isCompletedAbnormally

public final boolean isCompletedAbnormally()

Возвращает true, если эта задача выбросила исключение или была отменена.

Возвращает:: true, если эта задача выбросила исключение или была отменена

isCompletedNormally

public final boolean isCompletedNormally()

Возвращает true, если эта задача завершилась без выброса исключения и не была отменена.

Возвращает:: true, если эта задача завершилась без выброса исключения и не была отменена

state

public Future.State state()

Описание скопировано из интерфейса: Future

Возвращает состояние вычисления.

Указано в:: state в интерфейсе Future<V>
Возвращает:: состояние вычисления
C момента:: 19

resultNow

public V resultNow()

Описание скопировано из интерфейса: Future

Возвращает вычисленный результат без ожидания.

Этот метод предназначен для случаев, когда вызывающий код знает, что задача уже успешно завершилась, например, при фильтрации потока объектов Future по успешным задачам и использовании операции отображения для получения потока результатов.

    results = futures.stream()
               .filter(f -> f.state() == Future.State.SUCCESS)
               .map(Future::resultNow)
               .toList();

Указано в:: resultNow в интерфейсе Future<V>
Возвращает:: вычисленный результат
C момента:: 19

exceptionNow

public Throwable exceptionNow()

Описание скопировано из интерфейса: Future

Возвращает исключение, сгенерированное задачей, без ожидания.

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

Указано в:: exceptionNow в интерфейсе Future<V>
Возвращает:: исключение, сгенерированное задачей
C момента:: 19

getИсключение

public final Throwable getException()

Возвращает исключение, сгенерированное основным вычислением, или CancellationException, если вычисление было отменено, или null, если исключение отсутствует или метод ещё не завершён.

Возвращает:: исключение, или null, если исключение отсутствует

completeИсключительно

public void completeExceptionally(Throwable ex)

Ненормально завершает эту задачу, и если она ещё не прервана или отменена, заставляет её сгенерировать заданное исключение при join и смежных операциях. Этот метод может использоваться для создания исключений в асинхронных задачах или для принудительного завершения задач, которые не завершаются иначе. Использование в других ситуациях не рекомендуется. Этот метод переопределяемый, но переопределённые версии должны вызывать super реализацию, чтобы сохранить гарантии.

Параметры:: ex - исключение, которое нужно сгенерировать. Если это исключение не является RuntimeException или Error, фактически сгенерированное исключение будет RuntimeException с причиной ex.

завершить

public void complete(V value)

Завершает эту задачу, и если она ещё не прервана или отменена, возвращает заданное значение в качестве результата последующих вызовов join и связанных операций. Этот метод может использоваться для предоставления результатов асинхронных задач или для альтернативной обработки задач, которые иначе не завершатся нормально. Использование в других ситуациях не рекомендуется. Этот метод переопределяемый, но переопределённые версии должны вызывать super реализацию, чтобы сохранить гарантии.

Параметры:: value - значение результата для этой задачи

quietlyЗавершить

public final void quietlyComplete()

Завершает эту задачу нормально без установки значения. Наиболее недавнее значение, установленное с помощью setRawResult(V) (или


 null

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

Since:: 1.8

получить

public final V get() throws InterruptedException, ExecutionException

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

Определено в:: get в интерфейсе Future<V>
Возвращает:: вычисленный результат
Исключения:: CancellationException - если вычисление было отменено; ExecutionException - если вычисление сгенерировало исключение; InterruptedException - если текущий поток не является членом ForkJoinPool и был прерван во время ожидания

получить

public final V get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException

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

Определено в:: get в интерфейсе Future<V>
Параметры:: timeout - максимальное время ожидания; unit - единица измерения времени параметра timeout
Возвращает:: вычисленный результат
Исключения:: CancellationException - если вычисление было отменено; ExecutionException - если вычисление сгенерировало исключение; InterruptedException - если текущий поток не является членом ForkJoinPool и был прерван во время ожидания; TimeoutException - если ожидание истекло

quietlyПрисоединиться

public final void quietlyJoin()

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

quietlyВызвать

public final void quietlyInvoke()

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

quietlyПрисоединиться

public final boolean quietlyJoin(long timeout, TimeUnit unit) throws InterruptedException

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

Параметры:: timeout - максимальное время ожидания; unit - единица измерения времени параметра timeout
Возвращает:: true, если задача завершилась
Исключения:: InterruptedException - если текущий поток был прерван во время ожидания
Since:: 19

quietlyПрисоединитьсяНепрерывно

public final boolean quietlyJoinUninterruptibly(long timeout, TimeUnit unit)

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

Параметры:: timeout - максимальное время ожидания; unit - единица измерения времени параметра timeout
Возвращает:: true, если задача завершилась
Since:: 19

помочьЗатихнуть

public static void helpQuiesce()

Возможно выполняет задачи до тех пор, пока пул, содержащий текущую задачу не станет quiescent. Этот метод может быть полезен в конструкциях, в которых много задач форкуется, но ни одна явно не присоединяется, а вместо этого они выполняются до обработки всех.

переинициализировать

public void reinitialize()

Сбрасывает внутреннее состояние учёта этой задачи, позволяя последующее fork. Этот метод позволяет повторно использовать эту задачу, но только если повторное использование происходит, когда эта задача либо никогда не форковалась, либо была форкована, затем завершена, и все ожидающие присоединения к этой задаче также завершены. Эффекты при любых других условиях использования не гарантируются. Этот метод может быть полезен при выполнении предопределённых деревьев подзадач в циклах.

После выполнения этого метода, isDone() сообщает false, и getException() сообщает null. Однако, значение, возвращённое getRawResult, не изменяется. Чтобы очистить это значение, можно вызвать setRawResult(null).

получитьПул

public static ForkJoinPool getPool()

Возвращает пул, в котором выполняется текущий поток, или null, если текущий поток выполняется вне любого ForkJoinPool.

Этот метод возвращает null тогда и только тогда, когда inForkJoinPool() возвращает false.

Возвращает:: пул, или null, если пул отсутствует

вForkJoinПуле

public static boolean inForkJoinPool()

Возвращает true, если текущий поток является ForkJoinWorkerThread, выполняющим вычисление в ForkJoinPool.

Возвращает:: true, если текущий поток является ForkJoinWorkerThread, выполняющим вычисление в ForkJoinPool, или false в противном случае

попытатьсяОтфоркнуть

public boolean tryUnfork()

Пытается отменить планирование этой задачи для выполнения. Этот метод, как правило (но не гарантировано), будет успешным, если эта задача является последней форкнутой задачей текущим потоком и ещё не начала выполняться в другом потоке. Этот метод может быть полезен при организации альтернативной локальной обработки задач, которые могли быть, но не были, украдены.

Возвращает:: true, если отфорковано

количествоОчередныхЗадач

public static int getQueuedTaskCount()

Возвращает оценку количества задач, форкнутых текущим рабочим потоком, но ещё не выполненных. Это значение может быть полезно для эвристических решений о том, следует ли форкнуть другие задачи.

Возвращает:: количество задач

количествоИзлишнихОчередныхЗадач

public static int getSurplusQueuedTaskCount()

Возвращает оценку того, на сколько больше локально очереди задач удерживаются текущим рабочим потоком, чем других рабочих потоков, которые могли бы их украсть, или ноль, если этот поток не работает в ForkJoinPool. Это значение может быть полезно для эвристических решений о том, следует ли форкнуть другие задачи. Во многих случаях использования ForkJoinTasks, в стационарном состоянии, каждый рабочий должен стремиться поддерживать небольшой постоянный излишек (например, 3) задач и обрабатывать вычисления локально, если этот порог превышен.

Возвращает:: излишнее количество задач, которое может быть отрицательным

сыройРезультат

public abstract V getRawResult()

Возвращает результат, который бы вернул join(), даже если эта задача завершилась аномально, или null, если об окончании этой задачи ничего неизвестно. Этот метод предназначен для отладки, а также для поддержки расширений. Его использование в любом другом контексте не рекомендуется.

Возвращает:: результат, или null, если задача не завершена

setRawResult

protected abstract void setRawResult(V value)

Принудительно устанавливает заданное значение в качестве результата. Данный метод предназначен для поддержки расширений и обычно вызывать не следует.

Parameters:: value - значение

exec

protected abstract boolean exec()

Немедленно выполняет основное действие данной задачи и возвращает true, если после завершения этого метода задача гарантированно завершена. В противном случае метод может вернуть false, чтобы указать, что задача не обязательно завершена (или не известно, завершена ли она), например, в асинхронных действиях, требующих явных вызовов методов завершения. Метод также может бросить (непроверенное) исключение для обозначения аномального выхода. Этот метод предназначен для поддержки расширений и обычно вызывать не следует.

Returns:: true, если известно, что задача завершилась успешно

peekNextLocalTask

protected static ForkJoinTask<?> peekNextLocalTask()

Возвращает, но не отменяет и не выполняет, задачу, помещенную в очередь текущей нитью, но еще не выполненную, если она сразу доступна. Нет гарантии, что эта задача будет взята в обработку или выполнена в следующей очереди. Напротив, этот метод может вернуть null, даже если задача существует, но не может быть обработана без конфликта с другими нитями. Этот метод в первую очередь предназначен для поддержки расширений и вряд ли будет полезен в других случаях.

Returns:: следующую задачу или null, если доступные задачи отсутствуют

pollNextLocalTask

protected static ForkJoinTask<?> pollNextLocalTask()

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

Returns:: следующую задачу или null, если доступные задачи отсутствуют

pollTask

protected static ForkJoinTask<?> pollTask()

Если текущая нить работает в ForkJoinPool, отменяет и возвращает, не выполняя, следующую задачу, помещенную в очередь текущей нитью, но еще не выполненную, если она доступна, или, если она недоступна, задачу, созданную другой нитью, если она доступна. Доступность может быть временной, поэтому результат null не обязательно означает бездействия пула задач, в котором работает эта задача. Этот метод в первую очередь предназначен для поддержки расширений и вряд ли будет полезен в других случаях.

Returns:: задачу или null, если доступные задачи отсутствуют

pollSubmission

protected static ForkJoinTask<?> pollSubmission()

Если текущая нить работает в ForkJoinPool, отменяет и возвращает, не выполняя, задачу, внешне переданную в пул, если она доступна. Доступность может быть временной, поэтому результат null не обязательно означает бездействия пула. Этот метод в первую очередь предназначен для поддержки расширений и вряд ли будет полезен в других случаях.

Returns:: задачу или null, если доступные задачи отсутствуют
Since:: 9

getForkJoinTaskTag

public final short getForkJoinTaskTag()

Возвращает метку для данной задачи.

Returns:: метку для этой задачи
Since:: 1.8

setForkJoinTaskTag

public final short setForkJoinTaskTag(short newValue)

Атомарно устанавливает значение метки для этой задачи и возвращает старое значение.

Parameters:: newValue - новое значение метки
Returns:: предыдущее значение метки
Since:: 1.8

compareAndSetForkJoinTaskTag

public final boolean compareAndSetForkJoinTaskTag(short expect, short update)

Атомарно условно устанавливает значение метки для этой задачи. Среди прочих применений, метки могут использоваться в качестве маркеров посещения в задачах, работающих с графами, как в методах, которые проверяют:


 if (task.compareAndSetForkJoinTaskTag((short)0, (short)1))

перед обработкой, иначе выходят, потому что узел уже посещён.

Parameters:: expect - ожидаемое значение метки; update - новое значение метки
Returns:: true, если успешно; т.е., текущее значение было равно expect и было изменено на update.
Since:: 1.8

adapt

public static ForkJoinTask<?> adapt(Runnable runnable)

Возвращает новую ForkJoinTask, которая выполняет метод run заданного Runnable в качестве своего действия и возвращает null-результат при join().

Parameters:: runnable - действие Runnable
Returns:: задачу

adapt

public static <T> ForkJoinTask<T> adapt(Runnable runnable, T result)

Возвращает новую ForkJoinTask, которая выполняет метод run заданного Runnable в качестве своего действия и возвращает заданный результат при join().

Type Parameters:: T - тип результата
Parameters:: runnable - действие Runnable; result - результат по завершении
Returns:: задачу

adapt

public static <T> ForkJoinTask<T> adapt(Callable<? extends T> callable)

Возвращает новую ForkJoinTask, которая выполняет метод call заданного Callable в качестве своего действия и возвращает его результат при join(), переводя любые проверенные исключения в RuntimeException.

Type Parameters:: T - тип результата вызова
Parameters:: callable - действие Callable
Returns:: задачу

adaptInterruptible

public static <T> ForkJoinTask<T> adaptInterruptible(Callable<? extends T> callable)

mayInterruptIfRunning
 true

попытаются прервать нить, выполняющую задачу.

Type Parameters:: T - тип результата вызова
Parameters:: callable - действие Callable
Returns:: задачу
Since:: 19

adaptInterruptible

public static <T> ForkJoinTask<T> adaptInterruptible(Runnable runnable, T result)

Возвращает новую ForkJoinTask, которая выполняет метод run заданного Runnable в качестве своего действия и возвращает заданный результат при join(), переводя любые проверенные исключения в RuntimeException. Дополнительно, вызовы cancel с

mayInterruptIfRunning
 true

попытаются прервать нить, выполняющую задачу.

Type Parameters:: T - тип результата
Parameters:: runnable - действие Runnable; result - результат по завершении
Returns:: задачу
Since:: 22

adaptInterruptible

public static ForkJoinTask<?> adaptInterruptible(Runnable runnable)

Возвращает новую ForkJoinTask, которая выполняет метод

run

заданного Runnable в качестве своего действия и возвращает null при join(), переводя любые проверенные исключения в RuntimeException. Дополнительно, вызовы cancel с


 mayInterruptIfRunning true

попытаются прервать нить, выполняющую задачу.

Parameters:: runnable - действие Runnable
Returns:: задачу
Since:: 22

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/concurrent/ForkJoinTask.html