ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/concurrent/ExecutorService.java

Comparing jsr166/src/main/java/util/concurrent/ExecutorService.java (file contents):
Revision 1.16 by dl, Wed Dec 17 17:00:24 2003 UTC vs.
Revision 1.17 by dl, Fri Dec 19 14:42:25 2003 UTC

#	Line 13 | Line 13 | import java.security.PrivilegedException
13
14		/**
15		* An <tt>Executor</tt> that provides methods to manage termination
16	<	* and those that can produce a {@link Future} for tracking
16	>	* and methods that can produce a {@link Future} for tracking
17		* progress of one or more asynchronous tasks.
18	+	* <p>
19	+	*
20		* 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		* executing, no tasks are awaiting execution, and no new tasks can be
24		* submitted.
25		*
26	+	* <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		* <p>The {@link Executors} class provides factory methods for the
36		* executor services provided in this package.
37		*
#	Line 29 | Line 40 | import java.security.PrivilegedException
40		*/
41		public interface ExecutorService extends Executor {
42
43	+
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		/**
108		* Submits a Runnable task for execution and returns a Future
109		* representing that task.
110		*
111		* @param task the task to submit
112		* @param result the result to return upon completion
113	<	* If you do not need a particular result, consider using <tt>Boolean.TRUE</tt>.
113	>	* If you do not need a particular result, consider using
114	>	* the form: <tt>Future&lt;?&gt; cancellationHandle = e.submit(task, null)</tt>.
115		* @return a Future representing pending completion of the task,
116		* and whose <tt>get()</tt> method will return the given value
117		* upon completion
#	Line 55 | Line 131 | public interface ExecutorService extends
131		*/
132		<T> Future<T> submit(Callable<T> task);
133
58	–	/**
59	–	* Executes a Runnable task and blocks until it completes normally
60	–	* or throws an exception.
61	–	*
62	–	* @param task the task to submit
63	–	* @throws RejectedExecutionException if task cannot be scheduled
64	–	* for execution
65	–	* @throws ExecutionException if the task encountered an exception
66	–	* while executing
67	–	*/
68	–	void invoke(Runnable task) throws ExecutionException, InterruptedException;
69	–
70	–	/**
71	–	* Executes a value-returning task and blocks until it returns a
72	–	* value or throws an exception.
73	–	*
74	–	* @param task the task to submit
75	–	* @return a Future representing pending completion of the task
76	–	* @throws RejectedExecutionException if task cannot be scheduled
77	–	* for execution
78	–	* @throws InterruptedException if interrupted while waiting for
79	–	* completion
80	–	* @throws ExecutionException if the task encountered an exception
81	–	* while executing
82	–	*/
83	–	<T> T invoke(Callable<T> task) throws ExecutionException, InterruptedException;
84	–
134
135		/**
136		* Submits a privileged action for execution under the current
#	Line 107 | Line 156 | public interface ExecutorService extends
156		*/
157		Future<Object> submit(PrivilegedExceptionAction action);
158
110	–
111	–	/**
112	–	* Initiates an orderly shutdown in which previously submitted
113	–	* tasks are executed, but no new tasks will be
114	–	* accepted. Invocation has no additional effect if already shut
115	–	* down.
116	–	* @throws SecurityException if a security manager exists and
117	–	* shutting down this ExecutorService manipulates threads
118	–	* that the caller is not permitted to access.
119	–	*/
120	–	void shutdown();
121	–
122	–	/**
123	–	* Attempts to stop all actively executing tasks, halts the
124	–	* processing of waiting tasks, and returns a list of the tasks that were
125	–	* awaiting execution.
126	–	*
127	–	* <p>There are no guarantees beyond best-effort attempts to stop
128	–	* processing actively executing tasks.  For example, typical
129	–	* implementations will cancel via {@link Thread#interrupt}, so if any
130	–	* tasks mask or fail to respond to interrupts, they may never terminate.
131	–	*
132	–	* @return list of tasks that never commenced execution
133	–	* @throws SecurityException if a security manager exists and
134	–	* shutting down this ExecutorService manipulates threads
135	–	* that the caller is not permitted to access.
136	–	*/
137	–	List<Runnable> shutdownNow();
138	–
139	–	/**
140	–	* Returns <tt>true</tt> if this executor has been shut down.
141	–	*
142	–	* @return <tt>true</tt> if this executor has been shut down
143	–	*/
144	–	boolean isShutdown();
145	–
159		/**
160	<	* Returns <tt>true</tt> if all tasks have completed following shut down.
161	<	* Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
149	<	* either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
160	>	* Executes a Runnable task and blocks until it completes normally
161	>	* or throws an exception.
162		*
163	<	* @return <tt>true</tt> if all tasks have completed following shut down
163	>	* @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		*/
169	<	boolean isTerminated();
169	>	void invoke(Runnable task) throws ExecutionException, InterruptedException;
170
171		/**
172	<	* Blocks until all tasks have completed execution after a shutdown
173	<	* request, or the timeout occurs, or the current thread is
158	<	* interrupted, whichever happens first.
172	>	* Executes a value-returning task and blocks until it returns a
173	>	* value or throws an exception.
174		*
175	<	* @param timeout the maximum time to wait
176	<	* @param unit the time unit of the timeout argument
177	<	* @return <tt>true</tt> if this executor terminated and <tt>false</tt>
178	<	* if the timeout elapsed before termination
179	<	* @throws InterruptedException if interrupted while waiting
175	>	* @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		*/
184	<	boolean awaitTermination(long timeout, TimeUnit unit)
167	<	throws InterruptedException;
168	<
169	<
184	>	<T> T invoke(Callable<T> task) throws ExecutionException, InterruptedException;
185
186		/**
187	<	* Arranges for execution of the given tasks, returning when
187	>	* Executes the given tasks, returning when
188		* all of them complete.
189		* Note that a <em>completed</em> task could have
190		* terminated either normally or by throwing an exception.
191		* @param tasks the collection of tasks
192		* @param result value for each task to return upon completion.
193	<	* If you do not need a particular result, consider using <tt>Boolean.TRUE</tt>.
193	>	* If you do not need a particular result, consider using <tt>null</tt>.
194		* @return A list of Futures representing the tasks, in the same
195		* sequential order as as produced by the iterator for the given task list, each of which has
196		* completed.
#	Line 189 | Line 204 | public interface ExecutorService extends
204		throws InterruptedException;
205
206		/**
207	<	* Arranges for execution of the given tasks, returning normally
207	>	* Executes the given tasks, returning normally
208		* when all complete or the given timeout expires, whichever
209		* happens first.
210		* Upon return, tasks that have not completed are cancelled.
#	Line 197 | Line 212 | public interface ExecutorService extends
212		* terminated either normally or by throwing an exception.
213		* @param tasks the collection of tasks
214		* @param result value for each task to return upon completion.
215	<	* If you do not need a particular result, consider using <tt>Boolean.TRUE</tt>.
215	>	* If you do not need a particular result, consider using <tt>null</tt>.
216		* @param timeout the maximum time to wait
217		* @return A list of Futures representing the tasks, in the same
218		* sequential order as as produced by the iterator for the given task list. If the operation did
#	Line 206 | Line 221 | public interface ExecutorService extends
221		* @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	<	* @throws NullPointerException if tasks, any or its elements, or unit are <tt>null</tt>
224	>	* @throws NullPointerException if tasks, any of its elements, or unit are <tt>null</tt>
225		* @throws RejectedExecutionException if any task cannot be scheduled
226		* for execution
227		*/
#	Line 216 | Line 231 | public interface ExecutorService extends
231
232
233		/**
234	<	* Arranges for execution of the given tasks, returning their results
234	>	* Executes the given tasks, returning their results
235		* when all complete.
236		* Note that a <em>completed</em> task could have
237		* terminated either normally or by throwing an exception.
#	Line 235 | Line 250 | public interface ExecutorService extends
250		throws InterruptedException;
251
252		/**
253	<	* Arranges for execution of the given tasks, returning their results
253	>	* Executes the given tasks, returning their results
254		* when all complete or the timeout expires, whichever happens first.
255		* Upon return, tasks that have not completed are cancelled.
256		* Note that a <em>completed</em> task could have
#	Line 249 | Line 264 | public interface ExecutorService extends
264		* out, some of thiese tasks will not have completed.
265		* @throws InterruptedException if interrupted while waiting, in
266		* which case unfinished tasks are cancelled.
267	<	* @throws NullPointerException if tasks, any or its elements, or
267	>	* @throws NullPointerException if tasks, any of its elements, or
268		* unit are <tt>null</tt>
269		* @throws RejectedExecutionException if any task cannot be scheduled
270		* for execution
#	Line 260 | Line 275 | public interface ExecutorService extends
275
276
277		/**
278	<	* Arranges for execution of the given tasks, returning the result
278	>	* Executes the given tasks, returning the result
279		* 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.
#	Line 279 | Line 294 | public interface ExecutorService extends
294		throws InterruptedException, ExecutionException;
295
296		/**
297	<	* Arranges for execution of the given tasks, returning the result
297	>	* Executes the given tasks, returning the result
298		* 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
#	Line 289 | Line 304 | public interface ExecutorService extends
304		* @param unit the time unit of the timeout argument
305		* @return The result returned by one of the tasks.
306		* @throws InterruptedException if interrupted while waiting
307	<	* @throws NullPointerException if tasks, any or its elements, or
307	>	* @throws NullPointerException if tasks, any of its elements, or
308		* unit are <tt>null</tt>
309		* @throws TimeoutException if the given timeout elapses before
310		* any task successfully completes
#	Line 302 | Line 317 | public interface ExecutorService extends
317		throws InterruptedException, ExecutionException, TimeoutException;
318
319		/**
320	<	* Arranges for execution of the given tasks, returning the given
320	>	* Executes the given tasks, returning the given
321		* 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.
#	Line 322 | Line 337 | public interface ExecutorService extends
337		throws InterruptedException, ExecutionException;
338
339		/**
340	<	* Arranges for execution of the given tasks, returning the given result
340	>	* Executes the given tasks, returning the given result
341		* 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
#	Line 333 | Line 348 | public interface ExecutorService extends
348		* @param unit the time unit of the timeout argument
349		* @return the given result
350		* @throws InterruptedException if interrupted while waiting
351	<	* @throws NullPointerException if tasks, any or its elements, or
351	>	* @throws NullPointerException if tasks, any of its elements, or
352		* unit are <tt>null</tt>
353		* @throws TimeoutException if the given timeout elapses before
354		* any task successfully completes

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines