edu.emory.mathcs.backport.java.util.concurrent

Class 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 java.util.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. If ScheduledThreadPoolExecutor is set {@code true} cancelled tasks are automatically removed from the work queue.

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 {@code corePoolSize} threads and an unbounded queue, adjustments to {@code maximumPoolSize} have no useful effect. Additionally, it is almost never a good idea to set {@code corePoolSize} to zero or use {@code 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 {@code decorateTask} (one version each for {@code Runnable} and {@code Callable}) that can be used to customize the concrete task types used to execute commands entered via {@code execute}, {@code submit}, {@code schedule}, {@code scheduleAtFixedRate}, and {@code scheduleWithFixedDelay}. By default, a {@code ScheduledThreadPoolExecutor} uses a task type extending FutureTask. However, this may be modified or replaced using subclasses of the form:

 {@code  public class CustomScheduledExecutor extends ScheduledThreadPoolExecutor {

   static class CustomTask implements RunnableScheduledFuture { ... }

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

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

Since: 1.5

Author: Doug Lea

Constructor Summary
ScheduledThreadPoolExecutor(int corePoolSize)
Creates a new {@code ScheduledThreadPoolExecutor} with the given core pool size.
ScheduledThreadPoolExecutor(int corePoolSize, ThreadFactory threadFactory)
Creates a new {@code ScheduledThreadPoolExecutor} with the given initial parameters.
ScheduledThreadPoolExecutor(int corePoolSize, RejectedExecutionHandler handler)
Creates a new ScheduledThreadPoolExecutor with the given initial parameters.
ScheduledThreadPoolExecutor(int corePoolSize, ThreadFactory threadFactory, RejectedExecutionHandler handler)
Creates a new ScheduledThreadPoolExecutor with the given initial parameters.
Method Summary
protected RunnableScheduledFuturedecorateTask(Runnable runnable, RunnableScheduledFuture task)
Modifies or replaces the task used to execute a runnable.
protected RunnableScheduledFuturedecorateTask(Callable callable, RunnableScheduledFuture task)
Modifies or replaces the task used to execute a callable.
voidexecute(Runnable command)
Executes {@code command} with zero required delay.
booleangetContinueExistingPeriodicTasksAfterShutdownPolicy()
Gets the policy on whether to continue executing existing periodic tasks even when this executor has been {@code shutdown}.
booleangetExecuteExistingDelayedTasksAfterShutdownPolicy()
Gets the policy on whether to execute existing delayed tasks even when this executor has been {@code shutdown}.
BlockingQueuegetQueue()
Returns the task queue used by this executor.
booleangetRemoveOnCancelPolicy()
Gets the policy on whether to cancellation of a a task should remove it from the work queue.
ScheduledFutureschedule(Runnable command, long delay, TimeUnit unit)
ScheduledFutureschedule(Callable callable, long delay, TimeUnit unit)
ScheduledFuturescheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)
ScheduledFuturescheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)
voidsetContinueExistingPeriodicTasksAfterShutdownPolicy(boolean value)
Sets the policy on whether to continue executing existing periodic tasks even when this executor has been {@code shutdown}.
voidsetExecuteExistingDelayedTasksAfterShutdownPolicy(boolean value)
Sets the policy on whether to execute existing delayed tasks even when this executor has been {@code shutdown}.
voidsetRemoveOnCancelPolicy(boolean value)
Sets the policy on whether to cancellation of a a task should remove it from the work queue.
voidshutdown()
Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted.
ListshutdownNow()
Attempts to stop all actively executing tasks, halts the processing of waiting tasks, and returns a list of the tasks that were awaiting execution.
Futuresubmit(Runnable task)
Futuresubmit(Runnable task, Object result)
Futuresubmit(Callable task)

Constructor Detail

ScheduledThreadPoolExecutor

public ScheduledThreadPoolExecutor(int corePoolSize)
Creates a new {@code ScheduledThreadPoolExecutor} with the given core pool size.

Parameters: corePoolSize the number of threads to keep in the pool, even if they are idle, unless {@code allowCoreThreadTimeOut} is set

Throws: IllegalArgumentException if {@code corePoolSize < 0}

ScheduledThreadPoolExecutor

public ScheduledThreadPoolExecutor(int corePoolSize, ThreadFactory threadFactory)
Creates a new {@code ScheduledThreadPoolExecutor} with the given initial parameters.

Parameters: corePoolSize the number of threads to keep in the pool, even if they are idle, unless {@code allowCoreThreadTimeOut} is set threadFactory the factory to use when the executor creates a new thread

Throws: IllegalArgumentException if {@code corePoolSize < 0} NullPointerException if {@code threadFactory} is null

ScheduledThreadPoolExecutor

public ScheduledThreadPoolExecutor(int corePoolSize, RejectedExecutionHandler handler)
Creates a new ScheduledThreadPoolExecutor with the given initial parameters.

Parameters: corePoolSize the number of threads to keep in the pool, even if they are idle, unless {@code allowCoreThreadTimeOut} is set handler the handler to use when execution is blocked because the thread bounds and queue capacities are reached

Throws: IllegalArgumentException if {@code corePoolSize < 0} NullPointerException if {@code handler} is null

ScheduledThreadPoolExecutor

public ScheduledThreadPoolExecutor(int corePoolSize, ThreadFactory threadFactory, RejectedExecutionHandler handler)
Creates a new ScheduledThreadPoolExecutor with the given initial parameters.

Parameters: corePoolSize the number of threads to keep in the pool, even if they are idle, unless {@code allowCoreThreadTimeOut} is set threadFactory the factory to use when the executor creates a new thread handler the handler to use when execution is blocked because the thread bounds and queue capacities are reached

Throws: IllegalArgumentException if {@code corePoolSize < 0} NullPointerException if {@code threadFactory} or {@code handler} is null

Method Detail

decorateTask

protected RunnableScheduledFuture decorateTask(Runnable runnable, RunnableScheduledFuture task)
Modifies or replaces the task used to execute a runnable. This method can be used to override the concrete class used for managing internal tasks. The default implementation simply returns the given task.

Parameters: runnable the submitted Runnable task the task created to execute the runnable

Returns: a task that can execute the runnable

Since: 1.6

decorateTask

protected RunnableScheduledFuture decorateTask(Callable callable, RunnableScheduledFuture task)
Modifies or replaces the task used to execute a callable. This method can be used to override the concrete class used for managing internal tasks. The default implementation simply returns the given task.

Parameters: callable the submitted Callable task the task created to execute the callable

Returns: a task that can execute the callable

Since: 1.6

execute

public void execute(Runnable command)
Executes {@code command} with zero required delay. This has effect equivalent to schedule(command, 0, anyUnit). Note that inspections of the queue and of the list returned by {@code shutdownNow} will access the zero-delayed ScheduledFuture, not the {@code command} itself.

A consequence of the use of {@code ScheduledFuture} objects is that afterExecute is always called with a null second {@code Throwable} argument, even if the {@code command} terminated abruptly. Instead, the {@code Throwable} thrown by such a task can be obtained via Future.

Throws: RejectedExecutionException at discretion of {@code RejectedExecutionHandler}, if the task cannot be accepted for execution because the executor has been shut down NullPointerException {@inheritDoc }

getContinueExistingPeriodicTasksAfterShutdownPolicy

public boolean getContinueExistingPeriodicTasksAfterShutdownPolicy()
Gets the policy on whether to continue executing existing periodic tasks even when this executor has been {@code shutdown}. In this case, these tasks will only terminate upon {@code shutdownNow} or after setting the policy to {@code false} when already shutdown. This value is by default {@code false}.

Returns: {@code true} if will continue after shutdown

See Also: ScheduledThreadPoolExecutor

getExecuteExistingDelayedTasksAfterShutdownPolicy

public boolean getExecuteExistingDelayedTasksAfterShutdownPolicy()
Gets the policy on whether to execute existing delayed tasks even when this executor has been {@code shutdown}. In this case, these tasks will only terminate upon {@code shutdownNow}, or after setting the policy to {@code false} when already shutdown. This value is by default {@code true}.

Returns: {@code true} if will execute after shutdown

See Also: ScheduledThreadPoolExecutor

getQueue

public BlockingQueue getQueue()
Returns the task queue used by this executor. Each element of this queue is a ScheduledFuture, including those tasks submitted using {@code execute} which are for scheduling purposes used as the basis of a zero-delay {@code ScheduledFuture}. Iteration over this queue is not guaranteed to traverse tasks in the order in which they will execute.

Returns: the task queue

getRemoveOnCancelPolicy

public boolean getRemoveOnCancelPolicy()
Gets the policy on whether to cancellation of a a task should remove it from the work queue. This value is by default {@code false}.

Returns: {@code true} if cancelled tasks are removed from the queue.

Since: 1.7

See Also: ScheduledThreadPoolExecutor

schedule

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

Throws: RejectedExecutionException {@inheritDoc } NullPointerException {@inheritDoc }

schedule

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

Throws: RejectedExecutionException {@inheritDoc } NullPointerException {@inheritDoc }

scheduleAtFixedRate

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

Throws: RejectedExecutionException {@inheritDoc } NullPointerException {@inheritDoc } IllegalArgumentException {@inheritDoc }

scheduleWithFixedDelay

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

Throws: RejectedExecutionException {@inheritDoc } NullPointerException {@inheritDoc } IllegalArgumentException {@inheritDoc }

setContinueExistingPeriodicTasksAfterShutdownPolicy

public void setContinueExistingPeriodicTasksAfterShutdownPolicy(boolean value)
Sets the policy on whether to continue executing existing periodic tasks even when this executor has been {@code shutdown}. In this case, these tasks will only terminate upon {@code shutdownNow} or after setting the policy to {@code false} when already shutdown. This value is by default {@code false}.

Parameters: value if {@code true}, continue after shutdown, else don't.

See Also: ScheduledThreadPoolExecutor

setExecuteExistingDelayedTasksAfterShutdownPolicy

public void setExecuteExistingDelayedTasksAfterShutdownPolicy(boolean value)
Sets the policy on whether to execute existing delayed tasks even when this executor has been {@code shutdown}. In this case, these tasks will only terminate upon {@code shutdownNow}, or after setting the policy to {@code false} when already shutdown. This value is by default {@code true}.

Parameters: value if {@code true}, execute after shutdown, else don't.

See Also: ScheduledThreadPoolExecutor

setRemoveOnCancelPolicy

public void setRemoveOnCancelPolicy(boolean value)
Sets the policy on whether to cancellation of a a task should remove it from the work queue. This value is by default {@code false}.

Parameters: value if {@code true}, remove on cancellation, else don't.

Since: 1.7

See Also: ScheduledThreadPoolExecutor

shutdown

public void shutdown()
Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted. If the {@code ExecuteExistingDelayedTasksAfterShutdownPolicy} has been set {@code false}, existing delayed tasks whose delays have not yet elapsed are cancelled. And unless the {@code ContinueExistingPeriodicTasksAfterShutdownPolicy} has been set {@code true}, future executions of existing periodic tasks will be cancelled.

Throws: SecurityException {@inheritDoc }

shutdownNow

public List shutdownNow()
Attempts to stop all actively executing tasks, halts the processing of waiting tasks, and returns a list of the tasks that were awaiting execution.

There are no guarantees beyond best-effort attempts to stop processing actively executing tasks. This implementation cancels tasks via Thread#interrupt, so any task that fails to respond to interrupts may never terminate.

Returns: list of tasks that never commenced execution. Each element of this list is a ScheduledFuture, including those tasks submitted using {@code execute}, which are for scheduling purposes used as the basis of a zero-delay {@code ScheduledFuture}.

Throws: SecurityException {@inheritDoc }

submit

public Future submit(Runnable task)

Throws: RejectedExecutionException {@inheritDoc } NullPointerException {@inheritDoc }

submit

public Future submit(Runnable task, Object result)

Throws: RejectedExecutionException {@inheritDoc } NullPointerException {@inheritDoc }

submit

public Future submit(Callable task)

Throws: RejectedExecutionException {@inheritDoc } NullPointerException {@inheritDoc }