lib/classpath/external/jsr166/java/util/concurrent/ScheduledExecutorService.java

   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 }