Spec-Zone.ru › OpenJDK 27

Класс ThreadPoolExecutor

java.lang.Object
java.util.concurrent.AbstractExecutorService
java.util.concurrent.ThreadPoolExecutor
Все реализуемые интерфейсы:
AutoCloseable, Executor, ExecutorService
Прямые известные подклассы:
ScheduledThreadPoolExecutor
public class ThreadPoolExecutor extends AbstractExecutorService
ExecutorService, выполняющий каждую отправленную задачу с помощью одного из нескольких потоков пула, обычно настраиваемого с помощью фабричных методов Executors.

Пулы потоков решают две разные задачи: обычно они повышают производительность при выполнении большого количества асинхронных задач за счёт снижения накладных расходов на запуск каждой задачи и предоставляют средства ограничения и управления ресурсами, включая потоки, используемыми при выполнении набора задач. Каждый ThreadPoolExecutor также поддерживает некоторые основные статистические данные, например количество завершённых задач.

Чтобы быть полезным в широком диапазоне ситуаций, этот класс предоставляет множество настраиваемых параметров и возможностей расширения. Однако программистам рекомендуется использовать более удобные фабричные методы Executors: Executors.newCachedThreadPool() (пул потоков неограниченного размера с автоматическим освобождением потоков), Executors.newFixedThreadPool(int) (пул потоков фиксированного размера) и Executors.newSingleThreadExecutor() (один фоновый поток), предварительно настраивающие параметры для наиболее распространённых сценариев использования. В противном случае при ручной настройке этого класса воспользуйтесь следующими рекомендациями:

Минимальный и максимальный размеры пула
ThreadPoolExecutor будет автоматически изменять размер пула (см. getPoolSize()) в соответствии с границами, заданными параметрами corePoolSize (см. getCorePoolSize()) и maximumPoolSize (см. getMaximumPoolSize()). Когда новая задача отправляется методом execute(Runnable), если работает меньше потоков, чем corePoolSize, для обработки запроса создаётся новый поток, даже если другие рабочие потоки простаивают. Если же работает меньше потоков, чем maximumPoolSize, новый поток для обработки запроса создаётся только в том случае, если очередь заполнена. Если задать одинаковые значения corePoolSize и maximumPoolSize, будет создан пул потоков фиксированного размера. Если задать для maximumPoolSize практически неограниченное значение, например Integer.MAX_VALUE, пул сможет обслуживать произвольное количество параллельных задач. Обычно минимальный и максимальный размеры пула задаются только при создании, однако их также можно динамически изменять с помощью методов setCorePoolSize(int) и setMaximumPoolSize(int).
Создание по требованию
По умолчанию даже основные потоки создаются и запускаются только при поступлении новых задач, но это поведение можно динамически изменить с помощью метода prestartCoreThread() или prestartAllCoreThreads(). Если пул создаётся с непустой очередью, вероятно, стоит предварительно запустить потоки.
Создание новых потоков
Новые потоки создаются с помощью ThreadFactory. Если не указано иное, используется Executors.defaultThreadFactory(), которая создаёт потоки в одной и той же ThreadGroup с одинаковым приоритетом NORM_PRIORITY и статусом недемон-потока. Передав другую ThreadFactory, можно изменить имя потока, группу потоков, приоритет, статус демона и другие параметры. Если ThreadFactory не удаётся создать поток по запросу и она возвращает null из newThread, исполнитель продолжит работу, но может оказаться не в состоянии выполнять задачи.
Время ожидания бездействия
Если в пуле сейчас больше потоков, чем corePoolSize, лишние потоки будут завершены, если они бездействовали дольше времени keepAliveTime (см. getKeepAliveTime(TimeUnit)). Это позволяет снизить потребление ресурсов, когда пул не используется активно. Если позднее пул станет активнее, будут созданы новые потоки. Этот параметр также можно динамически изменять методом setKeepAliveTime(long, TimeUnit). Использование значения Long.MAX_VALUE TimeUnit.NANOSECONDS фактически запрещает завершение бездействующих потоков до остановки пула. По умолчанию политика времени ожидания применяется только тогда, когда потоков больше, чем corePoolSize, однако метод allowCoreThreadTimeOut(boolean) позволяет применять её и к основным потокам, если значение keepAliveTime не равно нулю.
Очереди
Для передачи и хранения отправленных задач можно использовать любую BlockingQueue. Использование этой очереди влияет на размер пула:
  • Если работает меньше потоков, чем corePoolSize, Executor всегда предпочитает добавить новый поток, а не помещать задачу в очередь.
  • Если работает не меньше потоков, чем corePoolSize, Executor всегда предпочитает поместить запрос в очередь, а не добавлять новый поток.
  • Если запрос нельзя поместить в очередь, создаётся новый поток, если это не приведёт к превышению maximumPoolSize; в противном случае задача будет отклонена.
