/*
* Written by Doug Lea with assistance from members of JCP JSR-166
* Expert Group and released to the public domain. Use, modify, and
* redistribute this code in any way without acknowledgement.
*/
package java.util.concurrent;
import java.util.concurrent.atomic.*;
import java.util.*;
/**
* An {@link Executor} that can schedule commands to run after a given
* delay, or to execute periodically.
*
*
The schedule methods create tasks with various delays
* and return a task object that can be used to cancel or check
* execution. The scheduleAtFixedRate and
* scheduleWithFixedDelay methods create and execute tasks
* that run periodically until cancelled. Commands submitted using
* the execute method are scheduled with a requested delay of
* zero.
*
*
All schedule methods accept relative delays and
* periods as arguments, not absolute times or dates. It is a simple
* matter to transform an absolute time represented as a {@link
* java.util.Date} to the required form. For example, to schedule at
* a certain future date, you can use: schedule(task,
* date.getTime() - System.currentTimeMillis(),
* TimeUnit.MILLISECONDS). Beware however that expiration of a
* relative delay need not coincide with the current Date at
* which the task is enabled due to network time synchronization
* protocols, clock drift, or other factors. Negative relative delays
* (but not periods) are allowed in schedule methods, and are
* treated as requests for immediate execution.
*
* @since 1.5
* @author Doug Lea
*/
public interface ScheduledExecutor extends Executor {
/**
* Creates and executes a one-shot action that becomes enabled
* after the given delay.
* @param command the task to execute.
* @param delay the time from now to delay execution.
* @param unit the time unit of the delay parameter.
* @return a Future representing pending completion of the task,
* and whose get() method will return an arbitrary value
* upon completion.
* @throws RejectedExecutionException if task cannot be scheduled
* for execution because the executor has been shut down.
* @throws NullPointerException if command is null
*/
public ScheduledFuture> schedule(Runnable command, long delay, TimeUnit unit);
/**
* Creates and executes a ScheduledFuture that becomes enabled after the
* given delay.
* @param callable the function to execute.
* @param delay the time from now to delay execution.
* @param unit the time unit of the delay parameter.
* @return a ScheduledFuture that can be used to extract result or cancel.
* @throws RejectedExecutionException if task cannot be scheduled
* for execution because the executor has been shut down.
* @throws NullPointerException if callable is null
*/
public ScheduledFuture schedule(Callable callable, long delay, TimeUnit unit);
/**
* Creates and executes a periodic action that becomes enabled first
* after the given initial delay, and subsequently with the given
* period; that is executions will commence after
* initialDelay then initialDelay+period, then
* initialDelay + 2 * period, and so on. The
* task will only terminate via cancellation.
* @param command the task to execute.
* @param initialDelay the time to delay first execution.
* @param period the period between successive executions.
* @param unit the time unit of the delay and period parameters
* @return a Future representing pending completion of the task,
* and whose get() method will throw an exception upon
* cancellation.
* @throws RejectedExecutionException if task cannot be scheduled
* for execution because the executor has been shut down.
* @throws NullPointerException if command is null
* @throws IllegalArgumentException if period less than or equal to zero.
*/
public ScheduledFuture> scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit);
/**
* Creates and executes a periodic action that becomes enabled first
* after the given initial delay, and subsequently with the
* given delay between the termination of one execution and the
* commencement of the next.
* The task will only terminate via cancellation.
* @param command the task to execute.
* @param initialDelay the time to delay first execution.
* @param delay the delay between the termination of one
* execution and the commencement of the next.
* @param unit the time unit of the delay and delay parameters
* @return a Future representing pending completion of the task,
* and whose get() method will throw an exception upon
* cancellation.
* @throws RejectedExecutionException if task cannot be scheduled
* for execution because the executor has been shut down.
* @throws NullPointerException if command is null
* @throws IllegalArgumentException if delay less than or equal to zero.
*/
public ScheduledFuture> scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit);
/**
* Execute command with zero required delay. This has effect
* equivalent to schedule(command, 0, anyUnit).
* @param command the task to execute
* @throws RejectedExecutionException if this task cannot be
* accepted for execution.
* @throws NullPointerException if command is null
*/
public void execute(Runnable command);
}