Класс ForkJoinPool

Объект ExecutorService для выполнения ForkJoinTask задач. Объект ForkJoinPool предоставляет точку входа для задач от не-ForkJoinTask клиентов, а также для операций управления и мониторинга.

Объект ForkJoinPool отличается от других типов ExecutorService в основном тем, что использует кражу работы: все потоки в пуле пытаются найти и выполнить задачи, представленные в пуле и/или созданные другими активными задачами (в конечном итоге блокируются, ожидая работы, если таковой нет). Это обеспечивает эффективную обработку, когда большинство задач порождают другие подзадачи (как и большинство ForkJoinTask), а также когда во множество мелких задач представляется в пул от внешних клиентов. Особенно при установлении asyncMode в значение true в конструкторах, ForkJoinPool могут также быть подходящими для использования с задачами в стиле событий, которые никогда не присоединяются.

Статический commonPool() доступен и подходит для большинства приложений. Общий пул используется любой задачей ForkJoinTask, которая не представлена явным образом в указанный пул. Использование общего пула обычно снижает использование ресурсов (его потоки медленно освобождаются в периоды бездействия и возобновляются при последующем использовании).

Для приложений, требующих отдельных или настраиваемых пулов, может быть создан ForkJoinPool с заданным уровнем параллельности; по умолчанию равен количеству доступных процессоров. Пул пытается поддерживать достаточное количество активных (или доступных) потоков, динамически добавляя, приостанавливая или возобновляя внутренние рабочие потоки, даже если некоторые задачи приостановлены, ожидая присоединения к другим. Однако такие корректировки не гарантируются при наличии блокировок ввода-вывода или других не управляемых синхронизаций. Вложенный интерфейс ForkJoinPool.ManagedBlocker позволяет расширить типы синхронизации, которые поддерживаются.

В дополнение к методам управления выполнением и жизненным циклом, этот класс предоставляет методы проверки состояния (например, getStealCount()), которые предназначены для помощи в разработке, настройке и мониторинге приложений fork/join. Также метод toString() возвращает сведения о состоянии пула в удобной форме для неформального мониторинга.

Как и в случае с другими ExecutorService, существует три основных метода выполнения задач, обобщенных в следующей таблице. Они предназначены для использования в первую очередь клиентами, которые еще не участвуют в вычислениях fork/join в текущем пуле. Основные формы этих методов принимают экземпляры ForkJoinTask, но перегруженные формы также позволяют смешанное выполнение простых задач Runnable или Callable-основанных операций. Однако задачи, которые уже выполняются в пуле, обычно должны использовать формы внутри вычислений, указанные в таблице, если не используются задачи в стиле асинхронных событий, которые обычно не присоединяются, в этом случае мало разницы между выбором методов.

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

• java.util.concurrent.ForkJoinPool.common.parallelism - уровень параллельности, целое неотрицательное число
• java.util.concurrent.ForkJoinPool.common.threadFactory - имя класса ForkJoinPool.ForkJoinWorkerThreadFactory
• java.util.concurrent.ForkJoinPool.common.exceptionHandler - имя класса Thread.UncaughtExceptionHandler

Примечания к реализации: В этой реализации максимальное количество запущенных потоков ограничено 32767. Попытки создать пулы с количеством потоков больше максимального приведут к IllegalArgumentException.

Эта реализация отклоняет представленные задачи (то есть, выбросив RejectedExecutionException) только когда пул закрывается или внутренние ресурсы исчерпаны.

Поля

defaultForkJoinWorkerThreadFactory

public static final ForkJoinPool.ForkJoinWorkerThreadFactory defaultForkJoinWorkerThreadFactory

Создаёт новый ForkJoinWorkerThread. Этот фабричный метод используется, если не переопределён в конструкторах ForkJoinPool.

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

ForkJoinPool

public ForkJoinPool()

Создаёт ForkJoinPool с уровнем параллелизма, равным Runtime.availableProcessors(), используя стандартный фабричный метод потоков, без UncaughtExceptionHandler и неасинхронный режим обработки LIFO.

Исключения:

