FileDocCategorySizeDatePackage
ScheduledThreadPoolExecutor.javaAPI DocAndroid 1.5 API20991Wed May 06 22:41:02 BST 2009java.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.

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)
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 less than or equal to zero

        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
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
NullPointerException if handler is null

        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue(), handler);
    
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
NullPointerException if threadFactory or handler is null

        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue(), threadFactory, handler);
    
Methods Summary
private voidcancelUnwantedTasks()
Cancel and clear 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 ScheduledFutureTask) {
                    ScheduledFutureTask<?> t = (ScheduledFutureTask<?>)e;
                    if (t.isPeriodic()? !keepPeriodic : !keepDelayed)
                        t.cancel(false);
                }
            }
            entries = null;
            purge();
        }
    
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)
Execute 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()
Get 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()
Get 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 ScheduledFutureTask))
            return false;
        return getQueue().remove(task);
    
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);
        ScheduledFutureTask<V> t = 
            new ScheduledFutureTask<V>(callable, triggerTime);
        delayedExecute(t);
        return t;
    
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);
        ScheduledFutureTask<?> t = 
            new ScheduledFutureTask<Boolean>(command, null, 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);
        ScheduledFutureTask<?> t = 
            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);
        ScheduledFutureTask<?> t = 
            new ScheduledFutureTask<Boolean>(command, 
                                             null,
                                             triggerTime,
                                             unit.toNanos(-delay));
        delayedExecute(t);
        return t;
    
public voidsetContinueExistingPeriodicTasksAfterShutdownPolicy(boolean value)
Set 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
#getExecuteExistingDelayedTasksAfterShutdownPolicy

        continueExistingPeriodicTasksAfterShutdown = value;
        if (!value && isShutdown())
            cancelUnwantedTasks();
    
public voidsetExecuteExistingDelayedTasksAfterShutdownPolicy(boolean value)
Set 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 if any tasks mask or fail to respond to interrupts, they 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.

        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);