ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ExecutorService.java
Revision: 1.34
Committed: Wed May 18 06:51:43 2005 UTC (19 years ago) by jsr166
Branch: MAIN
Changes since 1.33: +0 -1 lines
Log Message: 
whitespace

File Contents

# User Rev Content
1 dl 1.1 /*
2     * Written by Doug Lea with assistance from members of JCP JSR-166
3 dl 1.22 * Expert Group and released to the public domain, as explained at
4     * http://creativecommons.org/licenses/publicdomain
5 dl 1.1 */
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.25 * An {@link Executor} that provides methods to manage termination and
16 dl 1.20 * methods that can produce a {@link Future} for tracking progress of
17 jsr166 1.33 * one or more asynchronous tasks.
18 dl 1.17 *
19 dl 1.25 * <p>
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.20 * <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.)
34 dl 1.17 *
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 dl 1.23 * <h3>Usage Example</h3>
39     *
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:
43     *
44     * <pre>
45     * class NetworkService {
46     * private final ServerSocket serverSocket;
47     * private final ExecutorService pool;
48     *
49     * public NetworkService(int port, int poolSize) throws IOException {
50     * serverSocket = new ServerSocket(port);
51     * pool = Executors.newFixedThreadPool(poolSize);
52     * }
53 jsr166 1.33 *
54 dl 1.23 * public void serve() {
55     * try {
56     * for (;;) {
57     * pool.execute(new Handler(serverSocket.accept()));
58     * }
59     * } catch (IOException ex) {
60     * pool.shutdown();
61     * }
62     * }
63     * }
64     *
65     * class Handler implements Runnable {
66     * private final Socket socket;
67     * Handler(Socket socket) { this.socket = socket; }
68     * public void run() {
69     * // read and service request
70     * }
71     * }
72     * </pre>
73 dl 1.1 * @since 1.5
74 dl 1.5 * @author Doug Lea
75 dl 1.1 */
76     public interface ExecutorService extends Executor {
77 tim 1.8
78 dl 1.17 /**
79     * Initiates an orderly shutdown in which previously submitted
80     * tasks are executed, but no new tasks will be
81     * accepted. Invocation has no additional effect if already shut
82     * down.
83     * @throws SecurityException if a security manager exists and
84     * shutting down this ExecutorService may manipulate threads that
85     * the caller is not permitted to modify because it does not hold
86     * {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
87     * or the security manager's <tt>checkAccess</tt> method denies access.
88     */
89     void shutdown();
90    
91     /**
92     * Attempts to stop all actively executing tasks, halts the
93     * processing of waiting tasks, and returns a list of the tasks that were
94 jsr166 1.33 * awaiting execution.
95     *
96 dl 1.17 * <p>There are no guarantees beyond best-effort attempts to stop
97     * processing actively executing tasks. For example, typical
98     * implementations will cancel via {@link Thread#interrupt}, so if any
99     * tasks mask or fail to respond to interrupts, they may never terminate.
100     *
101     * @return list of tasks that never commenced execution
102     * @throws SecurityException if a security manager exists and
103     * shutting down this ExecutorService may manipulate threads that
104     * the caller is not permitted to modify because it does not hold
105     * {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
106     * or the security manager's <tt>checkAccess</tt> method denies access.
107     */
108     List<Runnable> shutdownNow();
109    
110     /**
111     * Returns <tt>true</tt> if this executor has been shut down.
112     *
113     * @return <tt>true</tt> if this executor has been shut down
114     */
115     boolean isShutdown();
116    
117     /**
118     * Returns <tt>true</tt> if all tasks have completed following shut down.
119     * Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
120     * either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
121     *
122     * @return <tt>true</tt> if all tasks have completed following shut down
123     */
124     boolean isTerminated();
125    
126     /**
127     * Blocks until all tasks have completed execution after a shutdown
128     * request, or the timeout occurs, or the current thread is
129 dl 1.29 * interrupted, whichever happens first. To wait "forever"
130     * use <tt>awaitTermination(Long.MAX_VALUE, TimeUnit.NANOSECONDS)</tt>.
131 dl 1.17 *
132     * @param timeout the maximum time to wait
133     * @param unit the time unit of the timeout argument
134     * @return <tt>true</tt> if this executor terminated and <tt>false</tt>
135     * if the timeout elapsed before termination
136     * @throws InterruptedException if interrupted while waiting
137     */
138     boolean awaitTermination(long timeout, TimeUnit unit)
139     throws InterruptedException;
140    
141    
142 tim 1.8 /**
143 dl 1.30 * Submits a value-returning task for execution and returns a
144 dl 1.31 * Future representing the pending results of the task. The
145 dl 1.32 * Future's <tt>get</tt> method will return the task's result upon
146 dl 1.30 * <em>successful</em> completion.
147 tim 1.8 *
148 dl 1.19 * <p>
149 dl 1.20 * If you would like to immediately block waiting
150 dl 1.19 * for a task, you can use constructions of the form
151     * <tt>result = exec.submit(aCallable).get();</tt>
152 dl 1.20 *
153     * <p> Note: The {@link Executors} class includes a set of methods
154     * that can convert some other common closure-like objects,
155     * for example, {@link java.security.PrivilegedAction} to
156     * {@link Callable} form so they can be submitted.
157     *
158 tim 1.8 * @param task the task to submit
159     * @return a Future representing pending completion of the task
160     * @throws RejectedExecutionException if task cannot be scheduled
161     * for execution
162 dl 1.20 * @throws NullPointerException if task null
163 tim 1.8 */
164     <T> Future<T> submit(Callable<T> task);
165    
166     /**
167 dl 1.30 * Submits a Runnable task for execution and returns a Future
168 jsr166 1.33 * representing that task. The Future's <tt>get</tt> method will
169 dl 1.31 * return the given result upon successful completion.
170 dl 1.20 *
171     * @param task the task to submit
172     * @param result the result to return
173 dl 1.31 * @return a Future representing pending completion of the task
174 dl 1.20 * @throws RejectedExecutionException if task cannot be scheduled
175     * for execution
176 jsr166 1.33 * @throws NullPointerException if task null
177 dl 1.20 */
178     <T> Future<T> submit(Runnable task, T result);
179    
180     /**
181 jsr166 1.33 * Submits a Runnable task for execution and returns a Future
182     * representing that task. The Future's <tt>get</tt> method will
183 dl 1.32 * return <tt>null</tt> upon successful completion.
184 dl 1.1 *
185 dl 1.17 * @param task the task to submit
186 dl 1.31 * @return a Future representing pending completion of the task
187 dl 1.17 * @throws RejectedExecutionException if task cannot be scheduled
188     * for execution
189 dl 1.20 * @throws NullPointerException if task null
190 dl 1.1 */
191 dl 1.18 Future<?> submit(Runnable task);
192 dl 1.15
193 dl 1.11 /**
194 dl 1.27 * Executes the given tasks, returning a list of Futures holding
195 jsr166 1.33 * their status and results when all complete.
196     * {@link Future#isDone} is <tt>true</tt> for each
197 dl 1.27 * element of the returned list.
198 dl 1.12 * Note that a <em>completed</em> task could have
199     * terminated either normally or by throwing an exception.
200 dl 1.21 * The results of this method are undefined if the given
201     * collection is modified while this operation is in progress.
202 dl 1.11 * @param tasks the collection of tasks
203 dl 1.13 * @return A list of Futures representing the tasks, in the same
204 dl 1.21 * sequential order as produced by the iterator for the given task
205     * list, each of which has completed.
206 dl 1.11 * @throws InterruptedException if interrupted while waiting, in
207     * which case unfinished tasks are cancelled.
208 dl 1.13 * @throws NullPointerException if tasks or any of its elements are <tt>null</tt>
209     * @throws RejectedExecutionException if any task cannot be scheduled
210     * for execution
211 dl 1.11 */
212 dl 1.16 <T> List<Future<T>> invokeAll(Collection<Callable<T>> tasks)
213 dl 1.11 throws InterruptedException;
214    
215     /**
216 dl 1.27 * Executes the given tasks, returning a list of Futures holding
217 jsr166 1.33 * their status and results
218 dl 1.15 * when all complete or the timeout expires, whichever happens first.
219 jsr166 1.33 * {@link Future#isDone} is <tt>true</tt> for each
220 dl 1.27 * element of the returned list.
221 dl 1.11 * Upon return, tasks that have not completed are cancelled.
222 dl 1.12 * Note that a <em>completed</em> task could have
223     * terminated either normally or by throwing an exception.
224 dl 1.21 * The results of this method are undefined if the given
225     * collection is modified while this operation is in progress.
226 dl 1.11 * @param tasks the collection of tasks
227     * @param timeout the maximum time to wait
228 dl 1.15 * @param unit the time unit of the timeout argument
229 dl 1.13 * @return A list of Futures representing the tasks, in the same
230 dl 1.26 * sequential order as produced by the iterator for the given
231 dl 1.21 * task list. If the operation did not time out, each task will
232 dl 1.28 * have completed. If it did time out, some of these tasks will
233 dl 1.21 * not have completed.
234 dl 1.11 * @throws InterruptedException if interrupted while waiting, in
235     * which case unfinished tasks are cancelled.
236 dl 1.17 * @throws NullPointerException if tasks, any of its elements, or
237 dl 1.15 * unit are <tt>null</tt>
238 dl 1.13 * @throws RejectedExecutionException if any task cannot be scheduled
239     * for execution
240 dl 1.11 */
241 jsr166 1.33 <T> List<Future<T>> invokeAll(Collection<Callable<T>> tasks,
242     long timeout, TimeUnit unit)
243 dl 1.11 throws InterruptedException;
244    
245     /**
246 dl 1.17 * Executes the given tasks, returning the result
247 dl 1.15 * of one that has completed successfully (i.e., without throwing
248     * an exception), if any do. Upon normal or exceptional return,
249     * tasks that have not completed are cancelled.
250 dl 1.21 * The results of this method are undefined if the given
251     * collection is modified while this operation is in progress.
252 dl 1.11 * @param tasks the collection of tasks
253 dl 1.15 * @return The result returned by one of the tasks.
254     * @throws InterruptedException if interrupted while waiting
255     * @throws NullPointerException if tasks or any of its elements
256     * are <tt>null</tt>
257     * @throws IllegalArgumentException if tasks empty
258     * @throws ExecutionException if no task successfully completes
259     * @throws RejectedExecutionException if tasks cannot be scheduled
260 dl 1.13 * for execution
261 dl 1.11 */
262 dl 1.15 <T> T invokeAny(Collection<Callable<T>> tasks)
263     throws InterruptedException, ExecutionException;
264 dl 1.11
265     /**
266 dl 1.17 * Executes the given tasks, returning the result
267 dl 1.15 * of one that has completed successfully (i.e., without throwing
268     * an exception), if any do before the given timeout elapses.
269     * Upon normal or exceptional return, tasks that have not
270     * completed are cancelled.
271 dl 1.21 * The results of this method are undefined if the given
272     * collection is modified while this operation is in progress.
273 dl 1.11 * @param tasks the collection of tasks
274     * @param timeout the maximum time to wait
275     * @param unit the time unit of the timeout argument
276 dl 1.15 * @return The result returned by one of the tasks.
277     * @throws InterruptedException if interrupted while waiting
278 dl 1.17 * @throws NullPointerException if tasks, any of its elements, or
279 dl 1.15 * unit are <tt>null</tt>
280     * @throws TimeoutException if the given timeout elapses before
281     * any task successfully completes
282     * @throws ExecutionException if no task successfully completes
283     * @throws RejectedExecutionException if tasks cannot be scheduled
284 dl 1.13 * for execution
285 dl 1.11 */
286 jsr166 1.33 <T> T invokeAny(Collection<Callable<T>> tasks,
287     long timeout, TimeUnit unit)
288 dl 1.15 throws InterruptedException, ExecutionException, TimeoutException;
289 dl 1.3
290 dl 1.1 }