util/concurrent/ExecutorService.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;

import java.util.Collection;
import java.util.List;
import java.security.PrivilegedAction;
import java.security.PrivilegedExceptionAction;

/**
 * An <tt>Executor</tt> that provides methods to manage termination
 * and those that can produce a {@link Future} for tracking
 * progress of one or more asynchronous tasks.
 * An <tt>ExecutorService</tt> can be shut down, which will cause it
 * to stop accepting new tasks.  After being shut down, the executor
 * will eventually terminate, at which point no tasks are actively
 * executing, no tasks are awaiting execution, and no new tasks can be
 * submitted.
 *
 * <p>The {@link Executors} class provides factory methods for the
 * executor services provided in this package.
 *
 * @since 1.5
 * @author Doug Lea
 */
public interface ExecutorService extends Executor {

    /**
     * Submits a Runnable task for execution and returns a Future 
     * representing that task.
     *
     * @param task the task to submit
     * @return a Future representing pending completion of the task,
     * and whose <tt>get()</tt> method will return an arbitrary value 
     * upon completion
     * @throws RejectedExecutionException if task cannot be scheduled
     * for execution
     */
    Future<?> submit(Runnable task);

    /**
     * Submits a value-returning task for execution and returns a Future
     * representing the pending results of the task.
     *
     * @param task the task to submit
     * @return a Future representing pending completion of the task
     * @throws RejectedExecutionException if task cannot be scheduled
     * for execution
     */
    <T> Future<T> submit(Callable<T> task);

    /**
     * Executes a Runnable task and blocks until it completes normally
     * or throws an exception.
     *
     * @param task the task to submit
     * @throws RejectedExecutionException if task cannot be scheduled
     * for execution
     * @throws ExecutionException if the task encountered an exception
     * while executing
     */
    void invoke(Runnable task) throws ExecutionException, InterruptedException;

    /**
     * Executes a value-returning task and blocks until it returns a
     * value or throws an exception.
     *
     * @param task the task to submit
     * @return a Future representing pending completion of the task
     * @throws RejectedExecutionException if task cannot be scheduled
     * for execution
     * @throws InterruptedException if interrupted while waiting for
     * completion
     * @throws ExecutionException if the task encountered an exception
     * while executing
     */
    <T> T invoke(Callable<T> task) throws ExecutionException, InterruptedException;


    /**
     * Submits a privileged action for execution under the current 
     * access control context and returns a Future representing the 
     * pending result object of that action.
     *
     * @param action the action to submit
     * @return a Future representing pending completion of the action
     * @throws RejectedExecutionException if action cannot be scheduled
     * for execution
     */
    Future<Object> submit(PrivilegedAction action);

    /**
     * Submits a privileged exception action for execution under the current 
     * access control context and returns a Future representing the pending 
     * result object of that action.
     *
     * @param action the action to submit
     * @return a Future representing pending completion of the action
     * @throws RejectedExecutionException if action cannot be scheduled
     * for execution
     */
    Future<Object> submit(PrivilegedExceptionAction action);
    

    /**
     * Initiates an orderly shutdown in which previously submitted
     * tasks are executed, but no new tasks will be
     * accepted. Invocation has no additional effect if already shut
     * down.
     *
     */
    void shutdown();

    /**
     * Attempts to stop all actively executing tasks, halts the
     * processing of waiting tasks, and returns a list of the tasks that were
     * awaiting execution. 
     *  
     * <p>There are no guarantees beyond best-effort attempts to stop
     * processing actively executing tasks.  For example, typical
     * implementations will cancel via {@link Thread#interrupt}, so if any
     * tasks mask or fail to respond to interrupts, they may never terminate.
     *
     * @return list of tasks that never commenced execution
     */
    List<Runnable> shutdownNow();

    /**
     * Returns <tt>true</tt> if this executor has been shut down.
     *
     * @return <tt>true</tt> if this executor has been shut down
     */
    boolean isShutdown();

    /**
     * Returns <tt>true</tt> if all tasks have completed following shut down.
     * Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
     * either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
     *
     * @return <tt>true</tt> if all tasks have completed following shut down
     */
    boolean isTerminated();

    /**
     * Blocks until all tasks have completed execution after a shutdown
     * request, or the timeout occurs, or the current thread is
     * interrupted, whichever happens first.
     *
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @return <tt>true</tt> if this executor terminated and <tt>false</tt>
     * if the timeout elapsed before termination
     * @throws InterruptedException if interrupted while waiting
     */
    boolean awaitTermination(long timeout, TimeUnit unit)
        throws InterruptedException;


