Класс ForkJoinTask<V>

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

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

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

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

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

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

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

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

Конструкторы

ForkJoinTask

public ForkJoinTask()

Методы

fork

public final ForkJoinTask<V> fork()

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

Возвращает:

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

join

public final V join()

Возвращает результат вычисления, когда он is done. Этот метод отличается от 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 в интерфейсе 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 , если эта задача завершилась без выброса исключения и не была отменена

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()

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

helpQuiesce

public static void helpQuiesce()

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

reinitialize

public void reinitialize()

getPool

public static ForkJoinPool getPool()

Возвращает пул, в котором выполняется текущая задача, или null, если эта задача выполняется вне ForkJoinPool.

Возвращает:

пул, или null если нет

См. также:

inForkJoinPool()

inForkJoinPool

public static boolean inForkJoinPool()

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

Возвращает:

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

tryUnfork

public boolean tryUnfork()

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

Возвращает:

true если отменено

getQueuedTaskCount

public static int getQueuedTaskCount()

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

Возвращает:

количество задач

getSurplusQueuedTaskCount

public static int getSurplusQueuedTaskCount()

Возвращает оценку того, на сколько больше локально очередированных задач удерживает текущий поток-рабочий, чем других потоков-рабочих, которые могут их украсть, или ноль, если этот поток не работает в ForkJoinPool. Это значение может быть полезно для эвристических решений о том, следует ли создавать другие задачи. Во многих случаях использования ForkJoinTasks в стационарном состоянии каждый рабочий должен стремиться поддерживать небольшой постоянный избыток (например, 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 если нет доступных

getForkJoinTaskTag

public final short getForkJoinTaskTag()

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

Возвращает:

метку для этой задачи

С:

1.8

setForkJoinTaskTag

public final short setForkJoinTaskTag(short tag)

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

Параметры:

tag - значение метки

Возвращает:

предыдущее значение метки

С:

1.8

compareAndSetForkJoinTaskTag

public final boolean compareAndSetForkJoinTaskTag(short e,
                                                  short tag)

Атомарно условно устанавливает значение метки для этой задачи. Среди других применений, метки могут использоваться в качестве маркеров посещения в задачах, работающих с графами, как в методах, которые проверяют: if (task.compareAndSetForkJoinTaskTag((short)0, (short)1)) перед обработкой, в противном случае завершая работу, потому что узел уже был посещён.

Параметры:

e - ожидаемое значение метки

tag - новое значение метки

Возвращает:

true если успешно; т. е. текущее значение было равно e и теперь является меткой.

С:

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 - вызываемый объект

Возвращает:

задачу