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
7 package java.util.concurrent;
9 import java.util.Collection;
10 import java.security.PrivilegedAction;
11 import java.security.PrivilegedExceptionAction;
14 * An {@link Executor} that provides methods to manage termination and
15 * methods that can produce a {@link Future} for tracking progress of
16 * one or more asynchronous tasks.
19 * An <tt>ExecutorService</tt> can be shut down, which will cause it
20 * to stop accepting new tasks. After being shut down, the executor
21 * will eventually terminate, at which point no tasks are actively
22 * executing, no tasks are awaiting execution, and no new tasks can be
23 * submitted. An unused <tt>ExecutorService</tt> should be shut down
24 * to allow reclamation of its resources.
26 * <p> Method <tt>submit</tt> extends base method {@link
27 * Executor#execute} by creating and returning a {@link Future} that
28 * can be used to cancel execution and/or wait for completion.
29 * Methods <tt>invokeAny</tt> and <tt>invokeAll</tt> perform the most
30 * commonly useful forms of bulk execution, executing a collection of
31 * tasks and then waiting for at least one, or all, to
32 * complete. (Class {@link ExecutorCompletionService} can be used to
33 * write customized variants of these methods.)
35 * <p>The {@link Executors} class provides factory methods for the
36 * executor services provided in this package.
38 * <h3>Usage Example</h3>
40 * Here is a sketch of a network service in which threads in a thread
41 * pool service incoming requests. It uses the preconfigured {@link
42 * Executors#newFixedThreadPool} factory method:
45 * class NetworkService {
46 * private final ServerSocket serverSocket;
47 * private final ExecutorService pool;
49 * public NetworkService(int port, int poolSize)
50 * throws IOException {
51 * serverSocket = new ServerSocket(port);
52 * pool = Executors.newFixedThreadPool(poolSize);
55 * public void serve() {
58 * pool.execute(new Handler(serverSocket.accept()));
60 * } catch (IOException ex) {
66 * class Handler implements Runnable {
67 * private final Socket socket;
68 * Handler(Socket socket) { this.socket = socket; }
70 * // read and service request
75 * <p>Memory consistency effects: Actions in a thread prior to the
76 * submission of a {@code Runnable} or {@code Callable} task to an
77 * {@code ExecutorService}
78 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
79 * any actions taken by that task, which in turn <i>happen-before</i> the
80 * result is retrieved via {@code Future.get()}.
85 public interface ExecutorService extends Executor {
88 * Initiates an orderly shutdown in which previously submitted
89 * tasks are executed, but no new tasks will be accepted.
90 * Invocation has no additional effect if already shut down.
92 * @throws SecurityException if a security manager exists and
93 * shutting down this ExecutorService may manipulate
94 * threads that the caller is not permitted to modify
95 * because it does not hold {@link
96 * java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
97 * or the security manager's <tt>checkAccess</tt> method
103 * Attempts to stop all actively executing tasks, halts the
104 * processing of waiting tasks, and returns a list of the tasks that were
105 * awaiting execution.
107 * <p>There are no guarantees beyond best-effort attempts to stop
108 * processing actively executing tasks. For example, typical
109 * implementations will cancel via {@link Thread#interrupt}, so any
110 * task that fails to respond to interrupts may never terminate.
112 * @return list of tasks that never commenced execution
113 * @throws SecurityException if a security manager exists and
114 * shutting down this ExecutorService may manipulate
115 * threads that the caller is not permitted to modify
116 * because it does not hold {@link
117 * java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
118 * or the security manager's <tt>checkAccess</tt> method
121 List<Runnable> shutdownNow();
124 * Returns <tt>true</tt> if this executor has been shut down.
126 * @return <tt>true</tt> if this executor has been shut down
128 boolean isShutdown();
131 * Returns <tt>true</tt> if all tasks have completed following shut down.
132 * Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
133 * either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
135 * @return <tt>true</tt> if all tasks have completed following shut down
137 boolean isTerminated();
140 * Blocks until all tasks have completed execution after a shutdown
141 * request, or the timeout occurs, or the current thread is
142 * interrupted, whichever happens first.
144 * @param timeout the maximum time to wait
145 * @param unit the time unit of the timeout argument
146 * @return <tt>true</tt> if this executor terminated and
147 * <tt>false</tt> if the timeout elapsed before termination
148 * @throws InterruptedException if interrupted while waiting
150 boolean awaitTermination(long timeout, TimeUnit unit)
151 throws InterruptedException;
155 * Submits a value-returning task for execution and returns a
156 * Future representing the pending results of the task. The
157 * Future's <tt>get</tt> method will return the task's result upon
158 * successful completion.
161 * If you would like to immediately block waiting
162 * for a task, you can use constructions of the form
163 * <tt>result = exec.submit(aCallable).get();</tt>
165 * <p> Note: The {@link Executors} class includes a set of methods
166 * that can convert some other common closure-like objects,
167 * for example, {@link java.security.PrivilegedAction} to
168 * {@link Callable} form so they can be submitted.
170 * @param task the task to submit
171 * @return a Future representing pending completion of the task
172 * @throws RejectedExecutionException if the task cannot be
173 * scheduled for execution
174 * @throws NullPointerException if the task is null
176 <T> Future<T> submit(Callable<T> task);
179 * Submits a Runnable task for execution and returns a Future
180 * representing that task. The Future's <tt>get</tt> method will
181 * return the given result upon successful completion.
183 * @param task the task to submit
184 * @param result the result to return
185 * @return a Future representing pending completion of the task
186 * @throws RejectedExecutionException if the task cannot be
187 * scheduled for execution
188 * @throws NullPointerException if the task is null
190 <T> Future<T> submit(Runnable task, T result);
193 * Submits a Runnable task for execution and returns a Future
194 * representing that task. The Future's <tt>get</tt> method will
195 * return <tt>null</tt> upon <em>successful</em> completion.
197 * @param task the task to submit
198 * @return a Future representing pending completion of the task
199 * @throws RejectedExecutionException if the task cannot be
200 * scheduled for execution
201 * @throws NullPointerException if the task is null
203 Future<?> submit(Runnable task);
206 * Executes the given tasks, returning a list of Futures holding
207 * their status and results when all complete.
208 * {@link Future#isDone} is <tt>true</tt> for each
209 * element of the returned list.
210 * Note that a <em>completed</em> task could have
211 * terminated either normally or by throwing an exception.
212 * The results of this method are undefined if the given
213 * collection is modified while this operation is in progress.
215 * @param tasks the collection of tasks
216 * @return A list of Futures representing the tasks, in the same
217 * sequential order as produced by the iterator for the
218 * given task list, each of which has completed.
219 * @throws InterruptedException if interrupted while waiting, in
220 * which case unfinished tasks are cancelled.
221 * @throws NullPointerException if tasks or any of its elements are <tt>null</tt>
222 * @throws RejectedExecutionException if any task cannot be
223 * scheduled for execution
226 <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
227 throws InterruptedException;
230 * Executes the given tasks, returning a list of Futures holding
231 * their status and results
232 * when all complete or the timeout expires, whichever happens first.
233 * {@link Future#isDone} is <tt>true</tt> for each
234 * element of the returned list.
235 * Upon return, tasks that have not completed are cancelled.
236 * Note that a <em>completed</em> task could have
237 * terminated either normally or by throwing an exception.
238 * The results of this method are undefined if the given
239 * collection is modified while this operation is in progress.
241 * @param tasks the collection of tasks
242 * @param timeout the maximum time to wait
243 * @param unit the time unit of the timeout argument
244 * @return a list of Futures representing the tasks, in the same
245 * sequential order as produced by the iterator for the
246 * given task list. If the operation did not time out,
247 * each task will have completed. If it did time out, some
248 * of these tasks will not have completed.
249 * @throws InterruptedException if interrupted while waiting, in
250 * which case unfinished tasks are cancelled
251 * @throws NullPointerException if tasks, any of its elements, or
252 * unit are <tt>null</tt>
253 * @throws RejectedExecutionException if any task cannot be scheduled
256 <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks,
257 long timeout, TimeUnit unit)
258 throws InterruptedException;
261 * Executes the given tasks, returning the result
262 * of one that has completed successfully (i.e., without throwing
263 * an exception), if any do. Upon normal or exceptional return,
264 * tasks that have not completed are cancelled.
265 * The results of this method are undefined if the given
266 * collection is modified while this operation is in progress.
268 * @param tasks the collection of tasks
269 * @return the result returned by one of the tasks
270 * @throws InterruptedException if interrupted while waiting
271 * @throws NullPointerException if tasks or any of its elements
273 * @throws IllegalArgumentException if tasks is empty
274 * @throws ExecutionException if no task successfully completes
275 * @throws RejectedExecutionException if tasks cannot be scheduled
278 <T> T invokeAny(Collection<? extends Callable<T>> tasks)
279 throws InterruptedException, ExecutionException;
282 * Executes the given tasks, returning the result
283 * of one that has completed successfully (i.e., without throwing
284 * an exception), if any do before the given timeout elapses.
285 * Upon normal or exceptional return, tasks that have not
286 * completed are cancelled.
287 * The results of this method are undefined if the given
288 * collection is modified while this operation is in progress.
290 * @param tasks the collection of tasks
291 * @param timeout the maximum time to wait
292 * @param unit the time unit of the timeout argument
293 * @return the result returned by one of the tasks.
294 * @throws InterruptedException if interrupted while waiting
295 * @throws NullPointerException if tasks, any of its elements, or
296 * unit are <tt>null</tt>
297 * @throws TimeoutException if the given timeout elapses before
298 * any task successfully completes
299 * @throws ExecutionException if no task successfully completes
300 * @throws RejectedExecutionException if tasks cannot be scheduled
303 <T> T invokeAny(Collection<? extends Callable<T>> tasks,
304 long timeout, TimeUnit unit)
305 throws InterruptedException, ExecutionException, TimeoutException;