Класс ScheduledThreadPoolExecutor

public class ScheduledThreadPoolExecutor
extends ThreadPoolExecutor
implements ScheduledExecutorService

A ThreadPoolExecutor that can additionally schedule commands to run after a given delay, or to execute periodically. This class is preferable to Timer when multiple worker threads are needed, or when the additional flexibility or capabilities of ThreadPoolExecutor (which this class extends) are required.

Delayed tasks execute no sooner than they are enabled, but without any real-time guarantees about when, after they are enabled, they will commence. Tasks scheduled for exactly the same execution time are enabled in first-in-first-out (FIFO) order of submission.

When a submitted task is cancelled before it is run, execution is suppressed. By default, such a cancelled task is not automatically removed from the work queue until its delay elapses. While this enables further inspection and monitoring, it may also cause unbounded retention of cancelled tasks. To avoid this, set setRemoveOnCancelPolicy(boolean) to true, which causes tasks to be immediately removed from the work queue at time of cancellation.

Successive executions of a task scheduled via scheduleAtFixedRate or scheduleWithFixedDelay do not overlap. While different executions may be performed by different threads, the effects of prior executions happen-before those of subsequent ones.

While this class inherits from ThreadPoolExecutor, a few of the inherited tuning methods are not useful for it. In particular, because it acts as a fixed-sized pool using corePoolSize threads and an unbounded queue, adjustments to maximumPoolSize have no useful effect. Additionally, it is almost never a good idea to set corePoolSize to zero or use allowCoreThreadTimeOut because this may leave the pool without threads to handle tasks once they become eligible to run.

Extension notes: This class overrides the execute and submit methods to generate internal ScheduledFuture objects to control per-task delays and scheduling. To preserve functionality, any further overrides of these methods in subclasses must invoke superclass versions, which effectively disables additional task customization. However, this class provides alternative protected extension method decorateTask (one version each for Runnable and Callable) that can be used to customize the concrete task types used to execute commands entered via execute, submit, schedule, scheduleAtFixedRate, and scheduleWithFixedDelay. By default, a ScheduledThreadPoolExecutor uses a task type extending FutureTask. However, this may be modified or replaced using subclasses of the form:

public class CustomScheduledExecutor extends ScheduledThreadPoolExecutor {

   static class CustomTask<V> implements RunnableScheduledFuture<V> { ... }

   protected <V> RunnableScheduledFuture<V> decorateTask(
                Runnable r, RunnableScheduledFuture<V> task) {
       return new CustomTask<V>(r, task);
   }

   protected <V> RunnableScheduledFuture<V> decorateTask(
                Callable<V> c, RunnableScheduledFuture<V> task) {
       return new CustomTask<V>(c, task);
   }
   // ... add constructors, etc.
 }

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

ScheduledThreadPoolExecutor

public ScheduledThreadPoolExecutor(int corePoolSize)

Создает новый ScheduledThreadPoolExecutor с заданным размером пула основных потоков.

Параметры:

corePoolSize - количество потоков, которые необходимо хранить в пуле, даже если они неактивны, если только не установлен allowCoreThreadTimeOut

Исключения:

IllegalArgumentException - если corePoolSize < 0

ScheduledThreadPoolExecutor

public ScheduledThreadPoolExecutor(int corePoolSize,
                                   ThreadFactory threadFactory)

Создает новый ScheduledThreadPoolExecutor с заданными начальными параметрами.

Параметры:

corePoolSize - количество потоков, которые необходимо хранить в пуле, даже если они неактивны, если только не установлен allowCoreThreadTimeOut

threadFactory - фабрика, используемая исполнителем при создании нового потока

Исключения:

IllegalArgumentException - если corePoolSize < 0

NullPointerException - если threadFactory равно null

ScheduledThreadPoolExecutor

public ScheduledThreadPoolExecutor(int corePoolSize,
                                   RejectedExecutionHandler handler)

Создает новый ScheduledThreadPoolExecutor с заданными начальными параметрами.

Параметры:

corePoolSize - количество потоков, которые необходимо хранить в пуле, даже если они неактивны, если только не установлен allowCoreThreadTimeOut

handler - обработчик, используемый при блокировке выполнения из-за достижения ограничений потоков и емкости очереди

Исключения:

IllegalArgumentException - если corePoolSize < 0

NullPointerException - если handler равно null

ScheduledThreadPoolExecutor