Существует три общие стратегии организации очередей:
  1. Непосредственная передача. Хорошим вариантом по умолчанию для рабочей очереди является SynchronousQueue, передающая задачи потокам, не сохраняя их. В этом случае попытка поместить задачу в очередь завершится неудачей, если нет потоков, готовых немедленно её выполнить, поэтому будет создан новый поток. Эта политика позволяет избежать блокировок при обработке наборов запросов, которые могут зависеть друг от друга. Для непосредственной передачи обычно требуется неограниченное значение maximumPoolSize, чтобы избежать отклонения новых отправленных задач. Это, в свою очередь, допускает неограниченный рост числа потоков, если команды продолжают поступать в среднем быстрее, чем их можно обработать.
  2. Неограниченные очереди. Использование неограниченной очереди (например, LinkedBlockingQueue без заранее заданной ёмкости) приводит к тому, что новые задачи ожидают в очереди, когда все потоки corePoolSize заняты. Таким образом, потоков никогда не будет создано больше, чем corePoolSize. (Поэтому значение maximumPoolSize не будет иметь никакого эффекта.) Такой вариант может подойти, если каждая задача полностью независима от остальных и задачи не могут влиять на выполнение друг друга, например, в сервере веб-страниц. Хотя такая стратегия организации очереди помогает сглаживать кратковременные всплески запросов, она допускает неограниченный рост очереди задач, если команды продолжают поступать в среднем быстрее, чем их можно обработать.
  3. Ограниченные очереди. Ограниченная очередь (например, ArrayBlockingQueue) помогает предотвратить исчерпание ресурсов при использовании конечного значения maximumPoolSize, однако её настройка и управление могут быть сложнее. Размер очереди и максимальный размер пула можно подбирать взаимосвязанно: большие очереди и небольшие пулы сокращают использование ЦП, ресурсов ОС и накладные расходы на переключение контекста, но могут привести к искусственно низкой пропускной способности. Если задачи часто блокируются (например, из-за операций ввода-вывода), система может иметь возможность выделить время для большего числа потоков, чем предусмотрено настройками. Использование небольших очередей обычно требует более крупных пулов: это позволяет активнее загружать ЦП, но может привести к неприемлемым накладным расходам на планирование, что также снижает пропускную способность.
Отклонённые задачи
Новые задачи, отправленные методом execute(Runnable), будут отклонены, если Executor остановлен, а также если Executor использует конечные ограничения как на число потоков, так и на ёмкость рабочей очереди и достиг этих ограничений. В обоих случаях метод execute вызывает метод RejectedExecutionHandler.rejectedExecution(Runnable, ThreadPoolExecutor) своего RejectedExecutionHandler. Предусмотрены четыре стандартные политики обработки:
  1. При использовании политики по умолчанию ThreadPoolExecutor.AbortPolicy обработчик при отклонении выбрасывает исключение времени выполнения RejectedExecutionException.
  2. При использовании ThreadPoolExecutor.CallerRunsPolicy поток, вызывающий execute, сам выполняет задачу. Это обеспечивает простой механизм обратной связи, замедляющий отправку новых задач.
  3. При использовании ThreadPoolExecutor.DiscardPolicy невыполнимая задача просто отбрасывается. Эта политика предназначена только для редких случаев, когда завершение задачи не имеет значения.
  4. При использовании ThreadPoolExecutor.DiscardOldestPolicy, если исполнитель не остановлен, задача в начале рабочей очереди отбрасывается, после чего предпринимается повторная попытка выполнения (которая тоже может завершиться неудачей, и тогда процесс повторится). Эта политика приемлема лишь в редких случаях. Почти всегда следует также отменить задачу, чтобы вызвать исключение в компоненте, ожидающем её завершения, и/или записать ошибку в журнал, как показано в документации ThreadPoolExecutor.DiscardOldestPolicy.
