ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ExecutorService.java
Revision: 1.17
Committed: Fri Dec 19 14:42:25 2003 UTC (20 years, 5 months ago) by dl
Branch: MAIN
Changes since 1.16: +111 -96 lines
Log Message: 
Documentation improvements

File Contents

# User Rev Content
1 dl 1.1 /*
2     * Written by Doug Lea with assistance from members of JCP JSR-166
3     * Expert Group and released to the public domain. Use, modify, and
4     * redistribute this code in any way without acknowledgement.
5     */
6    
7     package java.util.concurrent;
8    
9     import java.util.List;
10 dl 1.15 import java.util.Collection;
11 tim 1.8 import java.security.PrivilegedAction;
12     import java.security.PrivilegedExceptionAction;
13 dl 1.1
14     /**
15 dl 1.10 * An <tt>Executor</tt> that provides methods to manage termination
16 dl 1.17 * and methods that can produce a {@link Future} for tracking
17 dl 1.11 * progress of one or more asynchronous tasks.
18 dl 1.17 * <p>
19     *
20 dl 1.7 * An <tt>ExecutorService</tt> can be shut down, which will cause it
21     * to stop accepting new tasks. After being shut down, the executor
22     * will eventually terminate, at which point no tasks are actively
23 dl 1.1 * executing, no tasks are awaiting execution, and no new tasks can be
24     * submitted.
25     *
26 dl 1.17 * <p> Method <tt>submit</tt> and related methods extend base method
27     * <tt>execute</tt> 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 complete. (Class
32     * {@link ExecutorCompletionService} can be used to write customizable
33     * versions of such methods.)
34     *
35 dl 1.7 * <p>The {@link Executors} class provides factory methods for the
36     * executor services provided in this package.
37 dl 1.1 *
38     * @since 1.5
39 dl 1.5 * @author Doug Lea
40 dl 1.1 */
41     public interface ExecutorService extends Executor {
42 tim 1.8
43 dl 1.17
44     /**
45     * Initiates an orderly shutdown in which previously submitted
46     * tasks are executed, but no new tasks will be
47     * accepted. Invocation has no additional effect if already shut
48     * down.
49     * @throws SecurityException if a security manager exists and
50     * shutting down this ExecutorService may manipulate threads that
51     * the caller is not permitted to modify because it does not hold
52     * {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
53     * or the security manager's <tt>checkAccess</tt> method denies access.
54     */
55     void shutdown();
56    
57     /**
58     * Attempts to stop all actively executing tasks, halts the
59     * processing of waiting tasks, and returns a list of the tasks that were
60     * awaiting execution.
61     *
62     * <p>There are no guarantees beyond best-effort attempts to stop
63     * processing actively executing tasks. For example, typical
64     * implementations will cancel via {@link Thread#interrupt}, so if any
65     * tasks mask or fail to respond to interrupts, they may never terminate.
66     *
67     * @return list of tasks that never commenced execution
68     * @throws SecurityException if a security manager exists and
69     * shutting down this ExecutorService may manipulate threads that
70     * the caller is not permitted to modify because it does not hold
71     * {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
72     * or the security manager's <tt>checkAccess</tt> method denies access.
73     */
74     List<Runnable> shutdownNow();
75    
76     /**
77     * Returns <tt>true</tt> if this executor has been shut down.
78     *
79     * @return <tt>true</tt> if this executor has been shut down
80     */
81     boolean isShutdown();
82    
83     /**
84     * Returns <tt>true</tt> if all tasks have completed following shut down.
85     * Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
86     * either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
87     *
88     * @return <tt>true</tt> if all tasks have completed following shut down
89     */
90     boolean isTerminated();
91    
92     /**
93     * Blocks until all tasks have completed execution after a shutdown
94     * request, or the timeout occurs, or the current thread is
95     * interrupted, whichever happens first.
96     *
97     * @param timeout the maximum time to wait
98     * @param unit the time unit of the timeout argument
99     * @return <tt>true</tt> if this executor terminated and <tt>false</tt>
100     * if the timeout elapsed before termination
101     * @throws InterruptedException if interrupted while waiting
102     */
103     boolean awaitTermination(long timeout, TimeUnit unit)
104     throws InterruptedException;
105    
106    
107 tim 1.8 /**
108     * Submits a Runnable task for execution and returns a Future
109     * representing that task.
110     *
111     * @param task the task to submit
112 dl 1.14 * @param result the result to return upon completion
113 dl 1.17 * If you do not need a particular result, consider using
114     * the form: <tt>Future&lt;?&gt; cancellationHandle = e.submit(task, null)</tt>.
115 tim 1.8 * @return a Future representing pending completion of the task,
116 dl 1.14 * and whose <tt>get()</tt> method will return the given value
117 tim 1.8 * upon completion
118     * @throws RejectedExecutionException if task cannot be scheduled
119     * for execution
120     */
121 dl 1.14 <T> Future<T> submit(Runnable task, T result);
122 tim 1.8
123     /**
124     * Submits a value-returning task for execution and returns a Future
125     * representing the pending results of the task.
126     *
127     * @param task the task to submit
128     * @return a Future representing pending completion of the task
129     * @throws RejectedExecutionException if task cannot be scheduled
130     * for execution
131     */
132     <T> Future<T> submit(Callable<T> task);
133    
134    
135     /**
136     * Submits a privileged action for execution under the current
137     * access control context and returns a Future representing the
138     * pending result object of that action.
139     *
140     * @param action the action to submit
141     * @return a Future representing pending completion of the action
142     * @throws RejectedExecutionException if action cannot be scheduled
143     * for execution
144     */
145     Future<Object> submit(PrivilegedAction action);
146    
147     /**
148     * Submits a privileged exception action for execution under the current
149     * access control context and returns a Future representing the pending
150     * result object of that action.
151     *
152     * @param action the action to submit
153     * @return a Future representing pending completion of the action
154     * @throws RejectedExecutionException if action cannot be scheduled
155     * for execution
156     */
157     Future<Object> submit(PrivilegedExceptionAction action);
158    
159 dl 1.1 /**
160 dl 1.17 * Executes a Runnable task and blocks until it completes normally
161     * or throws an exception.
162 dl 1.1 *
163 dl 1.17 * @param task the task to submit
164     * @throws RejectedExecutionException if task cannot be scheduled
165     * for execution
166     * @throws ExecutionException if the task encountered an exception
167     * while executing
168 dl 1.1 */
169 dl 1.17 void invoke(Runnable task) throws ExecutionException, InterruptedException;
170 dl 1.1
171     /**
172 dl 1.17 * Executes a value-returning task and blocks until it returns a
173     * value or throws an exception.
174 dl 1.1 *
175 dl 1.17 * @param task the task to submit
176     * @return a Future representing pending completion of the task
177     * @throws RejectedExecutionException if task cannot be scheduled
178     * for execution
179     * @throws InterruptedException if interrupted while waiting for
180     * completion
181     * @throws ExecutionException if the task encountered an exception
182     * while executing
183 dl 1.1 */
184 dl 1.17 <T> T invoke(Callable<T> task) throws ExecutionException, InterruptedException;
185 dl 1.15
186 dl 1.11 /**
187 dl 1.17 * Executes the given tasks, returning when
188 dl 1.15 * all of them complete.
189 dl 1.12 * Note that a <em>completed</em> task could have
190     * terminated either normally or by throwing an exception.
191 dl 1.11 * @param tasks the collection of tasks
192 dl 1.14 * @param result value for each task to return upon completion.
193 dl 1.17 * If you do not need a particular result, consider using <tt>null</tt>.
194 dl 1.13 * @return A list of Futures representing the tasks, in the same
195 dl 1.16 * sequential order as as produced by the iterator for the given task list, each of which has
196 dl 1.15 * completed.
197 dl 1.11 * @throws InterruptedException if interrupted while waiting, in
198     * which case unfinished tasks are cancelled.
199 dl 1.13 * @throws NullPointerException if tasks or any of its elements are <tt>null</tt>
200     * @throws RejectedExecutionException if any task cannot be scheduled
201     * for execution
202 dl 1.11 */
203 dl 1.16 <T> List<Future<T>> invokeAll(Collection<Runnable> tasks, T result)
204 dl 1.11 throws InterruptedException;
205    
206     /**
207 dl 1.17 * Executes the given tasks, returning normally
208 dl 1.15 * when all complete or the given timeout expires, whichever
209     * happens first.
210 dl 1.11 * Upon return, tasks that have not completed are cancelled.
211 dl 1.12 * Note that a <em>completed</em> task could have
212     * terminated either normally or by throwing an exception.
213 dl 1.11 * @param tasks the collection of tasks
214 dl 1.14 * @param result value for each task to return upon completion.
215 dl 1.17 * If you do not need a particular result, consider using <tt>null</tt>.
216 dl 1.11 * @param timeout the maximum time to wait
217 dl 1.15 * @return A list of Futures representing the tasks, in the same
218 dl 1.16 * sequential order as as produced by the iterator for the given task list. If the operation did
219 dl 1.15 * not time out, each task will have completed. If it did time
220     * out, some of these tasks will not have completed.
221 dl 1.11 * @param unit the time unit of the timeout argument
222     * @throws InterruptedException if interrupted while waiting, in
223     * which case unfinished tasks are cancelled.
224 dl 1.17 * @throws NullPointerException if tasks, any of its elements, or unit are <tt>null</tt>
225 dl 1.13 * @throws RejectedExecutionException if any task cannot be scheduled
226     * for execution
227 dl 1.11 */
228 dl 1.16 <T> List<Future<T>> invokeAll(Collection<Runnable> tasks, T result,
229 dl 1.14 long timeout, TimeUnit unit)
230 dl 1.11 throws InterruptedException;
231    
232    
233     /**
234 dl 1.17 * Executes the given tasks, returning their results
235 dl 1.15 * when all complete.
236 dl 1.12 * Note that a <em>completed</em> task could have
237     * terminated either normally or by throwing an exception.
238 dl 1.11 * @param tasks the collection of tasks
239 dl 1.13 * @return A list of Futures representing the tasks, in the same
240 dl 1.16 * sequential order as produced by the iterator for the given task list, each of which has
241 dl 1.13 * completed.
242 dl 1.11 * @throws InterruptedException if interrupted while waiting, in
243     * which case unfinished tasks are cancelled.
244 dl 1.13 * @throws NullPointerException if tasks or any of its elements are <tt>null</tt>
245     * @throws RejectedExecutionException if any task cannot be scheduled
246     * for execution
247 dl 1.11 */
248 dl 1.15
249 dl 1.16 <T> List<Future<T>> invokeAll(Collection<Callable<T>> tasks)
250 dl 1.11 throws InterruptedException;
251    
252     /**
253 dl 1.17 * Executes the given tasks, returning their results
254 dl 1.15 * when all complete or the timeout expires, whichever happens first.
255 dl 1.11 * Upon return, tasks that have not completed are cancelled.
256 dl 1.12 * Note that a <em>completed</em> task could have
257     * terminated either normally or by throwing an exception.
258 dl 1.11 * @param tasks the collection of tasks
259     * @param timeout the maximum time to wait
260 dl 1.15 * @param unit the time unit of the timeout argument
261 dl 1.13 * @return A list of Futures representing the tasks, in the same
262 dl 1.16 * sequential order as as produced by the iterator for the given task list. If the operation did
263 dl 1.13 * not time out, each task will have completed. If it did time
264 dl 1.15 * out, some of thiese tasks will not have completed.
265 dl 1.11 * @throws InterruptedException if interrupted while waiting, in
266     * which case unfinished tasks are cancelled.
267 dl 1.17 * @throws NullPointerException if tasks, any of its elements, or
268 dl 1.15 * unit are <tt>null</tt>
269 dl 1.13 * @throws RejectedExecutionException if any task cannot be scheduled
270     * for execution
271 dl 1.11 */
272 dl 1.16 <T> List<Future<T>> invokeAll(Collection<Callable<T>> tasks,
273 dl 1.15 long timeout, TimeUnit unit)
274 dl 1.11 throws InterruptedException;
275    
276 dl 1.15
277 dl 1.11 /**
278 dl 1.17 * Executes the given tasks, returning the result
279 dl 1.15 * of one that has completed successfully (i.e., without throwing
280     * an exception), if any do. Upon normal or exceptional return,
281     * tasks that have not completed are cancelled.
282 dl 1.11 * @param tasks the collection of tasks
283 dl 1.15 * @return The result returned by one of the tasks.
284     * @throws InterruptedException if interrupted while waiting
285     * @throws NullPointerException if tasks or any of its elements
286     * are <tt>null</tt>
287     * @throws IllegalArgumentException if tasks empty
288     * @throws ExecutionException if no task successfully completes
289     * @throws RejectedExecutionException if tasks cannot be scheduled
290 dl 1.13 * for execution
291 dl 1.11 */
292    
293 dl 1.15 <T> T invokeAny(Collection<Callable<T>> tasks)
294     throws InterruptedException, ExecutionException;
295 dl 1.11
296     /**
297 dl 1.17 * Executes the given tasks, returning the result
298 dl 1.15 * of one that has completed successfully (i.e., without throwing
299     * an exception), if any do before the given timeout elapses.
300     * Upon normal or exceptional return, tasks that have not
301     * completed are cancelled.
302 dl 1.11 * @param tasks the collection of tasks
303     * @param timeout the maximum time to wait
304     * @param unit the time unit of the timeout argument
305 dl 1.15 * @return The result returned by one of the tasks.
306     * @throws InterruptedException if interrupted while waiting
307 dl 1.17 * @throws NullPointerException if tasks, any of its elements, or
308 dl 1.15 * unit are <tt>null</tt>
309     * @throws TimeoutException if the given timeout elapses before
310     * any task successfully completes
311     * @throws ExecutionException if no task successfully completes
312     * @throws RejectedExecutionException if tasks cannot be scheduled
313 dl 1.13 * for execution
314 dl 1.11 */
315 dl 1.15 <T> T invokeAny(Collection<Callable<T>> tasks,
316     long timeout, TimeUnit unit)
317     throws InterruptedException, ExecutionException, TimeoutException;
318 dl 1.11
319     /**
320 dl 1.17 * Executes the given tasks, returning the given
321 dl 1.15 * result if one completes successfully (i.e., without
322     * throwing an exception). Upon normal or exceptional
323     * return, tasks that have not completed are cancelled.
324 dl 1.11 * @param tasks the collection of tasks
325 dl 1.15 * @param result the result to return upon successful completion
326     * @return the given result
327     * @throws InterruptedException if interrupted while waiting
328     * @throws NullPointerException if tasks or any of its elements
329     * are <tt>null</tt>
330     * @throws IllegalArgumentException if tasks empty
331     * @throws ExecutionException if no task successfully completes
332     * @throws RejectedExecutionException if tasks cannot be scheduled
333 dl 1.13 * for execution
334 dl 1.11 */
335    
336 dl 1.15 <T> T invokeAny(Collection<Runnable> tasks, T result)
337     throws InterruptedException, ExecutionException;
338 dl 1.11
339     /**
340 dl 1.17 * Executes the given tasks, returning the given result
341 dl 1.15 * if one completes successfully (i.e., without throwing
342     * an exception) before the given timeout elapses.
343     * Upon normal or exceptional return, tasks that have not
344     * completed are cancelled.
345 dl 1.11 * @param tasks the collection of tasks
346 dl 1.15 * @param result the result to return upon successful completion
347 dl 1.11 * @param timeout the maximum time to wait
348     * @param unit the time unit of the timeout argument
349 dl 1.15 * @return the given result
350     * @throws InterruptedException if interrupted while waiting
351 dl 1.17 * @throws NullPointerException if tasks, any of its elements, or
352 dl 1.13 * unit are <tt>null</tt>
353 dl 1.15 * @throws TimeoutException if the given timeout elapses before
354     * any task successfully completes
355     * @throws ExecutionException if no task successfully completes
356     * @throws RejectedExecutionException if tasks cannot be scheduled
357 dl 1.13 * for execution
358 dl 1.11 */
359 dl 1.15 <T> T invokeAny(Collection<Runnable> tasks, T result,
360     long timeout, TimeUnit unit)
361     throws InterruptedException, ExecutionException, TimeoutException;
362    
363 dl 1.3
364 dl 1.1 }