    /**
     * Arranges for execution of the given tasks, returning when at
     * least one of them has completed. 
     * Upon return, tasks that have not completed are cancelled.
     * Note that a <em>completed</em> task could have
     * terminated either normally or by throwing an exception.
     * @param tasks the collection of tasks
     * @return A list of Futures representing the tasks. If the task
     * list is non-empty, the first element of this list is known to
     * have completed. Other tasks may or may not have also completed.
     * @throws InterruptedException if interrupted while waiting, in
     * which case unfinished tasks are cancelled.
     * @throws NullPointerException if tasks null
     */
    List<Future<?>> runAny(Collection<Runnable> tasks)
        throws InterruptedException;

    /**
     * Arranges for execution of the given tasks, returning when at
     * least one of them has completed or the given timeout expires.
     * Upon return, tasks that have not completed are cancelled.
     * Note that a <em>completed</em> task could have
     * terminated either normally or by throwing an exception.
     * @param tasks the collection of tasks
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @return A list of Futures representing the tasks. If the task
     * list is non-empty and the operation did not time out, the first
     * element of this list is known to have completed. Other tasks
     * may or may not have also completed. If the operation timed out,
     * none of the tasks will have completed.
     * @throws InterruptedException if interrupted while waiting, in
     * which case unfinished tasks are cancelled.
     * @throws NullPointerException if tasks or unit null
     */
    List<Future<?>> runAny(Collection<Runnable> tasks, 
                           long timeout, TimeUnit unit) 
        throws InterruptedException;


    /**
     * Arranges for execution of the given tasks, returning when
     * all of them complete. 
     * Note that a <em>completed</em> task could have
     * terminated either normally or by throwing an exception.
     * @param tasks the collection of tasks
     * @return A list of Futures representing the tasks, each
     * of which has completed. 
     * @throws InterruptedException if interrupted while waiting, in
     * which case unfinished tasks are cancelled.
     * @throws NullPointerException if tasks null
     */
    List<Future<?>> runAll(Collection<Runnable> tasks)
        throws InterruptedException;

    /**
     * Arranges for execution of the given tasks, returning normally
     * when all complete or the given timeout expires, whichever
     * happens first.
     * Upon return, tasks that have not completed are cancelled.
     * Note that a <em>completed</em> task could have
     * terminated either normally or by throwing an exception.
     * @param tasks the collection of tasks
     * @param timeout the maximum time to wait
     * @return A list of Futures representing the tasks. If the
     * operation did not time out, each
     * task will have completed. If it did time out, some of
     * thiese tasks will not have completed.
     * @param unit the time unit of the timeout argument
     * @throws InterruptedException if interrupted while waiting, in
     * which case unfinished tasks are cancelled.
     * @throws NullPointerException if tasks or unit null
     */
    List<Future<?>> runAll(Collection<Runnable> tasks, 
                              long timeout, TimeUnit unit) 
        throws InterruptedException;

    /**
     * Arranges for execution of the given tasks, returning when at
     * least one of them has completed. 
     * Upon return, tasks that have not completed are cancelled.
     * Note that a <em>completed</em> task could have
     * terminated either normally or by throwing an exception.
     * @param tasks the collection of tasks
     * @return A list of Futures representing the tasks. If the task
     * list is non-empty, the first element of this list is known to
     * have completed. Other tasks may or may not have also completed.
     * @throws InterruptedException if interrupted while waiting, in
     * which case unfinished tasks are cancelled.
     * @throws NullPointerException if tasks null
     */

    <T> List<Future<T>> callAny(Collection<Callable<T>> tasks)
        throws InterruptedException;

    /**
     * Arranges for execution of the given tasks, returning when at
     * least one of them has completed or the given timeout expires.
     * Upon return, tasks that have not completed are cancelled.
     * Note that a <em>completed</em> task could have
     * terminated either normally or by throwing an exception.
     * @param tasks the collection of tasks
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @return A list of Futures representing the tasks. If the task
     * list is non-empty and the operation did not time out, the first
     * element of this list is known to have completed. Other tasks
     * may or may not have also completed. If the operation timed out,
     * none of the tasks will have completed.
     * @throws InterruptedException if interrupted while waiting, in
     * which case unfinished tasks are cancelled.
     * @throws NullPointerException if tasks or unit null
     */
    <T> List<Future<T>> callAny(Collection<Callable<T>> tasks, 
                                long timeout, TimeUnit unit) 
        throws InterruptedException;