Можно определять и использовать другие типы классов RejectedExecutionHandler. Для этого требуется соблюдать осторожность, особенно если политики предназначены для работы только с определёнными ограничениями ёмкости или стратегиями организации очереди.
Методы-перехватчики
Этот класс предоставляет protected переопределяемые методы beforeExecute(Thread, Runnable) и afterExecute(Runnable, Throwable), вызываемые до и после выполнения каждой задачи. Их можно использовать для управления средой выполнения, например для повторной инициализации ThreadLocal, сбора статистики или добавления записей в журнал. Кроме того, метод terminated() можно переопределить для выполнения специальных действий после полной остановки Executor.

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

Обслуживание очереди
Метод getQueue() предоставляет доступ к рабочей очереди для мониторинга и отладки. Использование этого метода в любых других целях настоятельно не рекомендуется. Для освобождения памяти, когда отменяется большое количество задач в очереди, доступны два метода: remove(Runnable) и purge().
Освобождение ресурсов
Пул, на который в программе больше нет ссылок И в котором не осталось потоков, может быть освобождён (собран сборщиком мусора) без явного вызова остановки. Можно настроить пул так, чтобы все неиспользуемые потоки со временем завершались, задав соответствующее время ожидания, установив нижнюю границу числа основных потоков равной нулю и/или вызвав allowCoreThreadTimeOut(boolean).

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

class PausableThreadPoolExecutor extends ThreadPoolExecutor {
  private boolean isPaused;
  private ReentrantLock pauseLock = new ReentrantLock();
  private Condition unpaused = pauseLock.newCondition();

  public PausableThreadPoolExecutor(...) { super(...); }

  protected void beforeExecute(Thread t, Runnable r) {
    super.beforeExecute(t, r);
    pauseLock.lock();
    try {
      while (isPaused) unpaused.await();
    } catch (InterruptedException ie) {
      t.interrupt();
    } finally {
      pauseLock.unlock();
    }
  }

  public void pause() {
    pauseLock.lock();
    try {
      isPaused = true;
    } finally {
      pauseLock.unlock();
    }
  }

  public void resume() {
    pauseLock.lock();
    try {
      isPaused = false;
      unpaused.signalAll();
    } finally {
      pauseLock.unlock();
    }
  }
}
Начиная с:
1.5

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

Модификатор и тип Класс Описание
static class  ThreadPoolExecutor.AbortPolicy
Обработчик отклонённых задач, выбрасывающий исключение RejectedExecutionException.
static class  ThreadPoolExecutor.CallerRunsPolicy
Обработчик отклонённых задач, выполняющий отклонённую задачу непосредственно в вызывающем потоке метода execute, если только исполнитель не остановлен; в этом случае задача отбрасывается.
static class  ThreadPoolExecutor.DiscardOldestPolicy
Обработчик отклонённых задач, отбрасывающий самый старый необработанный запрос и затем повторно вызывающий execute, если только исполнитель не остановлен; в этом случае задача отбрасывается.
static class  ThreadPoolExecutor.DiscardPolicy
Обработчик отклонённых задач, молча отбрасывающий отклонённую задачу.

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

Конструктор Описание
ThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue)
Создаёт новый ThreadPoolExecutor с заданными начальными параметрами, фабрикой потоков по умолчанию и обработчиком отклонённых задач по умолчанию.
ThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue, RejectedExecutionHandler handler)
Создаёт новый ThreadPoolExecutor с заданными начальными параметрами и фабрикой потоков по умолчанию.
ThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue, ThreadFactory threadFactory)
Создаёт новый ThreadPoolExecutor с заданными начальными параметрами и обработчиком отклонённых задач по умолчанию.
ThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue, ThreadFactory threadFactory, RejectedExecutionHandler handler)
Создаёт новый ThreadPoolExecutor с заданными начальными параметрами.

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