SecurityException - если существует менеджер безопасности и вызывающий объект не имеет разрешения на изменение потоков, поскольку он не обладает RuntimePermission("modifyThread")

ForkJoinPool

public ForkJoinPool(int parallelism)

Создаёт ForkJoinPool с указанным уровнем параллелизма, стандартным фабричным методом потоков, без UncaughtExceptionHandler и неасинхронный режим обработки LIFO.

Параметры:

parallelism - уровень параллелизма

Исключения:

IllegalArgumentException - если уровень параллелизма меньше или равен нулю, или больше допустимого предела реализации

SecurityException - если существует менеджер безопасности и вызывающий объект не имеет разрешения на изменение потоков, поскольку он не обладает RuntimePermission("modifyThread")

ForkJoinPool

public ForkJoinPool(int parallelism,
                    ForkJoinPool.ForkJoinWorkerThreadFactory factory,
                    Thread.UncaughtExceptionHandler handler,
                    boolean asyncMode)

Создаёт ForkJoinPool с заданными параметрами.

Параметры:

parallelism - уровень параллелизма. Для значения по умолчанию используйте Runtime.availableProcessors().

factory - фабричный метод для создания новых потоков. Для значения по умолчанию используйте defaultForkJoinWorkerThreadFactory.

handler - обработчик для внутренних рабочих потоков, которые завершаются из-за неисправимых ошибок, возникших во время выполнения задач. Для значения по умолчанию используйте null.

asyncMode - если true, устанавливает локальный режим планирования FIFO для разветвлённых задач, которые никогда не объединяются. Этот режим может быть более подходящим, чем режим локальной стековой обработки по умолчанию в приложениях, в которых рабочие потоки обрабатывают только асинхронные задачи в стиле событий. Для значения по умолчанию используйте false.

Исключения:

IllegalArgumentException - если уровень параллелизма меньше или равен нулю, или больше допустимого предела реализации

NullPointerException - если фабричный метод равен null

SecurityException - если существует менеджер безопасности и вызывающий объект не имеет разрешения на изменение потоков, поскольку он не обладает RuntimePermission("modifyThread")

Методы

commonPool

public static ForkJoinPool commonPool()

Возвращает общий экземпляр пула. Этот пул создаётся статически; его состояние выполнения не зависит от попыток shutdown() или shutdownNow(). Однако этот пул и любая текущая обработка автоматически завершаются при завершении программы System.exit(int). Любая программа, которая полагается на завершение асинхронной обработки задач перед завершением программы, должна вызывать commonPool().awaitQuiescence перед выходом.

Возвращает:

общий экземпляр пула

С версии:

1.8

invoke

public <T> T invoke(ForkJoinTask<T> task)

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

Параметры типа:

T - тип результата задачи

Параметры:

task - задача

Возвращает:

результат задачи

Исключения:

NullPointerException - если задача равна null

RejectedExecutionException - если задачу невозможно запланировать на выполнение

execute

public void execute(ForkJoinTask<?> task)

Организует (асинхронное) выполнение данной задачи.

Параметры:

task - задача

Исключения:

NullPointerException - если задача равна null

RejectedExecutionException - если задачу невозможно запланировать на выполнение

execute

public void execute(Runnable task)

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

Выполняет данную команду в некоторый момент времени в будущем. Команда может выполняться в новом потоке, в пуле потоков или в вызывающем потоке по усмотрению реализации Executor.

Параметры:

task - задача Runnable

Исключения:

NullPointerException - если задача равна null

RejectedExecutionException - если задачу невозможно запланировать на выполнение

submit

public <T> ForkJoinTask<T> submit(ForkJoinTask<T> task)

Отправляет ForkJoinTask на выполнение.

Параметры типа:

T - тип результата задачи

Параметры:

task - задача для отправки

Возвращает:

задача

Исключения:

NullPointerException - если задача равна null

RejectedExecutionException - если задачу невозможно запланировать на выполнение

submit

public <T> ForkJoinTask<T> submit(Callable<T> task)

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

Указано в:

submit в интерфейсе ExecutorService

Переопределяет:

submit в классе AbstractExecutorService

Параметры типа:

T - тип результата задачи

Параметры:

