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