Spec-Zone.ru › OpenJDK 27

Класс ForkJoinTask<V>

java.lang.Object
java.util.concurrent.ForkJoinTask<V>
Параметры типа:
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. Эффективность ForkJoinTasks обусловлена набором ограничений (лишь частично поддающихся статической проверке), отражающих их основное назначение: вычислительные задачи, вычисляющие чистые функции или работающие с полностью изолированными объектами. Основные механизмы координации — это fork(), обеспечивающий асинхронное выполнение, и join(), который не продолжает работу до вычисления результата задачи. В идеале вычисления должны избегать методов или блоков synchronized и сводить к минимуму другие блокирующие средства синхронизации, помимо присоединения к другим задачам или использования синхронизаторов, например Phaser, для которых заявлена поддержка планирования fork/join. Разделяемые на подзадачи задачи также не должны выполнять блокирующий ввод-вывод и в идеале должны обращаться к переменным, полностью независимым от тех, к которым обращаются другие выполняющиеся задачи. Эти рекомендации в некоторой степени обеспечиваются запретом на выбрасывание проверяемых исключений, таких как IOExceptions. Однако при вычислениях все же могут возникать непроверяемые исключения, которые повторно выбрасываются вызывающим кодом при попытке присоединиться к ним. К таким исключениям также может относиться RejectedExecutionException, возникающее из-за исчерпания внутренних ресурсов, например при невозможности выделить внутренние очереди задач. Повторно выбрасываемые исключения ведут себя так же, как обычные исключения, но, если возможно, содержат трассировки стека (например, отображаемые с помощью ex.printStackTrace()) как потока, инициировавшего вычисление, так и потока, фактически обнаружившего исключение; как минимум — трассировку последнего.

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

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

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

Состояние выполнения задач можно запрашивать с разной степенью подробности: isDone() возвращает true, если задача завершилась любым способом (включая отмену задачи без выполнения); isCompletedNormally() возвращает true, если задача завершилась без отмены и без исключения; isCancelled() возвращает true, если задача была отменена (в этом случае getException() возвращает CancellationException); а isCompletedAbnormally() возвращает true, если задача была отменена или в ней возникло исключение; в этом случае getException() вернет либо возникшее исключение, либо 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, предоставляемые этим классом.

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

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

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

С момента появления:
1.7
См. также:
  • Сериализованное представление

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

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

Future.State
Модификатор и тип Интерфейс Описание
static enum  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(), преобразуя все возникшие проверяемые исключения в RuntimeException.
static ForkJoinTask<?> adaptInterruptible(Runnable runnable)
Возвращает новый ForkJoinTask, который выполняет метод run заданного Runnable в качестве действия и возвращает null при join(), преобразуя все возникшие проверяемые исключения в RuntimeException.
static <T> ForkJoinTask<T> adaptInterruptible(Runnable runnable, T result)
Возвращает новый ForkJoinTask, который выполняет метод run заданного Runnable в качестве действия и возвращает заданный результат при join(), преобразуя все возникшие проверяемые исключения в RuntimeException.
static <T> ForkJoinTask<T> adaptInterruptible(Callable<? extends T> callable)
Возвращает новый ForkJoinTask, который выполняет метод call заданного Callable в качестве действия и возвращает его результат при join(), преобразуя все возникшие проверяемые исключения в 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.
V resultNow()
Возвращает вычисленный результат, не ожидая завершения.
final short setForkJoinTaskTag(short newValue)
Атомарно устанавливает значение метки этой задачи и возвращает ее предыдущее значение.
protected abstract void setRawResult(V value)
Принудительно задает возвращаемое значение.
Future.State state()
Возвращает состояние вычисления.
boolean tryUnfork()
Пытается снять эту задачу с очереди на выполнение.

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

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Модификатор и тип Метод Описание
protected Object clone()
Создает и возвращает копию этого объекта.
boolean equals(Object obj)
Указывает, является ли другой объект «равным» этому объекту.
protected void finalize()
Устарело, будет удалено: этот элемент API подлежит удалению в будущей версии.
Финализация объявлена устаревшей и подлежит удалению в одном из будущих выпусков.
final Class<?> getClass()
Возвращает класс времени выполнения этого Object.
int hashCode()
Возвращает хеш-код этого объекта.
final void notify()
Пробуждает один поток, ожидающий на мониторе этого объекта.
final void notifyAll()
Пробуждает все потоки, ожидающие на мониторе этого объекта.
String toString()
Возвращает строковое представление объекта.
final void wait()
Переводит текущий поток в ожидание до пробуждения, обычно вследствие уведомления или прерывания.
final void wait(long timeoutMillis)
Переводит текущий поток в ожидание до пробуждения, обычно вследствие уведомления или прерывания, либо до истечения заданного времени.
final void wait(long timeoutMillis, int nanos)
Переводит текущий поток в ожидание до пробуждения, обычно вследствие уведомления или прерывания, либо до истечения заданного времени.

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