task - задача для отправки

Возвращает:

Future, представляющий ожидающее завершение задачи

Исключения:

NullPointerException - если задача равна null

RejectedExecutionException - если задачу невозможно запланировать на выполнение

submit

public <T> ForkJoinTask<T> submit(Runnable task,
                                  T result)

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

Отправляет задачу Runnable на выполнение и возвращает Future, представляющий эту задачу. Метод get Future вернёт данный результат после успешного завершения.

Указано в:

submit в интерфейсе ExecutorService

Переопределяет:

submit в классе AbstractExecutorService

Параметры типа:

T - тип результата

Параметры:

task - задача для отправки

result - результат для возврата

Возвращает:

Future, представляющий ожидающее завершение задачи

Исключения:

NullPointerException - если задача равна null

RejectedExecutionException - если задачу невозможно запланировать на выполнение

submit

public ForkJoinTask<?> submit(Runnable task)

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

Отправляет задачу Runnable на выполнение и возвращает Future, представляющий эту задачу. Метод get Future вернёт null при успешном завершении.

Указано в:

submit в интерфейсе ExecutorService

Переопределяет:

submit в классе AbstractExecutorService

Параметры:

task - задача для отправки

Возвращает:

Future, представляющий ожидающее завершение задачи

Исключения:

NullPointerException - если задача равна null

RejectedExecutionException - если задачу невозможно запланировать на выполнение

invokeAll

public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)

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

Выполняет заданные задачи, возвращая список Futures, содержащий их статус и результаты, когда все завершены. Future.isDone() равно true для каждого элемента возвращаемого списка. Обратите внимание, что завершённая задача может быть завершена либо нормально, либо с выбросом исключения. Результаты этого метода не определены, если данная коллекция изменяется во время выполнения этой операции.

Указано в:

invokeAll в интерфейсе ExecutorService

Переопределяет:

invokeAll в классе AbstractExecutorService

Параметры типа:

T - тип значений, возвращаемых из задач

Параметры:

tasks - коллекция задач

Возвращает:

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

Исключения:

NullPointerException - если tasks или любой из его элементов null

RejectedExecutionException - если любую задачу невозможно запланировать на выполнение

getFactory

public ForkJoinPool.ForkJoinWorkerThreadFactory getFactory()

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

Возвращает:

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

getUncaughtExceptionHandler

public Thread.UncaughtExceptionHandler getUncaughtExceptionHandler()

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

Возвращает:

обработчик или null при отсутствии

getParallelism

public int getParallelism()

Возвращает целевой уровень параллелизма этого пула.

Возвращает:

целевой уровень параллелизма этого пула

getCommonPoolParallelism

public static int getCommonPoolParallelism()

Возвращает целевой уровень параллелизма общего пула.

Возвращает:

целевой уровень параллелизма общего пула

С:

1.8

getPoolSize

public int getPoolSize()

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

Возвращает:

количество рабочих потоков

getAsyncMode

public boolean getAsyncMode()

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

Возвращает:

true если этот пул использует асинхронный режим

getRunningThreadCount

public int getRunningThreadCount()

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

Возвращает:

количество рабочих потоков

getActiveThreadCount

public int getActiveThreadCount()

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

Возвращает:

количество активных потоков

isQuiescent

public boolean isQuiescent()

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

Возвращает:

true если все потоки в настоящее время бездействуют

getStealCount

public long getStealCount()

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

Возвращает:

количество краж

getQueuedTaskCount

public long getQueuedTaskCount()

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

Возвращает:

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

getQueuedSubmissionCount

public int getQueuedSubmissionCount()

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

Возвращает:

количество ожидающих отправлений

hasQueuedSubmissions

public boolean hasQueuedSubmissions()

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

Возвращает:

true если есть ожидающие отправления

pollSubmission

protected ForkJoinTask<?> pollSubmission()

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

Возвращает:

следующее отправление или null при отсутствии

drainTasksTo

protected int drainTasksTo(Collection<? super ForkJoinTask<?>> c)

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

Параметры:

c - коллекция для перевода элементов

Возвращает:

количество перенесенных элементов

toString

public String toString()

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

