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.
     * @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.
     * @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. 
     * @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.
     * @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.
     * @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.
     * @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.
     * @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.
     * @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.11
Committed:	Sun Dec 14 15:50:13 2003 UTC (20 years, 5 months ago) by dl
Branch:	MAIN
Changes since 1.10:	+141 -1 lines
Log Message:	Added 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	* @param tasks the collection of tasks
168	* @return A list of Futures representing the tasks. If the task
169	* list is non-empty, the first element of this list is known to
170	* have completed. Other tasks may or may not have also completed.
171	* @throws InterruptedException if interrupted while waiting, in
172	* which case unfinished tasks are cancelled.
173	* @throws NullPointerException if tasks null
174	*/
175	List<Future<?>> runAny(Collection<Runnable> tasks)
176	throws InterruptedException;
177
178	/**
179	* Arranges for execution of the given tasks, returning when at
180	* least one of them has completed or the given timeout expires.
181	* Upon return, tasks that have not completed are cancelled.
182	* @param tasks the collection of tasks
183	* @param timeout the maximum time to wait
184	* @param unit the time unit of the timeout argument
185	* @return A list of Futures representing the tasks. If the task
186	* list is non-empty and the operation did not time out, the first
187	* element of this list is known to have completed. Other tasks
188	* may or may not have also completed. If the operation timed out,
189	* none of the tasks will have completed.
190	* @throws InterruptedException if interrupted while waiting, in
191	* which case unfinished tasks are cancelled.
192	* @throws NullPointerException if tasks or unit null
193	*/
194	List<Future<?>> runAny(Collection<Runnable> tasks,
195	long timeout, TimeUnit unit)
196	throws InterruptedException;
197
198
199	/**
200	* Arranges for execution of the given tasks, returning when
201	* all of them complete.
202	* @param tasks the collection of tasks
203	* @return A list of Futures representing the tasks, each
204	* of which has completed.
205	* @throws InterruptedException if interrupted while waiting, in
206	* which case unfinished tasks are cancelled.
207	* @throws NullPointerException if tasks null
208	*/
209	List<Future<?>> runAll(Collection<Runnable> tasks)
210	throws InterruptedException;
211
212	/**
213	* Arranges for execution of the given tasks, returning normally
214	* when all complete or the given timeout expires, whichever
215	* happens first.
216	* Upon return, tasks that have not completed are cancelled.
217	* @param tasks the collection of tasks
218	* @param timeout the maximum time to wait
219	* @return A list of Futures representing the tasks. If the
220	* operation did not time out, each
221	* task will have completed. If it did time out, some of
222	* thiese tasks will not have completed.
223	* @param unit the time unit of the timeout argument
224	* @throws InterruptedException if interrupted while waiting, in
225	* which case unfinished tasks are cancelled.
226	* @throws NullPointerException if tasks or unit null
227	*/
228	List<Future<?>> runAll(Collection<Runnable> tasks,
229	long timeout, TimeUnit unit)
230	throws InterruptedException;
231
232	/**
233	* Arranges for execution of the given tasks, returning when at
234	* least one of them has completed.
235	* Upon return, tasks that have not completed are cancelled.
236	* @param tasks the collection of tasks
237	* @return A list of Futures representing the tasks. If the task
238	* list is non-empty, the first element of this list is known to
239	* have completed. Other tasks may or may not have also completed.
240	* @throws InterruptedException if interrupted while waiting, in
241	* which case unfinished tasks are cancelled.
242	* @throws NullPointerException if tasks null
243	*/
244
245	<T> List<Future<T>> callAny(Collection<Callable<T>> tasks)
246	throws InterruptedException;
247
248	/**
249	* Arranges for execution of the given tasks, returning when at
250	* least one of them has completed or the given timeout expires.
251	* Upon return, tasks that have not completed are cancelled.
252	* @param tasks the collection of tasks
253	* @param timeout the maximum time to wait
254	* @param unit the time unit of the timeout argument
255	* @return A list of Futures representing the tasks. If the task
256	* list is non-empty and the operation did not time out, the first
257	* element of this list is known to have completed. Other tasks
258	* may or may not have also completed. If the operation timed out,
259	* none of the tasks will have completed.
260	* @throws InterruptedException if interrupted while waiting, in
261	* which case unfinished tasks are cancelled.
262	* @throws NullPointerException if tasks or unit null
263	*/
264	<T> List<Future<T>> callAny(Collection<Callable<T>> tasks,
265	long timeout, TimeUnit unit)
266	throws InterruptedException;
267
268	/**
269	* Arranges for execution of the given tasks, returning their results
270	* when all complete.
271	* @param tasks the collection of tasks
272	* @return A list of Futures representing the tasks, each
273	* of which has completed.
274	* @throws InterruptedException if interrupted while waiting, in
275	* which case unfinished tasks are cancelled.
276	* @throws NullPointerException if tasks null
277	*/
278
279	<T> List<Future<T>> callAll(Collection<Callable<T>> tasks)
280	throws InterruptedException;
281
282	/**
283	* Arranges for execution of the given tasks, returning their results
284	* when all complete or the timeout expires, whichever happens first.
285	* Upon return, tasks that have not completed are cancelled.
286	* @param tasks the collection of tasks
287	* @param timeout the maximum time to wait
288	* @param unit the time unit of the timeout argument
289	* @return A list of Futures representing the tasks. If the
290	* operation did not time out, each
291	* task will have completed. If it did time out, some of
292	* thiese tasks will not have completed.
293	* @throws InterruptedException if interrupted while waiting, in
294	* which case unfinished tasks are cancelled.
295	* @throws NullPointerException if tasks or unit null
296	*/
297	<T> List<Future<T>> callAll(Collection<Callable<T>> tasks,
298	long timeout, TimeUnit unit)
299	throws InterruptedException;
300
301	}