Модификатор и тип Метод Описание
protected void afterExecute(Runnable r, Throwable t)
Метод, вызываемый после завершения выполнения заданного Runnable.
void allowCoreThreadTimeOut(boolean value)
Задаёт политику, определяющую, могут ли основные потоки завершаться по истечении времени ожидания, если новые задачи не поступают; при необходимости они заменяются при поступлении новых задач.
boolean allowsCoreThreadTimeOut()
Возвращает true, если этот пул позволяет основным потокам завершаться по истечении времени keepAlive, когда новые задачи не поступают; при необходимости они заменяются при поступлении новых задач.
boolean awaitTermination(long timeout, TimeUnit unit)
Блокирует выполнение до завершения всех задач после запроса остановки, истечения времени ожидания или прерывания текущего потока — в зависимости от того, что произойдёт первым.
protected void beforeExecute(Thread t, Runnable r)
Метод, вызываемый перед выполнением заданного Runnable в указанном потоке.
void execute(Runnable command)
Выполняет указанную задачу в будущем.
int getActiveCount()
Возвращает приблизительное количество потоков, активно выполняющих задачи.
long getCompletedTaskCount()
Возвращает приблизительное общее количество задач, выполнение которых завершено.
int getCorePoolSize()
Возвращает количество основных потоков.
long getKeepAliveTime(TimeUnit unit)
Возвращает время ожидания потока — промежуток времени, в течение которого потоки могут простаивать до завершения.
int getLargestPoolSize()
Возвращает наибольшее количество потоков, одновременно находившихся в пуле.
int getMaximumPoolSize()
Возвращает максимально допустимое количество потоков.
int getPoolSize()
Возвращает текущее количество потоков в пуле.
BlockingQueue<Runnable> getQueue()
Возвращает очередь задач, используемую этим исполнителем.
RejectedExecutionHandler getRejectedExecutionHandler()
Возвращает текущий обработчик невыполнимых задач.
long getTaskCount()
Возвращает приблизительное общее количество задач, когда-либо запланированных к выполнению.
ThreadFactory getThreadFactory()
Возвращает фабрику потоков, используемую для создания новых потоков.
boolean isShutdown()
Возвращает true, если этот исполнитель остановлен.
boolean isTerminated()
Возвращает true, если после остановки завершены все задачи.
boolean isTerminating()
Возвращает true, если этот исполнитель находится в процессе остановки после вызова shutdown() или shutdownNow(), но ещё не остановлен полностью.
int prestartAllCoreThreads()
Запускает все основные потоки, переводя их в режим ожидания задач.
boolean prestartCoreThread()
Запускает основной поток, переводя его в режим ожидания задач.
void purge()
Пытается удалить из рабочей очереди все отменённые задачи Future.
boolean remove(Runnable task)
Удаляет эту задачу из внутренней очереди исполнителя, если она там присутствует, предотвращая её выполнение, если оно ещё не началось.
void setCorePoolSize(int corePoolSize)
Задаёт количество основных потоков.
void setKeepAliveTime(long time, TimeUnit unit)
Задаёт время ожидания потока — промежуток времени, в течение которого потоки могут простаивать до завершения.
void setMaximumPoolSize(int maximumPoolSize)
Задаёт максимально допустимое количество потоков.
void setRejectedExecutionHandler(RejectedExecutionHandler handler)
Задаёт новый обработчик невыполнимых задач.
void setThreadFactory(ThreadFactory threadFactory)
Задаёт фабрику потоков, используемую для создания новых потоков.
void shutdown()
Инициирует упорядоченную остановку, при которой ранее отправленные задачи выполняются, но новые задачи не принимаются.
List<Runnable> shutdownNow()
Пытается остановить все активно выполняемые задачи, прекращает обработку ожидающих задач и возвращает список задач, ожидавших выполнения.
protected void terminated()
Метод, вызываемый после остановки Executor.
String toString()
Возвращает строку, описывающую этот пул и его состояние, включая сведения о состоянии выполнения и приблизительном количестве рабочих потоков и задач.

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

invokeAll, invokeAll, invokeAny, invokeAny, newTaskFor, newTaskFor, submit, submit, submit
Модификатор и тип Метод Описание
<T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
Выполняет указанные задачи и возвращает список Future, содержащих их состояние и результаты после завершения всех задач.
<T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
Выполняет указанные задачи и возвращает список Future, содержащих их состояние и результаты после завершения всех задач или истечения времени ожидания — в зависимости от того, что произойдёт первым.
<T> T invokeAny(Collection<? extends Callable<T>> tasks)
Выполняет указанные задачи и, если какая-либо из них завершится успешно (то есть без выбрасывания исключения), возвращает результат одной из них.
<T> T invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
Выполняет указанные задачи и, если какая-либо из них завершится успешно (то есть без выбрасывания исключения) до истечения заданного времени ожидания, возвращает результат одной из них.
protected <T> RunnableFuture<T> newTaskFor(Runnable runnable, T value)
Возвращает RunnableFuture для заданного Runnable и значения по умолчанию.
protected <T> RunnableFuture<T> newTaskFor(Callable<T> callable)
Возвращает RunnableFuture для заданной задачи Callable.
Future<?> submit(Runnable task)
Отправляет задачу Runnable на выполнение и возвращает Future, представляющий эту задачу.
<T> Future<T> submit(Runnable task, T result)
Отправляет задачу Runnable на выполнение и возвращает Future, представляющий эту задачу.
<T> Future<T> submit(Callable<T> task)
Отправляет на выполнение задачу, возвращающую значение, и возвращает Future, представляющий ожидающие результаты задачи.

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

clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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()
Пробуждает все потоки, ожидающие на мониторе этого объекта.
final void wait()
Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания.
final void wait(long timeoutMillis)
Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного промежутка реального времени.
final void wait(long timeoutMillis, int nanos)
Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного промежутка реального времени.

Методы, объявленные в интерфейсе ExecutorService

close
Модификатор и тип Метод Описание
default void close()
Инициирует упорядоченную остановку, при которой ранее отправленные задачи выполняются, но новые задачи не принимаются.

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

ThreadPoolExecutor

public ThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue)
Создает новый ThreadPoolExecutor с указанными начальными параметрами, фабрикой потоков по умолчанию и обработчиком отклоненного выполнения по умолчанию.

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

Параметры:
corePoolSize — количество потоков, сохраняемых в пуле, даже если они бездействуют, если не задано allowCoreThreadTimeOut
maximumPoolSize — максимально допустимое количество потоков в пуле
keepAliveTime — если количество потоков превышает базовое, это максимальное время, в течение которого лишние простаивающие потоки будут ожидать новые задачи перед завершением.
unit — единица измерения времени для аргумента keepAliveTime
workQueue — очередь для хранения задач до их выполнения. Эта очередь будет содержать только задачи Runnable, отправленные методом execute.
Исключения:
IllegalArgumentException — если выполняется одно из следующих условий:
corePoolSize < 0
keepAliveTime < 0
maximumPoolSize <= 0
maximumPoolSize < corePoolSize
NullPointerException — если workQueue имеет значение null

ThreadPoolExecutor

public ThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue, ThreadFactory threadFactory)
Создает новый ThreadPoolExecutor с указанными начальными параметрами и обработчиком отклоненного выполнения по умолчанию.
Параметры:
corePoolSize — количество потоков, сохраняемых в пуле, даже если они бездействуют, если не задано allowCoreThreadTimeOut
maximumPoolSize — максимально допустимое количество потоков в пуле
keepAliveTime — если количество потоков превышает базовое, это максимальное время, в течение которого лишние простаивающие потоки будут ожидать новые задачи перед завершением.
unit — единица измерения времени для аргумента keepAliveTime
workQueue — очередь для хранения задач до их выполнения. Эта очередь будет содержать только задачи Runnable, отправленные методом execute.
threadFactory — фабрика, используемая исполнителем при создании нового потока
Исключения:
IllegalArgumentException — если выполняется одно из следующих условий:
corePoolSize < 0
keepAliveTime < 0
maximumPoolSize <= 0
maximumPoolSize < corePoolSize
NullPointerException — если workQueue или threadFactory имеет значение null

ThreadPoolExecutor

public ThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue, RejectedExecutionHandler handler)
Создает новый ThreadPoolExecutor с указанными начальными параметрами и фабрикой потоков по умолчанию.
Параметры:
corePoolSize — количество потоков, сохраняемых в пуле, даже если они бездействуют, если не задано allowCoreThreadTimeOut
maximumPoolSize — максимально допустимое количество потоков в пуле
keepAliveTime — если количество потоков превышает базовое, это максимальное время, в течение которого лишние простаивающие потоки будут ожидать новые задачи перед завершением.
unit — единица измерения времени для аргумента keepAliveTime
workQueue — очередь для хранения задач до их выполнения. Эта очередь будет содержать только задачи Runnable, отправленные методом execute.
handler — обработчик, используемый при блокировке выполнения из-за достижения ограничений на количество потоков и емкость очереди
Исключения:
IllegalArgumentException — если выполняется одно из следующих условий:
corePoolSize < 0
keepAliveTime < 0
maximumPoolSize <= 0
maximumPoolSize < corePoolSize
NullPointerException — если workQueue или handler имеет значение null

ThreadPoolExecutor

public ThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue, ThreadFactory threadFactory, RejectedExecutionHandler handler)
Создает новый ThreadPoolExecutor с указанными начальными параметрами.
Параметры:
corePoolSize — количество потоков, сохраняемых в пуле, даже если они бездействуют, если не задано allowCoreThreadTimeOut
maximumPoolSize — максимально допустимое количество потоков в пуле
keepAliveTime — если количество потоков превышает базовое, это максимальное время, в течение которого лишние простаивающие потоки будут ожидать новые задачи перед завершением.
unit — единица измерения времени для аргумента keepAliveTime
workQueue — очередь для хранения задач до их выполнения. Эта очередь будет содержать только задачи Runnable, отправленные методом execute.
threadFactory — фабрика, используемая исполнителем при создании нового потока
handler — обработчик, используемый при блокировке выполнения из-за достижения ограничений на количество потоков и емкость очереди
Исключения:
IllegalArgumentException — если выполняется одно из следующих условий:
corePoolSize < 0
keepAliveTime < 0
maximumPoolSize <= 0
maximumPoolSize < corePoolSize
NullPointerException — если workQueue, threadFactory или handler имеет значение null

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

execute

public void execute(Runnable command)
Выполняет указанную задачу в будущем. Задача может быть выполнена в новом потоке или в существующем потоке пула. Если задачу невозможно отправить на выполнение — либо потому, что работа этого исполнителя была прекращена, либо потому, что достигнута его емкость, — задача передается текущему RejectedExecutionHandler.
Параметры:
command — выполняемая задача
Исключения:
RejectedExecutionException — по усмотрению RejectedExecutionHandler, если задача не может быть принята к выполнению
NullPointerException — если command имеет значение null

shutdown

public void shutdown()
Инициирует упорядоченное завершение работы: ранее отправленные задачи выполняются, но новые задачи приниматься не будут. Если работа уже прекращена, вызов не оказывает дополнительного эффекта.

Этот метод не ожидает завершения ранее отправленных задач. Для этого используйте awaitTermination.

shutdownNow

public List<Runnable> shutdownNow()
Пытается остановить все выполняющиеся задачи, прекращает обработку ожидающих задач и возвращает список задач, ожидавших выполнения. При возврате из этого метода эти задачи извлекаются (удаляются) из очереди задач.

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

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

Возвращает:
список задач, выполнение которых так и не началось

isShutdown

public boolean isShutdown()
Описание скопировано из интерфейса: ExecutorService
Возвращает true, если работа этого исполнителя была прекращена.
Возвращает:
true, если работа этого исполнителя была прекращена

isTerminating

public boolean isTerminating()
Возвращает true, если этот исполнитель находится в процессе завершения после вызова shutdown() или shutdownNow(), но еще не завершил работу. Этот метод может быть полезен при отладке. Если спустя достаточное время после вызова метода завершения работы возвращается true, это может указывать на то, что отправленные задачи проигнорировали или подавили прерывание, из-за чего исполнитель не может корректно завершить работу.
Возвращает:
true, если завершение работы выполняется, но еще не закончено

isTerminated

public boolean isTerminated()
Описание скопировано из интерфейса: ExecutorService
Возвращает true, если после прекращения работы все задачи завершили выполнение. Обратите внимание, что isTerminated никогда не принимает значение true, если предварительно не был вызван метод shutdown или shutdownNow.
Возвращает:
true, если после прекращения работы все задачи завершили выполнение

awaitTermination

public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException
Описание скопировано из интерфейса: ExecutorService
Блокирует выполнение до завершения всех задач после запроса на прекращение работы, истечения времени ожидания или прерывания текущего потока — в зависимости от того, что произойдет первым.
Параметры:
timeout — максимальное время ожидания
unit — единица измерения времени ожидания
Возвращает:
true, если работа этого исполнителя завершилась, и false, если время ожидания истекло до завершения
Исключения:
InterruptedException — если во время ожидания произошло прерывание

setThreadFactory

public void setThreadFactory(ThreadFactory threadFactory)
Задает фабрику потоков, используемую для создания новых потоков.
Параметры:
threadFactory — новая фабрика потоков
Исключения:
NullPointerException — если threadFactory имеет значение null
См. также:
  • getThreadFactory()

getThreadFactory

public ThreadFactory getThreadFactory()
Возвращает фабрику потоков, используемую для создания новых потоков.
Возвращает:
текущую фабрику потоков
См. также:
  • setThreadFactory(ThreadFactory)

setRejectedExecutionHandler

public void setRejectedExecutionHandler(RejectedExecutionHandler handler)
Задает новый обработчик для невыполнимых задач.
Параметры:
handler — новый обработчик
Исключения:
NullPointerException — если handler имеет значение null
См. также:
  • getRejectedExecutionHandler()

getRejectedExecutionHandler