ForkJoinTask

public ForkJoinTask()
Конструктор, предназначенный для вызова подклассами.

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

fork

public final ForkJoinTask<V> fork()
Планирует асинхронное выполнение этой задачи в пуле, в котором выполняется текущая задача, если это применимо, или использует ForkJoinPool.commonPool(), если текущий поток не inForkJoinPool(). Хотя это не обязательно обеспечивается, повторное помещение задачи в очередь с помощью fork считается ошибкой, если задача не завершена и не инициализирована повторно. Последующие изменения состояния этой задачи или любых данных, с которыми она работает, не обязательно будут согласованно видны другим потокам, кроме выполняющего её, если перед ними не был вызван 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>
Возвращает:
состояние вычисления
С версии:
19

resultNow

public V resultNow()
Описание скопировано из интерфейса: Future
Возвращает вычисленный результат, не ожидая завершения.

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

    results = futures.stream()
               .filter(f -> f.state() == Future.State.SUCCESS)
               .map(Future::resultNow)
               .toList();
Определено в:
resultNow в интерфейсе Future<V>
Возвращает:
вычисленный результат
С версии:
19

exceptionNow

public Throwable exceptionNow()
Описание скопировано из интерфейса: Future
Возвращает исключение, выброшенное задачей, не ожидая завершения.

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

Определено в:
exceptionNow в интерфейсе Future<V>
Возвращает:
исключение, выброшенное задачей
С версии:
19

getException

public final Throwable getException()
Возвращает исключение, выброшенное базовым вычислением, или CancellationException, если задача отменена, или null, если исключения нет либо метод ещё не завершился.
Возвращает:
исключение или null, если исключения нет

completeExceptionally

public void completeExceptionally(Throwable ex)
Завершает эту задачу аварийно и, если она ещё не была прервана или отменена, заставляет её выбрасывать указанное исключение при вызове join и связанных операций. Этот метод можно использовать, чтобы вызвать исключения в асинхронных задачах или принудительно завершить задачи, которые иначе не завершились бы. Не рекомендуется использовать его в других ситуациях. Этот метод можно переопределить, но для сохранения гарантий переопределённые версии должны вызывать реализацию super.
Параметры:
ex - исключение для выбрасывания. Если это исключение не является RuntimeException или Error, фактически выброшенным исключением будет RuntimeException с причиной ex.

complete

public void complete(V value)
Завершает эту задачу и, если она ещё не была прервана или отменена, возвращает указанное значение в качестве результата при последующих вызовах join и связанных операций. Этот метод можно использовать, чтобы предоставить результаты асинхронным задачам или обеспечить альтернативную обработку задач, которые иначе не завершились бы нормально. Не рекомендуется использовать его в других ситуациях. Этот метод можно переопределить, но для сохранения гарантий переопределённые версии должны вызывать реализацию super.
Параметры:
value - значение результата этой задачи

quietlyComplete

public final void quietlyComplete()
Нормально завершает эту задачу, не устанавливая значение. Последнее значение, заданное с помощью setRawResult(V) (или null по умолчанию), будет возвращаться в качестве результата при последующих вызовах join и связанных операций.
С версии:
1.8

get

public final V get() throws InterruptedException, ExecutionException
При необходимости ожидает завершения вычисления, а затем получает его результат.
Определено в:
get в интерфейсе Future<V>
Возвращает:
вычисленный результат
Выбрасывает:
CancellationException - если вычисление было отменено
ExecutionException - если вычисление выбросило исключение
InterruptedException - если текущий поток не является членом ForkJoinPool и был прерван во время ожидания

get

public final V get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
При необходимости ожидает завершения вычисления не дольше указанного времени, а затем получает его результат, если он доступен.
Определено в:
get в интерфейсе Future<V>
Параметры:
timeout - максимальное время ожидания
unit - единица измерения времени аргумента тайм-аута
Возвращает:
вычисленный результат
Выбрасывает:
CancellationException - если вычисление было отменено
ExecutionException - если вычисление выбросило исключение
InterruptedException - если текущий поток не является членом ForkJoinPool и был прерван во время ожидания
TimeoutException - если время ожидания истекло

quietlyJoin

public final void quietlyJoin()
Ожидает завершения этой задачи, не возвращая её результат и не выбрасывая её исключение. Этот метод может быть полезен при обработке коллекций задач, некоторые из которых были отменены или заведомо прерваны по другой причине.

quietlyInvoke

public final void quietlyInvoke()
Запускает выполнение этой задачи и при необходимости ожидает её завершения, не возвращая её результат и не выбрасывая её исключение.

quietlyJoin

