2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
36 package java.util.concurrent;
37 import java.util.concurrent.atomic.*;
41 * An {@link ExecutorService} that can schedule commands to run after a given
42 * delay, or to execute periodically.
44 * <p> The <tt>schedule</tt> methods create tasks with various delays
45 * and return a task object that can be used to cancel or check
46 * execution. The <tt>scheduleAtFixedRate</tt> and
47 * <tt>scheduleWithFixedDelay</tt> methods create and execute tasks
48 * that run periodically until cancelled.
50 * <p> Commands submitted using the {@link Executor#execute} and
51 * {@link ExecutorService} <tt>submit</tt> methods are scheduled with
52 * a requested delay of zero. Zero and negative delays (but not
53 * periods) are also allowed in <tt>schedule</tt> methods, and are
54 * treated as requests for immediate execution.
56 * <p>All <tt>schedule</tt> methods accept <em>relative</em> delays and
57 * periods as arguments, not absolute times or dates. It is a simple
58 * matter to transform an absolute time represented as a {@link
59 * java.util.Date} to the required form. For example, to schedule at
60 * a certain future <tt>date</tt>, you can use: <tt>schedule(task,
61 * date.getTime() - System.currentTimeMillis(),
62 * TimeUnit.MILLISECONDS)</tt>. Beware however that expiration of a
63 * relative delay need not coincide with the current <tt>Date</tt> at
64 * which the task is enabled due to network time synchronization
65 * protocols, clock drift, or other factors.
67 * The {@link Executors} class provides convenient factory methods for
68 * the ScheduledExecutorService implementations provided in this package.
70 * <h3>Usage Example</h3>
72 * Here is a class with a method that sets up a ScheduledExecutorService
73 * to beep every ten seconds for an hour:
76 * import static java.util.concurrent.TimeUnit.*;
77 * class BeeperControl {
78 * private final ScheduledExecutorService scheduler =
79 * Executors.newScheduledThreadPool(1);
81 * public void beepForAnHour() {
82 * final Runnable beeper = new Runnable() {
83 * public void run() { System.out.println("beep"); }
85 * final ScheduledFuture<?> beeperHandle =
86 * scheduler.scheduleAtFixedRate(beeper, 10, 10, SECONDS);
87 * scheduler.schedule(new Runnable() {
88 * public void run() { beeperHandle.cancel(true); }
89 * }, 60 * 60, SECONDS);
96 public interface ScheduledExecutorService extends ExecutorService {
99 * Creates and executes a one-shot action that becomes enabled
100 * after the given delay.
102 * @param command the task to execute
103 * @param delay the time from now to delay execution
104 * @param unit the time unit of the delay parameter
105 * @return a ScheduledFuture representing pending completion of
106 * the task and whose <tt>get()</tt> method will return
107 * <tt>null</tt> upon completion
108 * @throws RejectedExecutionException if the task cannot be
109 * scheduled for execution
110 * @throws NullPointerException if command is null
112 public ScheduledFuture<?> schedule(Runnable command,
113 long delay, TimeUnit unit);
116 * Creates and executes a ScheduledFuture that becomes enabled after the
119 * @param callable the function to execute
120 * @param delay the time from now to delay execution
121 * @param unit the time unit of the delay parameter
122 * @return a ScheduledFuture that can be used to extract result or cancel
123 * @throws RejectedExecutionException if the task cannot be
124 * scheduled for execution
125 * @throws NullPointerException if callable is null
127 public <V> ScheduledFuture<V> schedule(Callable<V> callable,
128 long delay, TimeUnit unit);
131 * Creates and executes a periodic action that becomes enabled first
132 * after the given initial delay, and subsequently with the given
133 * period; that is executions will commence after
134 * <tt>initialDelay</tt> then <tt>initialDelay+period</tt>, then
135 * <tt>initialDelay + 2 * period</tt>, and so on.
136 * 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. If any execution of this task
140 * takes longer than its period, then subsequent executions
141 * may start late, but will not concurrently execute.
143 * @param command the task to execute
144 * @param initialDelay the time to delay first execution
145 * @param period the period between successive executions
146 * @param unit the time unit of the initialDelay and period 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 period less than or equal to zero
155 public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
161 * Creates and executes a periodic action that becomes enabled first
162 * after the given initial delay, and subsequently with the
163 * given delay between the termination of one execution and the
164 * commencement of the next. If any execution of the task
165 * encounters an exception, subsequent executions are suppressed.
166 * Otherwise, the task will only terminate via cancellation or
167 * termination of the executor.
169 * @param command the task to execute
170 * @param initialDelay the time to delay first execution
171 * @param delay the delay between the termination of one
172 * execution and the commencement of the next
173 * @param unit the time unit of the initialDelay and delay parameters
174 * @return a ScheduledFuture representing pending completion of
175 * the task, and whose <tt>get()</tt> method will throw an
176 * exception upon cancellation
177 * @throws RejectedExecutionException if the task cannot be
178 * scheduled for execution
179 * @throws NullPointerException if command is null
180 * @throws IllegalArgumentException if delay less than or equal to zero
182 public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,