FileDocCategorySizeDatePackage
ScheduledThreadPoolExecutor.javaAPI DocJava SE 6 API24387Tue Jun 10 00:25:56 BST 2008java.util.concurrent

ScheduledThreadPoolExecutor

public class ScheduledThreadPoolExecutor extends ThreadPoolExecutor implements ScheduledExecutorService
A {@link ThreadPoolExecutor} that can additionally schedule commands to run after a given delay, or to execute periodically. This class is preferable to {@link java.util.Timer} when multiple worker threads are needed, or when the additional flexibility or capabilities of {@link 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.

While this class inherits from {@link 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.

Extension notes: This class overrides {@link AbstractExecutorService} submit methods to generate internal 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 {@link 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.
}
since
1.5
author
Doug Lea

Fields Summary
private volatile boolean
continueExistingPeriodicTasksAfterShutdown
False if should cancel/suppress periodic tasks on shutdown.
private volatile boolean
executeExistingDelayedTasksAfterShutdown
False if should cancel non-periodic tasks on shutdown.
private static final AtomicLong
sequencer
Sequence number to break scheduling ties, and in turn to guarantee FIFO order among tied entries.
private static final long
NANO_ORIGIN
Base of nanosecond timings, to avoid wrapping
Constructors Summary
public ScheduledThreadPoolExecutor(int corePoolSize, ThreadFactory threadFactory, RejectedExecutionHandler handler)
Creates a new ScheduledThreadPoolExecutor with the given initial parameters.

param
corePoolSize the number of threads to keep in the pool, even if they are idle
param
threadFactory the factory to use when the executor creates a new thread
param
handler the handler to use when execution is blocked because the thread bounds and queue capacities are reached.
throws
IllegalArgumentException if corePoolSize < 0
throws
NullPointerException if threadFactory or handler is null

        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue(), threadFactory, handler);
    
public ScheduledThreadPoolExecutor(int corePoolSize)
Creates a new ScheduledThreadPoolExecutor with the given core pool size.

param
corePoolSize the number of threads to keep in the pool, even if they are idle
throws
IllegalArgumentException if corePoolSize < 0

        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue());
    
public ScheduledThreadPoolExecutor(int corePoolSize, ThreadFactory threadFactory)
Creates a new ScheduledThreadPoolExecutor with the given initial parameters.

param
corePoolSize the number of threads to keep in the pool, even if they are idle
param
threadFactory the factory to use when the executor creates a new thread
throws
IllegalArgumentException if corePoolSize < 0
throws
NullPointerException if threadFactory is null

        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue(), threadFactory);
    
public ScheduledThreadPoolExecutor(int corePoolSize, RejectedExecutionHandler handler)
Creates a new ScheduledThreadPoolExecutor with the given initial parameters.

param
corePoolSize the number of threads to keep in the pool, even if they are idle
param
handler the handler to use when execution is blocked because the thread bounds and queue capacities are reached
throws
IllegalArgumentException if corePoolSize < 0
throws
NullPointerException if handler is null

        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue(), handler);
    
Methods Summary
private voidcancelUnwantedTasks()
Cancels and clears the queue of all tasks that should not be run due to shutdown policy.

        boolean keepDelayed = getExecuteExistingDelayedTasksAfterShutdownPolicy();
        boolean keepPeriodic = getContinueExistingPeriodicTasksAfterShutdownPolicy();
        if (!keepDelayed && !keepPeriodic)
            super.getQueue().clear();
        else if (keepDelayed || keepPeriodic) {
            Object[] entries = super.getQueue().toArray();
            for (int i = 0; i < entries.length; ++i) {
                Object e = entries[i];
                if (e instanceof RunnableScheduledFuture) {
                    RunnableScheduledFuture<?> t = (RunnableScheduledFuture<?>)e;
                    if (t.isPeriodic()? !keepPeriodic : !keepDelayed)
                        t.cancel(false);
                }
            }
            entries = null;
            purge();
        }
    