public final boolean quietlyJoin(long timeout, TimeUnit unit) throws InterruptedException
Пытается дождаться завершения этой задачи и возвращает true, если она завершилась (возможно, с исключением) до истечения указанного тайм-аута и текущий поток не был прерван.
Параметры:
timeout - максимальное время ожидания
unit - единица измерения времени аргумента тайм-аута
Возвращает:
true, если выполнение этой задачи завершено
Выбрасывает:
InterruptedException - если текущий поток был прерван во время ожидания
С версии:
19

quietlyJoinUninterruptibly

public final boolean quietlyJoinUninterruptibly(long timeout, TimeUnit unit)
Пытается дождаться завершения этой задачи и возвращает true, если она завершилась (возможно, с исключением) до истечения указанного тайм-аута.
Параметры:
timeout - максимальное время ожидания
unit - единица измерения времени аргумента тайм-аута
Возвращает:
true, если выполнение этой задачи завершено
С версии:
19

helpQuiesce

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

reinitialize

public void reinitialize()
Сбрасывает внутреннее состояние учёта этой задачи, позволяя впоследствии снова вызвать fork. Этот метод позволяет повторно использовать задачу, но только если повторное использование происходит в случае, когда задача ещё ни разу не помещалась в очередь с помощью fork либо была помещена в очередь, завершилась и все ожидающие вызовы join для этой задачи также завершились. Гарантии при любых других условиях использования не предоставляются. Этот метод может быть полезен при многократном выполнении заранее созданных деревьев подзадач.

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

getPool

public static ForkJoinPool getPool()
Возвращает пул, в котором выполняется текущий поток, или null, если текущий поток выполняется вне какого-либо ForkJoinPool.

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

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

inForkJoinPool

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

tryUnfork

public boolean tryUnfork()
Пытается удалить эту задачу из очереди выполнения. Обычно (но не гарантированно) попытка завершается успешно, если эта задача является последней задачей, помещённой в очередь текущим потоком с помощью fork, и её выполнение ещё не началось в другом потоке. Этот метод может быть полезен при организации альтернативной локальной обработки задач, которые могли быть украдены, но не были.
Возвращает:
true, если задачу удалось удалить из очереди

getQueuedTaskCount

public static int getQueuedTaskCount()
Возвращает оценку количества задач, помещённых текущим рабочим потоком в очередь с помощью fork, но ещё не выполненных. Это значение может быть полезно для эвристического определения того, следует ли помещать в очередь другие задачи.
Возвращает:
количество задач

getSurplusQueuedTaskCount

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

getRawResult

public abstract V getRawResult()
Возвращает результат, который вернул бы join(), даже если эта задача завершилась аварийно, или null, если известно, что задача ещё не завершена. Этот метод предназначен для упрощения отладки и поддержки расширений. Не рекомендуется использовать его в каких-либо других целях.
Возвращает:
результат или null, если задача не завершена

setRawResult

protected abstract void setRawResult(V value)
Принудительно задаёт указанное значение в качестве возвращаемого результата. Этот метод предназначен для поддержки расширений и, как правило, не должен вызываться в других случаях.
Параметры:
value - значение

exec

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

peekNextLocalTask

protected static ForkJoinTask<?> peekNextLocalTask()
Возвращает, но не удаляет из очереди и не выполняет, задачу, поставленную в очередь текущим потоком, но ещё не выполненную, если такая задача немедленно доступна. Нет гарантии, что эта задача действительно будет следующей опрошена или выполнена. И наоборот, метод может вернуть null, даже если задача существует, но её нельзя получить без конкуренции с другими потоками. Этот метод предназначен главным образом для поддержки расширений и вряд ли будет полезен в других случаях.
Возвращает:
следующую задачу или null, если доступных задач нет

pollNextLocalTask

protected static ForkJoinTask<?> pollNextLocalTask()
Удаляет из очереди и возвращает, не выполняя, следующую задачу, поставленную в очередь текущим потоком, но ещё не выполненную, если текущий поток работает в ForkJoinPool. Этот метод предназначен главным образом для поддержки расширений и вряд ли будет полезен в других случаях.
Возвращает:
следующую задачу или null, если доступных задач нет

pollTask

protected static ForkJoinTask<?> pollTask()
Если текущий поток работает в ForkJoinPool, удаляет из очереди и возвращает, не выполняя, следующую доступную задачу, поставленную в очередь текущим потоком, но ещё не выполненную; если такая задача недоступна, возвращает доступную задачу, помещённую в очередь другим потоком. Доступность может быть временной, поэтому результат null не обязательно означает, что пул, в котором работает эта задача, находится в состоянии покоя. Этот метод предназначен главным образом для поддержки расширений и вряд ли будет полезен в других случаях.
Возвращает:
задачу или null, если доступных задач нет

pollSubmission

