Source for java.util.concurrent.ScheduledExecutorService

   1: /*
   2:  * Written by Doug Lea with assistance from members of JCP JSR-166
   3:  * Expert Group and released to the public domain, as explained at
   4:  * http://creativecommons.org/licenses/publicdomain
   5:  */
   6: 
   7: package java.util.concurrent;
   8: import java.util.concurrent.atomic.*;
   9: import java.util.*;
  10: 
  11: /**
  12:  * An {@link ExecutorService} that can schedule commands to run after a given
  13:  * delay, or to execute periodically.
  14:  *
  15:  * <p> The <tt>schedule</tt> methods create tasks with various delays
  16:  * and return a task object that can be used to cancel or check
  17:  * execution. The <tt>scheduleAtFixedRate</tt> and
  18:  * <tt>scheduleWithFixedDelay</tt> methods create and execute tasks
  19:  * that run periodically until cancelled.
  20:  *
  21:  * <p> Commands submitted using the {@link Executor#execute} and
  22:  * {@link ExecutorService} <tt>submit</tt> methods are scheduled with
  23:  * a requested delay of zero. Zero and negative delays (but not
  24:  * periods) are also allowed in <tt>schedule</tt> methods, and are
  25:  * treated as requests for immediate execution.
  26:  *
  27:  * <p>All <tt>schedule</tt> methods accept <em>relative</em> delays and
  28:  * periods as arguments, not absolute times or dates. It is a simple
  29:  * matter to transform an absolute time represented as a {@link
  30:  * java.util.Date} to the required form. For example, to schedule at
  31:  * a certain future <tt>date</tt>, you can use: <tt>schedule(task,
  32:  * date.getTime() - System.currentTimeMillis(),
  33:  * TimeUnit.MILLISECONDS)</tt>. Beware however that expiration of a
  34:  * relative delay need not coincide with the current <tt>Date</tt> at
  35:  * which the task is enabled due to network time synchronization
  36:  * protocols, clock drift, or other factors.
  37:  *
  38:  * The {@link Executors} class provides convenient factory methods for
  39:  * the ScheduledExecutorService implementations provided in this package.
  40:  *
  41:  * <h3>Usage Example</h3>
  42:  *
  43:  * Here is a class with a method that sets up a ScheduledExecutorService
  44:  * to beep every ten seconds for an hour:
  45:  *
  46:  * <pre>
  47:  * import static java.util.concurrent.TimeUnit.*;
  48:  * class BeeperControl {
  49:  *    private final ScheduledExecutorService scheduler =
  50:  *       Executors.newScheduledThreadPool(1);
  51:  *
  52:  *    public void beepForAnHour() {
  53:  *        final Runnable beeper = new Runnable() {
  54:  *                public void run() { System.out.println("beep"); }
  55:  *            };
  56:  *        final ScheduledFuture&lt;?&gt; beeperHandle =
  57:  *            scheduler.scheduleAtFixedRate(beeper, 10, 10, SECONDS);
  58:  *        scheduler.schedule(new Runnable() {
  59:  *                public void run() { beeperHandle.cancel(true); }
  60:  *            }, 60 * 60, SECONDS);
  61:  *    }
  62:  * }
  63:  * </pre>
  64:  *
  65:  * @since 1.5
  66:  * @author Doug Lea
  67:  */
  68: public interface ScheduledExecutorService extends ExecutorService {
  69: 
  70:     /**
  71:      * Creates and executes a one-shot action that becomes enabled
  72:      * after the given delay.
  73:      *
  74:      * @param command the task to execute
  75:      * @param delay the time from now to delay execution
  76:      * @param unit the time unit of the delay parameter
  77:      * @return a ScheduledFuture representing pending completion of
  78:      *         the task and whose <tt>get()</tt> method will return
  79:      *         <tt>null</tt> upon completion
  80:      * @throws RejectedExecutionException if the task cannot be
  81:      *         scheduled for execution
  82:      * @throws NullPointerException if command is null
  83:      */
  84:     public ScheduledFuture<?> schedule(Runnable command,
  85:                        long delay, TimeUnit unit);
  86: 
  87:     /**
  88:      * Creates and executes a ScheduledFuture that becomes enabled after the
  89:      * given delay.
  90:      *
  91:      * @param callable the function to execute
  92:      * @param delay the time from now to delay execution
  93:      * @param unit the time unit of the delay parameter
  94:      * @return a ScheduledFuture that can be used to extract result or cancel
  95:      * @throws RejectedExecutionException if the task cannot be
  96:      *         scheduled for execution
  97:      * @throws NullPointerException if callable is null
  98:      */
  99:     public <V> ScheduledFuture<V> schedule(Callable<V> callable,
 100:                        long delay, TimeUnit unit);
 101: 
 102:     /**
 103:      * Creates and executes a periodic action that becomes enabled first
 104:      * after the given initial delay, and subsequently with the given
 105:      * period; that is executions will commence after
 106:      * <tt>initialDelay</tt> then <tt>initialDelay+period</tt>, then
 107:      * <tt>initialDelay + 2 * period</tt>, and so on.
 108:      * If any execution of the task
 109:      * encounters an exception, subsequent executions are suppressed.
 110:      * Otherwise, the task will only terminate via cancellation or
 111:      * termination of the executor.  If any execution of this task
 112:      * takes longer than its period, then subsequent executions
 113:      * may start late, but will not concurrently execute.
 114:      *
 115:      * @param command the task to execute
 116:      * @param initialDelay the time to delay first execution
 117:      * @param period the period between successive executions
 118:      * @param unit the time unit of the initialDelay and period parameters
 119:      * @return a ScheduledFuture representing pending completion of
 120:      *         the task, and whose <tt>get()</tt> method will throw an
 121:      *         exception upon cancellation
 122:      * @throws RejectedExecutionException if the task cannot be
 123:      *         scheduled for execution
 124:      * @throws NullPointerException if command is null
 125:      * @throws IllegalArgumentException if period less than or equal to zero
 126:      */
 127:     public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
 128:                           long initialDelay,
 129:                           long period,
 130:                           TimeUnit unit);
 131: 
 132:     /**
 133:      * Creates and executes a periodic action that becomes enabled first
 134:      * after the given initial delay, and subsequently with the
 135:      * given delay between the termination of one execution and the
 136:      * commencement of the next.  If any execution of the task
 137:      * encounters an exception, subsequent executions are suppressed.
 138:      * Otherwise, the task will only terminate via cancellation or
 139:      * termination of the executor.
 140:      *
 141:      * @param command the task to execute
 142:      * @param initialDelay the time to delay first execution
 143:      * @param delay the delay between the termination of one
 144:      * execution and the commencement of the next
 145:      * @param unit the time unit of the initialDelay and delay parameters
 146:      * @return a ScheduledFuture representing pending completion of
 147:      *         the task, and whose <tt>get()</tt> method will throw an
 148:      *         exception upon cancellation
 149:      * @throws RejectedExecutionException if the task cannot be
 150:      *         scheduled for execution
 151:      * @throws NullPointerException if command is null
 152:      * @throws IllegalArgumentException if delay less than or equal to zero
 153:      */
 154:     public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
 155:                              long initialDelay,
 156:                              long delay,
 157:                              TimeUnit unit);
 158: 
 159: }