protected java.util.concurrent.RunnableScheduledFuturedecorateTask(java.lang.Runnable runnable, java.util.concurrent.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.

param
runnable the submitted Runnable
param
task the task created to execute the runnable
return
a task that can execute the runnable
since
1.6

        return task;
    
protected java.util.concurrent.RunnableScheduledFuturedecorateTask(java.util.concurrent.Callable callable, java.util.concurrent.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.

param
callable the submitted Callable
param
task the task created to execute the callable
return
a task that can execute the callable
since
1.6

        return task;
    
private voiddelayedExecute(java.lang.Runnable command)
Specialized variant of ThreadPoolExecutor.execute for delayed tasks.

        if (isShutdown()) {
            reject(command);
            return;
        }
        // Prestart a thread if necessary. We cannot prestart it
        // running the task because the task (probably) shouldn't be
        // run yet, so thread will just idle until delay elapses.
        if (getPoolSize() < getCorePoolSize())
            prestartCoreThread();

        super.getQueue().add(command);
    
public voidexecute(java.lang.Runnable command)
Executes 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 shutdownNow will access the zero-delayed {@link ScheduledFuture}, not the command itself.

param
command the task to execute
throws
RejectedExecutionException at discretion of RejectedExecutionHandler, if task cannot be accepted for execution because the executor has been shut down.
throws
NullPointerException if command is null

        if (command == null)
            throw new NullPointerException();
        schedule(command, 0, TimeUnit.NANOSECONDS);
    
public booleangetContinueExistingPeriodicTasksAfterShutdownPolicy()
Gets the policy on whether to continue executing existing periodic tasks even when this executor has been shutdown. In this case, these tasks will only terminate upon shutdownNow or after setting the policy to false when already shutdown. This value is by default false.

return
true if will continue after shutdown
see
#setContinueExistingPeriodicTasksAfterShutdownPolicy

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

return
true if will execute after shutdown
see
#setExecuteExistingDelayedTasksAfterShutdownPolicy

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

return
the task queue

        return super.getQueue();
    
final longnow()
Returns nanosecond time offset by origin


               
       
        return System.nanoTime() - NANO_ORIGIN;
    
public booleanremove(java.lang.Runnable task)

        if (!(task instanceof RunnableScheduledFuture))
            return false;
        return getQueue().remove(task);
    
public java.util.concurrent.ScheduledFutureschedule(java.lang.Runnable command, long delay, java.util.concurrent.TimeUnit unit)

        if (command == null || unit == null)
            throw new NullPointerException();
        long triggerTime = now() + unit.toNanos(delay);
        RunnableScheduledFuture<?> t = decorateTask(command,
            new ScheduledFutureTask<Boolean>(command, null, triggerTime));
        delayedExecute(t);
        return t;
    
public java.util.concurrent.ScheduledFutureschedule(java.util.concurrent.Callable callable, long delay, java.util.concurrent.TimeUnit unit)

        if (callable == null || unit == null)
            throw new NullPointerException();
        if (delay < 0) delay = 0;
        long triggerTime = now() + unit.toNanos(delay);
        RunnableScheduledFuture<V> t = decorateTask(callable,
            new ScheduledFutureTask<V>(callable, triggerTime));
        delayedExecute(t);
        return t;
    
public java.util.concurrent.ScheduledFuturescheduleAtFixedRate(java.lang.Runnable command, long initialDelay, long period, java.util.concurrent.TimeUnit unit)

        if (command == null || unit == null)
            throw new NullPointerException();
        if (period <= 0)
            throw new IllegalArgumentException();
        if (initialDelay < 0) initialDelay = 0;
        long triggerTime = now() + unit.toNanos(initialDelay);
        RunnableScheduledFuture<?> t = decorateTask(command,
            new ScheduledFutureTask<Object>(command,
                                            null,
                                            triggerTime,
                                            unit.toNanos(period)));
        delayedExecute(t);
        return t;
    
public java.util.concurrent.ScheduledFuturescheduleWithFixedDelay(java.lang.Runnable command, long initialDelay, long delay, java.util.concurrent.TimeUnit unit)

        if (command == null || unit == null)
            throw new NullPointerException();
        if (delay <= 0)
            throw new IllegalArgumentException();
        if (initialDelay < 0) initialDelay = 0;
        long triggerTime = now() + unit.toNanos(initialDelay);
        RunnableScheduledFuture<?> t = decorateTask(command,
            new ScheduledFutureTask<Boolean>(command,
                                             null,
                                             triggerTime,
                                             unit.toNanos(-delay)));
        delayedExecute(t);
        return t;
    
public voidsetContinueExistingPeriodicTasksAfterShutdownPolicy(boolean value)
Sets the policy on whether to continue executing existing periodic tasks even when this executor has been shutdown. In this case, these tasks will only terminate upon shutdownNow, or after setting the policy to false when already shutdown. This value is by default false.

param
value if true, continue after shutdown, else don't.
see
#getContinueExistingPeriodicTasksAfterShutdownPolicy

        continueExistingPeriodicTasksAfterShutdown = value;
        if (!value && isShutdown())
            cancelUnwantedTasks();
    
public voidsetExecuteExistingDelayedTasksAfterShutdownPolicy(boolean value)
Sets the policy on whether to execute existing delayed tasks even when this executor has been shutdown. In this case, these tasks will only terminate upon shutdownNow, or after setting the policy to false when already shutdown. This value is by default true.

param
value if true, execute after shutdown, else don't.
see
#getExecuteExistingDelayedTasksAfterShutdownPolicy

        executeExistingDelayedTasksAfterShutdown = value;
        if (!value && isShutdown())
            cancelUnwantedTasks();
    
public voidshutdown()
Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted. If the ExecuteExistingDelayedTasksAfterShutdownPolicy has been set false, existing delayed tasks whose delays have not yet elapsed are cancelled. And unless the ContinueExistingPeriodicTasksAfterShutdownPolicy has been set true, future executions of existing periodic tasks will be cancelled.

        cancelUnwantedTasks();
        super.shutdown();
    
public java.util.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.

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

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

        return super.shutdownNow();
    
public java.util.concurrent.Futuresubmit(java.lang.Runnable task)

        return schedule(task, 0, TimeUnit.NANOSECONDS);
    
public java.util.concurrent.Futuresubmit(java.lang.Runnable task, T result)

        return schedule(Executors.callable(task, result),
                        0, TimeUnit.NANOSECONDS);
    
public java.util.concurrent.Futuresubmit(java.util.concurrent.Callable task)

        return schedule(task, 0, TimeUnit.NANOSECONDS);