public RejectedExecutionHandler getRejectedExecutionHandler()
Возвращает текущий обработчик невыполнимых задач.
Возвращает:
текущий обработчик
См. также:
  • setRejectedExecutionHandler(RejectedExecutionHandler)

setCorePoolSize

public void setCorePoolSize(int corePoolSize)
Задает базовое количество потоков. Это значение переопределяет значение, заданное в конструкторе. Если новое значение меньше текущего, лишние существующие потоки будут завершены, когда в следующий раз перейдут в состояние ожидания. Если оно больше, при необходимости будут запущены новые потоки для выполнения задач из очереди.
Параметры:
corePoolSize — новый размер базового пула
Исключения:
IllegalArgumentException — если corePoolSize < 0 или corePoolSize превышает максимальный размер пула
См. также:
  • getCorePoolSize()

getCorePoolSize

public int getCorePoolSize()
Возвращает базовое количество потоков.
Возвращает:
базовое количество потоков
См. также:
  • setCorePoolSize(int)

prestartCoreThread

public boolean prestartCoreThread()
Запускает базовый поток, который будет ожидать выполнения работы. Это переопределяет политику по умолчанию, согласно которой базовые потоки запускаются только при выполнении новых задач. Этот метод возвращает false, если все базовые потоки уже запущены.
Возвращает:
true, если поток был запущен

prestartAllCoreThreads

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

allowsCoreThreadTimeOut

public boolean allowsCoreThreadTimeOut()
Возвращает true, если этот пул допускает завершение базовых потоков по истечении времени ожидания, когда в течение времени keepAlive не поступают задачи; при необходимости такие потоки заменяются при поступлении новых задач. Если возвращается true, к базовым потокам применяется та же политика времени ожидания, что и к небазовым. Если возвращается false (значение по умолчанию), базовые потоки никогда не завершаются из-за отсутствия входящих задач.
Возвращает:
true, если для базовых потоков допускается истечение времени ожидания, иначе false
С версии:
1.6

allowCoreThreadTimeOut

public void allowCoreThreadTimeOut(boolean value)
Задает политику, определяющую, могут ли базовые потоки завершаться по истечении времени ожидания, если в течение времени keep-alive не поступают задачи; при необходимости такие потоки заменяются при поступлении новых задач. Если значение равно false, базовые потоки никогда не завершаются из-за отсутствия входящих задач. Если значение равно true, к базовым потокам применяется та же политика времени ожидания, что и к небазовым. Чтобы избежать постоянной замены потоков, при установке true время ожидания должно быть больше нуля. Как правило, этот метод следует вызывать до начала активного использования пула.
Параметры:
value — true, если время ожидания должно истекать, иначе false
Исключения:
IllegalArgumentException — если значение равно true, а текущее время ожидания не больше нуля
С версии:
1.6

setMaximumPoolSize

public void setMaximumPoolSize(int maximumPoolSize)
Задает максимально допустимое количество потоков. Это значение переопределяет значение, заданное в конструкторе. Если новое значение меньше текущего, лишние существующие потоки будут завершены, когда в следующий раз перейдут в состояние ожидания.
Параметры:
maximumPoolSize — новое максимальное значение
Исключения:
IllegalArgumentException — если новое максимальное значение меньше или равно нулю либо меньше размера базового пула
См. также:
  • getMaximumPoolSize()

getMaximumPoolSize

public int getMaximumPoolSize()
Возвращает максимально допустимое количество потоков.
Возвращает:
максимально допустимое количество потоков
См. также:
  • setMaximumPoolSize(int)

setKeepAliveTime

public void setKeepAliveTime(long time, TimeUnit unit)
Задает время ожидания потока — период, в течение которого потоки могут оставаться бездействующими до завершения. Потоки, которые в течение этого времени ожидают, не обрабатывая задачи, будут завершены, если в пуле сейчас больше потоков, чем базовое количество, или если в этом пуле допускается завершение базовых потоков по истечении времени ожидания. Это значение переопределяет значение, заданное в конструкторе.
Параметры:
time — время ожидания. Нулевое значение приводит к немедленному завершению лишних потоков после выполнения задач.
unit — единица измерения времени для аргумента time
Исключения:
IllegalArgumentException — если time меньше нуля или если time равно нулю и allowsCoreThreadTimeOut
См. также:
  • getKeepAliveTime(TimeUnit)

getKeepAliveTime