    /**
     * Arranges for execution of the given tasks, returning their results
     * when all complete.
     * Note that a <em>completed</em> task could have
     * terminated either normally or by throwing an exception.
     * @param tasks the collection of tasks
     * @return A list of Futures representing the tasks, each
     * of which has completed. 
     * @throws InterruptedException if interrupted while waiting, in
     * which case unfinished tasks are cancelled.
     * @throws NullPointerException if tasks null
     */

    <T> List<Future<T>> callAll(Collection<Callable<T>> tasks)
        throws InterruptedException;

    /**
     * Arranges for execution of the given tasks, returning their results
     * when all complete or the timeout expires, whichever happens first.
     * Upon return, tasks that have not completed are cancelled.
     * Note that a <em>completed</em> task could have
     * terminated either normally or by throwing an exception.
     * @param tasks the collection of tasks
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @return A list of Futures representing the tasks. If the
     * operation did not time out, each
     * task will have completed. If it did time out, some of
     * thiese tasks will not have completed.
     * @throws InterruptedException if interrupted while waiting, in
     * which case unfinished tasks are cancelled.
     * @throws NullPointerException if tasks or unit null
     */
    <T> List<Future<T>> callAll(Collection<Callable<T>> tasks, 
                                long timeout, TimeUnit unit) 
        throws InterruptedException;

}
Revision:	1.12
Committed:	Sun Dec 14 22:36:36 2003 UTC (20 years, 6 months ago) by dl
Branch:	MAIN
Changes since 1.11:	+19 -3 lines
Log Message:	Minor improvements to any/all methods
#	Content
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.Collection;
10	import java.util.List;
11	import java.security.PrivilegedAction;
12	import java.security.PrivilegedExceptionAction;
13
14	/**
15	* An <tt>Executor</tt> that provides methods to manage termination
16	* and those that can produce a {@link Future} for tracking
17	* progress of one or more asynchronous tasks.
18	* An <tt>ExecutorService</tt> can be shut down, which will cause it
19	* to stop accepting new tasks. After being shut down, the executor
20	* will eventually terminate, at which point no tasks are actively
21	* executing, no tasks are awaiting execution, and no new tasks can be
22	* submitted.
23	*
24	* <p>The {@link Executors} class provides factory methods for the
25	* executor services provided in this package.
26	*
27	* @since 1.5
28	* @author Doug Lea
29	*/
30	public interface ExecutorService extends Executor {
31
32	/**
33	* Submits a Runnable task for execution and returns a Future
34	* representing that task.
35	*
36	* @param task the task to submit
37	* @return a Future representing pending completion of the task,
38	* and whose <tt>get()</tt> method will return an arbitrary value
39	* upon completion
40	* @throws RejectedExecutionException if task cannot be scheduled
41	* for execution
42	*/
43	Future<?> submit(Runnable task);
44
45	/**
46	* Submits a value-returning task for execution and returns a Future
47	* representing the pending results of the task.
48	*
49	* @param task the task to submit
50	* @return a Future representing pending completion of the task
51	* @throws RejectedExecutionException if task cannot be scheduled
52	* for execution
53	*/
54	<T> Future<T> submit(Callable<T> task);
55
56	/**
57	* Executes a Runnable task and blocks until it completes normally
58	* or throws an exception.
59	*
60	* @param task the task to submit
61	* @throws RejectedExecutionException if task cannot be scheduled
62	* for execution
63	* @throws ExecutionException if the task encountered an exception
64	* while executing
65	*/
66	void invoke(Runnable task) throws ExecutionException, InterruptedException;
67
68	/**
69	* Executes a value-returning task and blocks until it returns a
70	* value or throws an exception.
71	*
72	* @param task the task to submit
73	* @return a Future representing pending completion of the task
74	* @throws RejectedExecutionException if task cannot be scheduled
75	* for execution
76	* @throws InterruptedException if interrupted while waiting for
77	* completion
78	* @throws ExecutionException if the task encountered an exception
79	* while executing
80	*/
81	<T> T invoke(Callable<T> task) throws ExecutionException, InterruptedException;
82
83
84	/**
85	* Submits a privileged action for execution under the current
86	* access control context and returns a Future representing the
87	* pending result object of that action.
88	*
89	* @param action the action to submit
90	* @return a Future representing pending completion of the action
91	* @throws RejectedExecutionException if action cannot be scheduled
92	* for execution
93	*/
94	Future<Object> submit(PrivilegedAction action);
95
96	/**
97	* Submits a privileged exception action for execution under the current
98	* access control context and returns a Future representing the pending
99	* result object of that action.
100	*
101	* @param action the action to submit
102	* @return a Future representing pending completion of the action
103	* @throws RejectedExecutionException if action cannot be scheduled
104	* for execution
105	*/
106	Future<Object> submit(PrivilegedExceptionAction action);
107
108
109	/**
110	* Initiates an orderly shutdown in which previously submitted
111	* tasks are executed, but no new tasks will be
112	* accepted. Invocation has no additional effect if already shut
113	* down.
114	*
115	*/
116	void shutdown();
117
118	/**
119	* Attempts to stop all actively executing tasks, halts the
120	* processing of waiting tasks, and returns a list of the tasks that were
121	* awaiting execution.
122	*
123	* <p>There are no guarantees beyond best-effort attempts to stop
124	* processing actively executing tasks. For example, typical
125	* implementations will cancel via {@link Thread#interrupt}, so if any
126	* tasks mask or fail to respond to interrupts, they may never terminate.
127	*
128	* @return list of tasks that never commenced execution
129	*/
130	List<Runnable> shutdownNow();
131
132	/**
133	* Returns <tt>true</tt> if this executor has been shut down.
134	*
135	* @return <tt>true</tt> if this executor has been shut down
136	*/
137	boolean isShutdown();
138
139	/**
140	* Returns <tt>true</tt> if all tasks have completed following shut down.
141	* Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
142	* either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
143	*
144	* @return <tt>true</tt> if all tasks have completed following shut down
145	*/
146	boolean isTerminated();
147
148	/**
149	* Blocks until all tasks have completed execution after a shutdown
150	* request, or the timeout occurs, or the current thread is
151	* interrupted, whichever happens first.
152	*
153	* @param timeout the maximum time to wait
154	* @param unit the time unit of the timeout argument
155	* @return <tt>true</tt> if this executor terminated and <tt>false</tt>
156	* if the timeout elapsed before termination
157	* @throws InterruptedException if interrupted while waiting
158	*/
159	boolean awaitTermination(long timeout, TimeUnit unit)
160	throws InterruptedException;
161
162
163	/**
164	* Arranges for execution of the given tasks, returning when at
165	* least one of them has completed.
166	* Upon return, tasks that have not completed are cancelled.
167	* Note that a <em>completed</em> task could have
168	* terminated either normally or by throwing an exception.
169	* @param tasks the collection of tasks
170	* @return A list of Futures representing the tasks. If the task
171	* list is non-empty, the first element of this list is known to
172	* have completed. Other tasks may or may not have also completed.
173	* @throws InterruptedException if interrupted while waiting, in
174	* which case unfinished tasks are cancelled.
175	* @throws NullPointerException if tasks null
176	*/
177	List<Future<?>> runAny(Collection<Runnable> tasks)
178	throws InterruptedException;
179
180	/**
181	* Arranges for execution of the given tasks, returning when at
182	* least one of them has completed or the given timeout expires.
183	* Upon return, tasks that have not completed are cancelled.
184	* Note that a <em>completed</em> task could have
185	* terminated either normally or by throwing an exception.
186	* @param tasks the collection of tasks
187	* @param timeout the maximum time to wait
188	* @param unit the time unit of the timeout argument
189	* @return A list of Futures representing the tasks. If the task
190	* list is non-empty and the operation did not time out, the first
191	* element of this list is known to have completed. Other tasks
192	* may or may not have also completed. If the operation timed out,
193	* none of the tasks will have completed.
194	* @throws InterruptedException if interrupted while waiting, in
195	* which case unfinished tasks are cancelled.
196	* @throws NullPointerException if tasks or unit null
197	*/
198	List<Future<?>> runAny(Collection<Runnable> tasks,
199	long timeout, TimeUnit unit)
200	throws InterruptedException;
201
202
203	/**
204	* Arranges for execution of the given tasks, returning when
205	* all of them complete.
206	* Note that a <em>completed</em> task could have
207	* terminated either normally or by throwing an exception.
208	* @param tasks the collection of tasks
209	* @return A list of Futures representing the tasks, each
210	* of which has completed.
211	* @throws InterruptedException if interrupted while waiting, in
212	* which case unfinished tasks are cancelled.
213	* @throws NullPointerException if tasks null
214	*/
215	List<Future<?>> runAll(Collection<Runnable> tasks)
216	throws InterruptedException;
217
218	/**
219	* Arranges for execution of the given tasks, returning normally
220	* when all complete or the given timeout expires, whichever
221	* happens first.
222	* Upon return, tasks that have not completed are cancelled.
223	* Note that a <em>completed</em> task could have
224	* terminated either normally or by throwing an exception.
225	* @param tasks the collection of tasks
226	* @param timeout the maximum time to wait
227	* @return A list of Futures representing the tasks. If the
228	* operation did not time out, each
229	* task will have completed. If it did time out, some of
230	* thiese tasks will not have completed.
231	* @param unit the time unit of the timeout argument
232	* @throws InterruptedException if interrupted while waiting, in
233	* which case unfinished tasks are cancelled.
234	* @throws NullPointerException if tasks or unit null
235	*/
236	List<Future<?>> runAll(Collection<Runnable> tasks,
237	long timeout, TimeUnit unit)
238	throws InterruptedException;
239
240	/**
241	* Arranges for execution of the given tasks, returning when at
242	* least one of them has completed.
243	* Upon return, tasks that have not completed are cancelled.
244	* Note that a <em>completed</em> task could have
245	* terminated either normally or by throwing an exception.
246	* @param tasks the collection of tasks
247	* @return A list of Futures representing the tasks. If the task
248	* list is non-empty, the first element of this list is known to
249	* have completed. Other tasks may or may not have also completed.
250	* @throws InterruptedException if interrupted while waiting, in
251	* which case unfinished tasks are cancelled.
252	* @throws NullPointerException if tasks null
253	*/
254
255	<T> List<Future<T>> callAny(Collection<Callable<T>> tasks)
256	throws InterruptedException;
257
258	/**
259	* Arranges for execution of the given tasks, returning when at
260	* least one of them has completed or the given timeout expires.
261	* Upon return, tasks that have not completed are cancelled.
262	* Note that a <em>completed</em> task could have
263	* terminated either normally or by throwing an exception.
264	* @param tasks the collection of tasks
265	* @param timeout the maximum time to wait
266	* @param unit the time unit of the timeout argument
267	* @return A list of Futures representing the tasks. If the task
268	* list is non-empty and the operation did not time out, the first
269	* element of this list is known to have completed. Other tasks
270	* may or may not have also completed. If the operation timed out,
271	* none of the tasks will have completed.
272	* @throws InterruptedException if interrupted while waiting, in
273	* which case unfinished tasks are cancelled.
274	* @throws NullPointerException if tasks or unit null
275	*/
276	<T> List<Future<T>> callAny(Collection<Callable<T>> tasks,
277	long timeout, TimeUnit unit)
278	throws InterruptedException;
279
280	/**
281	* Arranges for execution of the given tasks, returning their results
282	* when all complete.
283	* Note that a <em>completed</em> task could have
284	* terminated either normally or by throwing an exception.
285	* @param tasks the collection of tasks
286	* @return A list of Futures representing the tasks, each
287	* of which has completed.
288	* @throws InterruptedException if interrupted while waiting, in
289	* which case unfinished tasks are cancelled.
290	* @throws NullPointerException if tasks null
291	*/
292
293	<T> List<Future<T>> callAll(Collection<Callable<T>> tasks)
294	throws InterruptedException;
295
296	/**
297	* Arranges for execution of the given tasks, returning their results
298	* when all complete or the timeout expires, whichever happens first.
299	* Upon return, tasks that have not completed are cancelled.
300	* Note that a <em>completed</em> task could have
301	* terminated either normally or by throwing an exception.
302	* @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	* @return A list of Futures representing the tasks. If the
306	* operation did not time out, each
307	* task will have completed. If it did time out, some of
308	* thiese tasks will not have completed.
309	* @throws InterruptedException if interrupted while waiting, in
310	* which case unfinished tasks are cancelled.
311	* @throws NullPointerException if tasks or unit null
312	*/
313	<T> List<Future<T>> callAll(Collection<Callable<T>> tasks,
314	long timeout, TimeUnit unit)
315	throws InterruptedException;
316
317	}