protected static ForkJoinTask<?> pollSubmission()
Если текущий поток работает в ForkJoinPool, удаляет из очереди и возвращает, не выполняя, отправленную в пул извне задачу, если такая задача доступна. Доступность может быть временной, поэтому результат null не обязательно означает, что пул находится в состоянии покоя. Этот метод предназначен главным образом для поддержки расширений и вряд ли будет полезен в других случаях.
Возвращает:
задачу или null, если доступных задач нет
С версии:
9

getForkJoinTaskTag

public final short getForkJoinTaskTag()
Возвращает метку этой задачи.
Возвращает:
метку этой задачи
С версии:
1.8

setForkJoinTaskTag

public final short setForkJoinTaskTag(short newValue)
Атомарно задаёт значение метки этой задачи и возвращает старое значение.
Параметры:
newValue - новое значение метки
Возвращает:
предыдущее значение метки
С версии:
1.8

compareAndSetForkJoinTaskTag

public final boolean compareAndSetForkJoinTaskTag(short expect, short update)
Условно и атомарно задаёт значение метки этой задачи. Помимо прочего, метки можно использовать в качестве маркеров посещения в задачах, работающих с графами, например в методах, которые перед обработкой проверяют: if (task.compareAndSetForkJoinTaskTag((short)0, (short)1)); в противном случае выполнение прекращается, поскольку узел уже был посещён.
Параметры:
expect - ожидаемое значение метки
update - новое значение метки
Возвращает:
true при успехе; то есть если текущее значение совпадало с expect и было изменено на update.
С версии:
1.8

adapt

public static ForkJoinTask<?> adapt(Runnable runnable)
Возвращает новый ForkJoinTask, который выполняет метод run указанного Runnable в качестве действия и возвращает результат null при вызове join().
Параметры:
runnable - действие runnable
Возвращает:
задача

adapt

public static <T> ForkJoinTask<T> adapt(Runnable runnable, T result)
Возвращает новый ForkJoinTask, который выполняет метод run указанного Runnable в качестве действия и возвращает указанное значение при вызове join().
Параметры типа:
T - тип результата
Параметры:
runnable - действие runnable
result - результат после завершения
Возвращает:
задача

adapt

public static <T> ForkJoinTask<T> adapt(Callable<? extends T> callable)
Возвращает новый ForkJoinTask, который выполняет метод call указанного Callable в качестве действия и возвращает его результат при вызове join(), преобразуя любые возникшие проверяемые исключения в RuntimeException.
Параметры типа:
T - тип результата callable
Параметры:
callable - действие callable
Возвращает:
задача

adaptInterruptible

public static <T> ForkJoinTask<T> adaptInterruptible(Callable<? extends T> callable)
Возвращает новый ForkJoinTask, который выполняет метод call заданного Callable в качестве действия и возвращает его результат при вызове join(), преобразуя возникающие проверяемые исключения в RuntimeException. Кроме того, вызовы cancel с mayInterruptIfRunning true попытаются прервать поток, выполняющий задачу.
Параметры типа:
T — тип результата вызываемого объекта
Параметры:
callable — действие вызываемого объекта
Возвращает:
задачу
Начиная с версии:
19

adaptInterruptible

public static <T> ForkJoinTask<T> adaptInterruptible(Runnable runnable, T result)
Возвращает новый ForkJoinTask, который выполняет метод run заданного Runnable в качестве действия и возвращает заданный результат при вызове join(), преобразуя возникающие проверяемые исключения в RuntimeException. Кроме того, вызовы cancel с mayInterruptIfRunning true попытаются прервать поток, выполняющий задачу.
Параметры типа:
T — тип результата
Параметры:
runnable — действие runnable
result — результат по завершении
Возвращает:
задачу
Начиная с версии:
22

adaptInterruptible

public static ForkJoinTask<?> adaptInterruptible(Runnable runnable)
Возвращает новый ForkJoinTask, который выполняет метод run заданного Runnable в качестве действия и возвращает null при вызове join(), преобразуя возникающие проверяемые исключения в RuntimeException. Кроме того, вызовы cancel с mayInterruptIfRunning true попытаются прервать поток, выполняющий задачу.
Параметры:
runnable — действие runnable
Возвращает:
задачу
Начиная с версии:
22

Сообщить об ошибке или предложить улучшение
Дополнительные справочные материалы по API и документацию для разработчиков см. в документации Java SE, содержащей более подробные описания для разработчиков, включая концептуальные обзоры, определения терминов, обходные решения и работающие примеры кода. Другие версии.
Java является товарным знаком или зарегистрированным товарным знаком Oracle и/или ее аффилированных лиц в США и других странах.
Авторские права © 1993, 2026, Oracle и/или ее аффилированные лица, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
Все права защищены. Использование регулируется условиями лицензии и политикой распространения документации.

© 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.

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API