Spec-Zone.ru › OpenJDK 25

Класс 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 не удаётся создать поток по запросу и метод newThread возвращает null, исполнитель продолжит работу, но может оказаться неспособным выполнять какие-либо задачи.
Время ожидания перед завершением
Если в пуле сейчас больше потоков, чем задано параметром corePoolSize, избыточные потоки будут завершены, если они простаивали дольше, чем указано параметром keepAliveTime (см. getKeepAliveTime(TimeUnit)). Это позволяет сократить потребление ресурсов, когда пул не используется активно. Если позднее нагрузка на пул возрастёт, будут созданы новые потоки. Этот параметр также можно динамически изменять с помощью метода setKeepAliveTime(long, TimeUnit). Значение Long.MAX_VALUE TimeUnit.NANOSECONDS фактически отключает завершение простаивающих потоков до остановки пула. По умолчанию политика ожидания перед завершением применяется только тогда, когда потоков больше, чем задано параметром corePoolSize, но метод allowCoreThreadTimeOut(boolean) позволяет применять эту политику также к основным потокам, если значение keepAliveTime не равно нулю.
Постановка в очередь
Для передачи и хранения отправленных задач можно использовать любую BlockingQueue. Использование этой очереди влияет на размер пула:
  • Если работает меньше потоков, чем задано параметром corePoolSize, исполнитель всегда предпочитает добавить новый поток, а не помещать задачу в очередь.
  • Если работает столько же потоков или больше, чем задано параметром corePoolSize, исполнитель всегда предпочитает поместить запрос в очередь, а не добавлять новый поток.
  • Если запрос нельзя поместить в очередь, создаётся новый поток, если это не приведёт к превышению maximumPoolSize; в противном случае задача будет отклонена.
Существует три основные стратегии постановки в очередь:
  1. Непосредственная передача. Хорошим вариантом очереди работ по умолчанию является SynchronousQueue, которая передаёт задачи потокам, не сохраняя их. В этом случае попытка поместить задачу в очередь завершится неудачей, если немедленно доступных для её выполнения потоков нет, поэтому будет создан новый поток. Эта политика предотвращает взаимные блокировки при обработке наборов запросов, которые могут иметь внутренние зависимости. Для непосредственной передачи обычно требуется неограниченное значение maximumPoolSize, чтобы избежать отклонения новых отправленных задач. Это, в свою очередь, допускает неограниченный рост числа потоков, если команды продолжают поступать в среднем быстрее, чем их можно обрабатывать.
  2. Неограниченные очереди. Использование неограниченной очереди (например, LinkedBlockingQueue без заранее заданной ёмкости) приводит к тому, что новые задачи ожидают в очереди, когда все потоки corePoolSize заняты. Таким образом, число созданных потоков никогда не превысит corePoolSize. (Поэтому значение maximumPoolSize не будет иметь никакого эффекта.) Этот вариант может быть уместен, если каждая задача полностью независима от остальных и задачи не могут влиять на выполнение друг друга, например на сервере веб-страниц. Такой способ постановки в очередь позволяет сглаживать кратковременные всплески запросов, но допускает неограниченный рост очереди работ, если команды продолжают поступать в среднем быстрее, чем их можно обрабатывать.
  3. Ограниченные очереди. Ограниченная очередь (например, ArrayBlockingQueue) помогает предотвратить исчерпание ресурсов при использовании конечного значения maximumPoolSize, но её настройка и управление могут быть сложнее. Размер очереди и максимальный размер пула можно подбирать совместно: большие очереди и небольшие пулы сводят к минимуму использование процессора и ресурсов ОС, а также накладные расходы на переключение контекста, но могут привести к искусственно низкой пропускной способности. Если задачи часто блокируются (например, при интенсивном вводе-выводе), система может выделить время для большего числа потоков, чем вы обычно допускаете. Использование небольших очередей, как правило, требует увеличения размера пула, что позволяет эффективнее загружать процессоры, но может привести к неприемлемым накладным расходам на планирование и, как следствие, снизить пропускную способность.
Отклонённые задачи
Новые задачи, отправленные методом execute(Runnable), будут отклонены, если исполнитель остановлен, а также если исполнитель использует конечные ограничения как на максимальное число потоков, так и на ёмкость очереди работ и эти ограничения достигнуты. В любом из этих случаев метод 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() можно переопределить для выполнения специальных действий после полной остановки исполнителя.