public ScheduledThreadPoolExecutor(int corePoolSize,
                                   ThreadFactory threadFactory,
                                   RejectedExecutionHandler handler)

Создает новый ScheduledThreadPoolExecutor с заданными начальными параметрами.

Параметры:

corePoolSize - количество потоков, которые необходимо хранить в пуле, даже если они неактивны, если только не установлен allowCoreThreadTimeOut

threadFactory - фабрика, используемая исполнителем при создании нового потока

handler - обработчик, используемый при блокировке выполнения из-за достижения ограничений потоков и емкости очереди

Исключения:

IllegalArgumentException - если corePoolSize < 0

NullPointerException - если threadFactory или handler равно null

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

decorateTask

protected <V> RunnableScheduledFuture<V> decorateTask(Runnable runnable,
                                                      RunnableScheduledFuture<V> task)

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

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

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

Параметры:

runnable - переданный выполняемый объект

task - задача, созданная для выполнения выполняемого объекта

Возвращает:

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

С версии:

1.6

decorateTask

protected <V> RunnableScheduledFuture<V> decorateTask(Callable<V> callable,
                                                      RunnableScheduledFuture<V> task)

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

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

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

Параметры:

callable - переданный вызываемый объект

task - задача, созданная для выполнения вызываемого объекта

Возвращает:

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

С версии:

1.6

schedule

public ScheduledFuture<?> schedule(Runnable command,
                                   long delay,
                                   TimeUnit unit)

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

Создает и выполняет одноразовое действие, которое становится активным после заданной задержки.

Указано в:

schedule в интерфейсе ScheduledExecutorService

Параметры:

command - задача для выполнения

delay - время задержки выполнения с текущего момента

unit - единица времени параметра задержки

Возвращает:

ScheduledFuture, представляющий незавершенное выполнение задачи, и чей метод get() вернет null по завершении

Исключения:

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

NullPointerException - если команда равна null

schedule

public <V> ScheduledFuture<V> schedule(Callable<V> callable,
                                       long delay,
                                       TimeUnit unit)

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

Создает и выполняет ScheduledFuture, который становится активным после заданной задержки.

Указано в:

schedule в интерфейсе ScheduledExecutorService

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

V - тип результата вызываемого объекта

Параметры:

callable - функция для выполнения

delay - время задержки выполнения с текущего момента

unit - единица времени параметра задержки

Возвращает:

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

Исключения:

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

NullPointerException - если вызываемый объект равен null

scheduleAtFixedRate

public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
                                              long initialDelay,
                                              long period,
                                              TimeUnit unit)

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

Создает и выполняет периодическое действие, которое становится активным впервые после заданной начальной задержки, а затем с заданным периодом; то есть выполнение начнется через initialDelay затем initialDelay+period, затем initialDelay + 2 * period, и так далее. Если при выполнении задачи возникает исключение, последующие выполнения подавляются. В противном случае задача завершится только путем отмены или завершения работы исполнителя. Если выполнение этой задачи занимает больше времени, чем ее период, последующие выполнения могут начаться с опозданием, но не будут выполняться одновременно.

Указано в:

scheduleAtFixedRate в интерфейсе ScheduledExecutorService

Параметры:

command - задача для выполнения

initialDelay - время задержки первого выполнения

period - период между последовательными выполнениями

unit - единица времени параметров initialDelay и period

Возвращает:

ScheduledFuture, представляющий незавершенное выполнение задачи, и чей метод get() выбросит исключение при отмене

Исключения:

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

NullPointerException - если команда равна null

IllegalArgumentException - если период меньше или равен нулю

scheduleWithFixedDelay

public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
                                                 long initialDelay,
                                                 long delay,
                                                 TimeUnit unit)

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

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

Указано в:

scheduleWithFixedDelay в интерфейсе ScheduledExecutorService

Параметры:

command - задача для выполнения

initialDelay - время задержки первого выполнения

delay - задержка между завершением одного выполнения и началом следующего

unit - единица времени параметров initialDelay и delay

Возвращает:

ScheduledFuture, представляющий незавершенное выполнение задачи, и чей метод get() выбросит исключение при отмене

Исключения:

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

NullPointerException - если команда равна null

IllegalArgumentException - если задержка меньше или равна нулю

execute

public void execute(Runnable command)

Указано в:

execute в интерфейсе Executor

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

execute в классе ThreadPoolExecutor

Параметры:

command - задача для выполнения

Исключения:

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

NullPointerException - если command равно null

submit