public long getKeepAliveTime(TimeUnit unit)
Возвращает время ожидания потока — период, в течение которого потоки могут оставаться бездействующими до завершения. Потоки, которые в течение этого времени ожидают, не обрабатывая задачи, будут завершены, если в пуле сейчас больше потоков, чем базовое количество, или если в этом пуле допускается завершение базовых потоков по истечении времени ожидания.
Параметры:
unit — требуемая единица измерения возвращаемого значения
Возвращает:
ограничение времени
См. также:
  • setKeepAliveTime(long, TimeUnit)

getQueue

public BlockingQueue<Runnable> getQueue()
Возвращает очередь задач, используемую этим исполнителем. Доступ к очереди задач предназначен главным образом для отладки и мониторинга. Очередь может активно использоваться. Получение очереди задач не препятствует выполнению задач из нее.
Возвращает:
очередь задач

remove

public boolean remove(Runnable task)
Удаляет эту задачу из внутренней очереди исполнителя, если она в ней присутствует, тем самым предотвращая ее выполнение, если оно еще не началось.

Этот метод может быть полезен как часть схемы отмены. Он может не удалить задачи, преобразованные в другие формы перед помещением во внутреннюю очередь. Например, задача, добавленная с помощью submit, может быть преобразована в форму, сохраняющую состояние Future. Однако в таких случаях для удаления отмененных Future можно использовать метод purge().

Параметры:
task — удаляемая задача
Возвращает:
true, если задача была удалена

purge

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

getPoolSize

public int getPoolSize()
Возвращает текущее количество потоков в пуле.
Возвращает:
количество потоков

getActiveCount

public int getActiveCount()
Возвращает приблизительное количество потоков, активно выполняющих задачи.
Возвращает:
количество потоков

getLargestPoolSize

public int getLargestPoolSize()
Возвращает наибольшее количество потоков, одновременно находившихся в пуле.
Возвращает:
количество потоков

getTaskCount

public long getTaskCount()
Возвращает приблизительное общее количество задач, когда-либо запланированных к выполнению. Поскольку состояния задач и потоков могут динамически изменяться в ходе вычислений, возвращаемое значение является лишь приблизительным.
Возвращает:
количество задач

getCompletedTaskCount

public long getCompletedTaskCount()
Возвращает приблизительное общее количество задач, выполнение которых завершилось. Поскольку состояния задач и потоков могут динамически изменяться в ходе вычислений, возвращаемое значение является лишь приблизительным, но никогда не уменьшается при последовательных вызовах.
Возвращает:
количество задач

toString

public String toString()
Возвращает строку, идентифицирующую этот пул и его состояние, включая сведения о состоянии выполнения и приблизительном количестве рабочих потоков и задач.
Переопределяет:
toString в классе Object
Возвращает:
строку, идентифицирующую этот пул и его состояние

beforeExecute

protected void beforeExecute(Thread t, Runnable r)
Метод, вызываемый перед выполнением указанного Runnable в указанном потоке. Этот метод вызывается потоком t, который будет выполнять задачу r, и может использоваться для повторной инициализации ThreadLocal или ведения журнала.

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

Параметры:
t — поток, который будет выполнять задачу r
r — задача, которая будет выполнена

afterExecute

protected void afterExecute(Runnable r, Throwable t)
Метод, вызываемый по завершении выполнения указанного Runnable. Этот метод вызывается потоком, выполнявшим задачу. Если Throwable не равен null, это неперехваченное исключение RuntimeException или Error, приведшее к неожиданному прекращению выполнения.

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

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

class ExtendedExecutor extends ThreadPoolExecutor {
  // ...
  protected void afterExecute(Runnable r, Throwable t) {
    super.afterExecute(r, t);
    if (t == null
        && r instanceof Future<?>
        && ((Future<?>)r).isDone()) {
      try {
        Object result = ((Future<?>) r).get();
      } catch (CancellationException ce) {
        t = ce;
      } catch (ExecutionException ee) {
        t = ee.getCause();
      } catch (InterruptedException ie) {
        // ignore/reset
        Thread.currentThread().interrupt();
      }
    }
    if (t != null)
      System.out.println(t);
  }
}
Параметры:
r — завершивший выполнение объект runnable
t — исключение, вызвавшее завершение, или null, если выполнение завершилось нормально

terminated

protected void terminated()
Метод, вызываемый после завершения работы исполнителя. Реализация по умолчанию ничего не делает. Примечание. Чтобы корректно выстраивать несколько переопределений, подклассам, как правило, следует вызывать super.terminated внутри этого метода.

Сообщить об ошибке или предложить улучшение
Дополнительные справочные материалы по 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