Если методы-перехватчики, методы обратного вызова или методы 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)
Выполняет заданную задачу в будущем.
protected void finalize()
Устарело, планируется удаление: этот элемент API может быть удалён в будущей версии.
Финализация признана устаревшей и планируется к удалению.
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()
Метод, вызываемый после завершения работы исполнителя.
String toString()
Возвращает строку, идентифицирующую этот пул и его состояние, в том числе сведения о состоянии выполнения и примерном количестве рабочих потоков и задач.

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

invokeAll, invokeAll, invokeAny, invokeAny, newTaskFor, newTaskFor, submit, submit, submit

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

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

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

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 — если во время ожидания произошло прерывание

finalize

@Deprecated(since="9", forRemoval=true) protected void finalize()
Устарело и будет удалено: этот элемент API подлежит удалению в будущей версии.
Метод финализации объявлен устаревшим и будет удален. Справочную информацию и сведения о вариантах миграции см. в разделе Object.finalize().
Описание скопировано из класса: Object
Вызывается сборщиком мусора для объекта, когда тот определяет, что на объект больше нет ссылок. Подкласс переопределяет метод finalize, чтобы освободить системные ресурсы или выполнить другую очистку.

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

Общее правило для finalize состоит в том, что этот метод вызывается тогда и только тогда, когда виртуальная машина Java определит, что больше нет способа получить доступ к данному объекту из любого еще не завершившего работу потока, кроме как в результате действия, выполненного при финализации другого объекта или класса, готового к финализации. Метод finalize может выполнять любые действия, в том числе снова сделать объект доступным для других потоков; однако обычное назначение finalize — выполнить очистку до того, как объект будет окончательно удален. Например, метод finalize объекта, представляющего подключение ввода-вывода, может явно выполнить операции ввода-вывода, чтобы разорвать подключение до окончательного удаления объекта.

Метод finalize класса Object не выполняет никаких специальных действий и просто нормально возвращает управление. Подклассы Object могут переопределять это определение.

Язык программирования Java не гарантирует, какой поток вызовет метод finalize для того или иного объекта. Однако гарантируется, что поток, вызывающий finalize, не будет удерживать никаких видимых пользователю блокировок синхронизации в момент вызова finalize. Если метод finalize выбрасывает неперехваченное исключение, оно игнорируется, а финализация этого объекта прекращается.

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

Виртуальная машина Java никогда не вызывает метод finalize для одного и того же объекта более одного раза.

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

Переопределяет:
finalize в классе Object
Примечание по реализации:
В предыдущих версиях этого класса метод finalize завершал работу исполнителя, но в текущей версии finalize ничего не делает.
См. также:
  • WeakReference
  • PhantomReference

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, если этот пул допускает завершение базовых потоков по тайм-ауту при отсутствии задач в течение времени ожидания завершения; при поступлении новых задач такие потоки при необходимости заменяются. Если возвращается true, политика времени ожидания завершения для небазовых потоков также применяется к базовым. Если возвращается false (значение по умолчанию), базовые потоки никогда не завершаются из-за отсутствия новых задач.
Возвращает:
true, если базовым потокам разрешено завершаться по тайм-ауту; иначе false
Начиная с версии:
1.6

allowCoreThreadTimeOut

public void allowCoreThreadTimeOut(boolean value)
Задает политику, определяющую, могут ли базовые потоки завершаться по тайм-ауту при отсутствии задач в течение времени ожидания завершения; при поступлении новых задач такие потоки при необходимости заменяются. Если задано 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()
Метод, вызываемый при завершении работы Executor. Реализация по умолчанию ничего не делает. Примечание: чтобы корректно организовать несколько переопределений, подклассам обычно следует вызывать super.terminated внутри этого метода.

Сообщить об ошибке или предложить улучшение
Дополнительные справочные материалы по API и документацию для разработчиков см. в разделе Документация Java SE, содержащем более подробные описания для разработчиков, концептуальные обзоры, определения терминов, обходные решения и работающие примеры кода. Другие версии.
Java является товарным знаком или зарегистрированным товарным знаком Oracle и/или ее аффилированных лиц в США и других странах.
Авторские права © 1993, 2025, 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.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/ThreadPoolExecutor.html

Spec-Zone.ru

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