Переопределяет:

toString в классе Object

Возвращает:

строка, идентифицирующая этот пул и его состояние

shutdown

public void shutdown()

Возможная инициирование упорядоченной остановки, в которой ранее отправленные задачи выполняются, но новые задачи не принимаются. Вызов не оказывает никакого влияния на состояние выполнения, если это commonPool(), и не оказывает никакого дополнительного влияния, если уже остановлено. Задачи, которые в процессе отправки одновременно во время выполнения этого метода, могут быть отклонены или нет.

Выбрасывает:

SecurityException - если существует диспетчер безопасности, и вызывающий процесс не имеет разрешения на изменение потоков, так как не имеет RuntimePermission("modifyThread")

shutdownNow

public List<Runnable> shutdownNow()

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

Возвращает:

пустой список

Выбрасывает:

SecurityException - если существует диспетчер безопасности, и вызывающий процесс не имеет разрешения на изменение потоков, так как не имеет RuntimePermission("modifyThread")

isTerminated

public boolean isTerminated()

Возвращает true если все задачи завершены после остановки.

Возвращает:

true если все задачи завершены после остановки

isTerminating

public boolean isTerminating()

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

Возвращает:

true если завершается, но еще не завершено

isShutdown

public boolean isShutdown()

Возвращает true если этот пул был остановлен.

Возвращает:

true если этот пул был остановлен

awaitTermination

public boolean awaitTermination(long timeout,
                                TimeUnit unit)
                         throws InterruptedException

Блокирует до тех пор, пока все задачи не завершат выполнение после запроса остановки или истечет таймаут или текущий поток будет прерван — что произойдет первым. Поскольку commonPool() никогда не завершается до завершения программы, при применении к общему пулу этот метод эквивалентен awaitQuiescence(long, TimeUnit), но всегда возвращает false.

Параметры:

timeout - максимальное время ожидания

unit - единица измерения времени аргумента таймаута

Возвращает:

true если этот исполняемый модуль завершен и false если таймаут истек до завершения

Выбрасывает:

InterruptedException - если прерван во время ожидания

awaitQuiescence

public boolean awaitQuiescence(long timeout,
                               TimeUnit unit)

Если вызов производится задачей ForkJoinTask, работающей в этом пуле, то эквивалентен ForkJoinTask.helpQuiesce(). В противном случае ожидает и/или пытается помочь в выполнении задач до тех пор, пока этот пул isQuiescent() или не истечет указанный таймаут.

Параметры:

timeout - максимальное время ожидания

unit - единица измерения времени аргумента таймаута

Возвращает:

true если в состоянии покоя; false если таймаут истек.

managedBlock

public static void managedBlock(ForkJoinPool.ManagedBlocker blocker)
                         throws InterruptedException

while (!blocker.isReleasable())
   if (blocker.block())
     break;

Параметры:

blocker - задача-блокировщик

Выбрасывает:

InterruptedException - если blocker.block() так сделало

newTaskFor

protected <T> RunnableFuture<T> newTaskFor(Runnable runnable,
                                           T value)

Описание скопировано из класса: AbstractExecutorService

Возвращает RunnableFuture для заданного Runnable и значения по умолчанию.

Переопределяет:

newTaskFor в классе AbstractExecutorService

Параметры типа:

T - тип заданного значения

Параметры:

runnable - задача Runnable, которая оборачивается

value - значение по умолчанию для возвращаемого будущего

Возвращает:

RunnableFuture, которое при выполнении выполнит заданный Runnable и которое, как Future, вернёт заданное значение в качестве результата и позволит отменить задачу

newTaskFor

protected <T> RunnableFuture<T> newTaskFor(Callable<T> callable)

Описание скопировано из класса: AbstractExecutorService

Возвращает RunnableFuture для заданной задачи Callable.

Переопределяет:

newTaskFor в классе AbstractExecutorService

Параметры типа:

T - тип результата callable

Параметры:

callable - задача Callable, которая оборачивается

Возвращает:

RunnableFuture, которое при выполнении вызовет заданный callable и которое, как Future, вернёт результат callable в качестве результата и позволит отменить задачу