public Future<?> submit(Runnable task)

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

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

Указано в:

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

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

submit в классе AbstractExecutorService

Параметры:

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

Возвращает:

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

Исключения:

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

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

submit

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

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

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

Указано в:

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

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

submit в классе AbstractExecutorService

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

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

Параметры:

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

result - возвращаемый результат

Возвращает:

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

Исключение:

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

NullPointerException - если задача null

submit

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

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

Указано в:

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

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

submit в классе AbstractExecutorService

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

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

Параметры:

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

Возвращает:

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

Исключение:

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

NullPointerException - если задача null

setContinueExistingPeriodicTasksAfterShutdownPolicy

public void setContinueExistingPeriodicTasksAfterShutdownPolicy(boolean value)

Устанавливает политику продолжения выполнения существующих периодических задач даже когда этот Executor уже shutdown. В этом случае эти задачи завершатся только при shutdownNow или после установки политики на false при уже завершённом состоянии. Значение по умолчанию false.

Параметры:

value - если true, продолжать после завершения, иначе нет

См. также:

getContinueExistingPeriodicTasksAfterShutdownPolicy()

getContinueExistingPeriodicTasksAfterShutdownPolicy

public boolean getContinueExistingPeriodicTasksAfterShutdownPolicy()

Получает политику продолжения выполнения существующих периодических задач даже когда этот Executor уже shutdown. В этом случае эти задачи завершатся только при shutdownNow или после установки политики на false при уже завершённом состоянии. Значение по умолчанию false.

Возвращает:

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

См. также:

setContinueExistingPeriodicTasksAfterShutdownPolicy(boolean)

setExecuteExistingDelayedTasksAfterShutdownPolicy

public void setExecuteExistingDelayedTasksAfterShutdownPolicy(boolean value)

Устанавливает политику выполнения существующих отложенных задач даже когда этот Executor уже shutdown. В этом случае эти задачи завершатся только при shutdownNow, или после установки политики на false при уже завершённом состоянии. Значение по умолчанию true.

Параметры:

value - если true, выполнять после завершения, иначе нет

См. также:

getExecuteExistingDelayedTasksAfterShutdownPolicy()

getExecuteExistingDelayedTasksAfterShutdownPolicy

public boolean getExecuteExistingDelayedTasksAfterShutdownPolicy()

Получает политику выполнения существующих отложенных задач даже когда этот Executor уже shutdown. В этом случае эти задачи завершатся только при shutdownNow, или после установки политики на false при уже завершённом состоянии. Значение по умолчанию true.

Возвращает:

true если выполнять после завершения

См. также:

setExecuteExistingDelayedTasksAfterShutdownPolicy(boolean)

setRemoveOnCancelPolicy

public void setRemoveOnCancelPolicy(boolean value)

Устанавливает политику, определяющую, должны ли отменённые задачи немедленно удаляться из очереди задач при отмене. Значение по умолчанию false.

Параметры:

value - если true, удалять при отмене, иначе нет

С тех пор:

1.7

См. также:

getRemoveOnCancelPolicy()

getRemoveOnCancelPolicy

public boolean getRemoveOnCancelPolicy()

Получает политику, определяющую, должны ли отменённые задачи немедленно удаляться из очереди задач при отмене. Значение по умолчанию false.

Возвращает:

true если отменённые задачи сразу удаляются из очереди

С тех пор:

1.7

См. также:

setRemoveOnCancelPolicy(boolean)

shutdown

public void shutdown()

Указано в:

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

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

shutdown в классе ThreadPoolExecutor

Исключение:

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

shutdownNow

public List<Runnable> shutdownNow()

Указано в:

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

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

shutdownNow в классе ThreadPoolExecutor

Возвращает:

список задач, которые никогда не начинали выполнение. Каждый элемент этого списка — ScheduledFuture, включая те задачи, которые отправлены с помощью execute, которые в целях планирования используются в качестве основы для ScheduledFuture с нулевой задержкой.

Исключение:

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

getQueue

public BlockingQueue<Runnable> getQueue()

Возвращает очередь задач, используемую этим исполнителем. Каждый элемент этой очереди — ScheduledFuture, включая те задачи, которые отправлены с помощью execute, которые в целях планирования используются в качестве основы для ScheduledFuture. Итерация по этой очереди не гарантирует прохождение задач в порядке их выполнения.

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

getQueue в классе ThreadPoolExecutor

Возвращает:

очередь задач