View Javadoc
1   /*
2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3    *
4    * This code is free software; you can redistribute it and/or modify it
5    * under the terms of the GNU General Public License version 2 only, as
6    * published by the Free Software Foundation.  Oracle designates this
7    * particular file as subject to the "Classpath" exception as provided
8    * by Oracle in the LICENSE file that accompanied this code.
9    *
10   * This code is distributed in the hope that it will be useful, but WITHOUT
11   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
13   * version 2 for more details (a copy is included in the LICENSE file that
14   * accompanied this code).
15   *
16   * You should have received a copy of the GNU General Public License version
17   * 2 along with this work; if not, write to the Free Software Foundation,
18   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19   *
20   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21   * or visit www.oracle.com if you need additional information or have any
22   * questions.
23   */
24  
25  /*
26   * This file is available under and governed by the GNU General Public
27   * License version 2 only, as published by the Free Software Foundation.
28   * However, the following notice accompanied the original version of this
29   * file:
30   *
31   * Written by Doug Lea with assistance from members of JCP JSR-166
32   * Expert Group and released to the public domain, as explained at
33   * http://creativecommons.org/publicdomain/zero/1.0/
34   */
35  
36  package java.util.concurrent;
37  import java.util.List;
38  import java.util.Collection;
39  
40  /**
41   * An {@link Executor} that provides methods to manage termination and
42   * methods that can produce a {@link Future} for tracking progress of
43   * one or more asynchronous tasks.
44   *
45   * <p>An {@code ExecutorService} can be shut down, which will cause
46   * it to reject new tasks.  Two different methods are provided for
47   * shutting down an {@code ExecutorService}. The {@link #shutdown}
48   * method will allow previously submitted tasks to execute before
49   * terminating, while the {@link #shutdownNow} method prevents waiting
50   * tasks from starting and attempts to stop currently executing tasks.
51   * Upon termination, an executor has no tasks actively executing, no
52   * tasks awaiting execution, and no new tasks can be submitted.  An
53   * unused {@code ExecutorService} should be shut down to allow
54   * reclamation of its resources.
55   *
56   * <p>Method {@code submit} extends base method {@link
57   * Executor#execute(Runnable)} by creating and returning a {@link Future}
58   * that can be used to cancel execution and/or wait for completion.
59   * Methods {@code invokeAny} and {@code invokeAll} perform the most
60   * commonly useful forms of bulk execution, executing a collection of
61   * tasks and then waiting for at least one, or all, to
62   * complete. (Class {@link ExecutorCompletionService} can be used to
63   * write customized variants of these methods.)
64   *
65   * <p>The {@link Executors} class provides factory methods for the
66   * executor services provided in this package.
67   *
68   * <h3>Usage Examples</h3>
69   *
70   * Here is a sketch of a network service in which threads in a thread
71   * pool service incoming requests. It uses the preconfigured {@link
72   * Executors#newFixedThreadPool} factory method:
73   *
74   *  <pre> {@code
75   * class NetworkService implements Runnable {
76   *   private final ServerSocket serverSocket;
77   *   private final ExecutorService pool;
78   *
79   *   public NetworkService(int port, int poolSize)
80   *       throws IOException {
81   *     serverSocket = new ServerSocket(port);
82   *     pool = Executors.newFixedThreadPool(poolSize);
83   *   }
84   *
85   *   public void run() { // run the service
86   *     try {
87   *       for (;;) {
88   *         pool.execute(new Handler(serverSocket.accept()));
89   *       }
90   *     } catch (IOException ex) {
91   *       pool.shutdown();
92   *     }
93   *   }
94   * }
95   *
96   * class Handler implements Runnable {
97   *   private final Socket socket;
98   *   Handler(Socket socket) { this.socket = socket; }
99   *   public void run() {
100  *     // read and service request on socket
101  *   }
102  * }}</pre>
103  *
104  * The following method shuts down an {@code ExecutorService} in two phases,
105  * first by calling {@code shutdown} to reject incoming tasks, and then
106  * calling {@code shutdownNow}, if necessary, to cancel any lingering tasks:
107  *
108  *  <pre> {@code
109  * void shutdownAndAwaitTermination(ExecutorService pool) {
110  *   pool.shutdown(); // Disable new tasks from being submitted
111  *   try {
112  *     // Wait a while for existing tasks to terminate
113  *     if (!pool.awaitTermination(60, TimeUnit.SECONDS)) {
114  *       pool.shutdownNow(); // Cancel currently executing tasks
115  *       // Wait a while for tasks to respond to being cancelled
116  *       if (!pool.awaitTermination(60, TimeUnit.SECONDS))
117  *           System.err.println("Pool did not terminate");
118  *     }
119  *   } catch (InterruptedException ie) {
120  *     // (Re-)Cancel if current thread also interrupted
121  *     pool.shutdownNow();
122  *     // Preserve interrupt status
123  *     Thread.currentThread().interrupt();
124  *   }
125  * }}</pre>
126  *
127  * <p>Memory consistency effects: Actions in a thread prior to the
128  * submission of a {@code Runnable} or {@code Callable} task to an
129  * {@code ExecutorService}
130  * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
131  * any actions taken by that task, which in turn <i>happen-before</i> the
132  * result is retrieved via {@code Future.get()}.
133  *
134  * @since 1.5
135  * @author Doug Lea
136  */
137 public interface ExecutorService extends Executor {
138 
139     /**
140      * Initiates an orderly shutdown in which previously submitted
141      * tasks are executed, but no new tasks will be accepted.
142      * Invocation has no additional effect if already shut down.
143      *
144      * <p>This method does not wait for previously submitted tasks to
145      * complete execution.  Use {@link #awaitTermination awaitTermination}
146      * to do that.
147      *
148      * @throws SecurityException if a security manager exists and
149      *         shutting down this ExecutorService may manipulate
150      *         threads that the caller is not permitted to modify
151      *         because it does not hold {@link
152      *         java.lang.RuntimePermission}{@code ("modifyThread")},
153      *         or the security manager's {@code checkAccess} method
154      *         denies access.
155      */
156     void shutdown();
157 
158     /**
159      * Attempts to stop all actively executing tasks, halts the
160      * processing of waiting tasks, and returns a list of the tasks
161      * that were awaiting execution.
162      *
163      * <p>This method does not wait for actively executing tasks to
164      * terminate.  Use {@link #awaitTermination awaitTermination} to
165      * do that.
166      *
167      * <p>There are no guarantees beyond best-effort attempts to stop
168      * processing actively executing tasks.  For example, typical
169      * implementations will cancel via {@link Thread#interrupt}, so any
170      * task that fails to respond to interrupts may never terminate.
171      *
172      * @return list of tasks that never commenced execution
173      * @throws SecurityException if a security manager exists and
174      *         shutting down this ExecutorService may manipulate
175      *         threads that the caller is not permitted to modify
176      *         because it does not hold {@link
177      *         java.lang.RuntimePermission}{@code ("modifyThread")},
178      *         or the security manager's {@code checkAccess} method
179      *         denies access.
180      */
181     List<Runnable> shutdownNow();
182 
183     /**
184      * Returns {@code true} if this executor has been shut down.
185      *
186      * @return {@code true} if this executor has been shut down
187      */
188     boolean isShutdown();
189 
190     /**
191      * Returns {@code true} if all tasks have completed following shut down.
192      * Note that {@code isTerminated} is never {@code true} unless
193      * either {@code shutdown} or {@code shutdownNow} was called first.
194      *
195      * @return {@code true} if all tasks have completed following shut down
196      */
197     boolean isTerminated();
198 
199     /**
200      * Blocks until all tasks have completed execution after a shutdown
201      * request, or the timeout occurs, or the current thread is
202      * interrupted, whichever happens first.
203      *
204      * @param timeout the maximum time to wait
205      * @param unit the time unit of the timeout argument
206      * @return {@code true} if this executor terminated and
207      *         {@code false} if the timeout elapsed before termination
208      * @throws InterruptedException if interrupted while waiting
209      */
210     boolean awaitTermination(long timeout, TimeUnit unit)
211         throws InterruptedException;
212 
213     /**
214      * Submits a value-returning task for execution and returns a
215      * Future representing the pending results of the task. The
216      * Future's {@code get} method will return the task's result upon
217      * successful completion.
218      *
219      * <p>
220      * If you would like to immediately block waiting
221      * for a task, you can use constructions of the form
222      * {@code result = exec.submit(aCallable).get();}
223      *
224      * <p>Note: The {@link Executors} class includes a set of methods
225      * that can convert some other common closure-like objects,
226      * for example, {@link java.security.PrivilegedAction} to
227      * {@link Callable} form so they can be submitted.
228      *
229      * @param task the task to submit
230      * @param <T> the type of the task's result
231      * @return a Future representing pending completion of the task
232      * @throws RejectedExecutionException if the task cannot be
233      *         scheduled for execution
234      * @throws NullPointerException if the task is null
235      */
236     <T> Future<T> submit(Callable<T> task);
237 
238     /**
239      * Submits a Runnable task for execution and returns a Future
240      * representing that task. The Future's {@code get} method will
241      * return the given result upon successful completion.
242      *
243      * @param task the task to submit
244      * @param result the result to return
245      * @param <T> the type of the result
246      * @return a Future representing pending completion of the task
247      * @throws RejectedExecutionException if the task cannot be
248      *         scheduled for execution
249      * @throws NullPointerException if the task is null
250      */
251     <T> Future<T> submit(Runnable task, T result);
252 
253     /**
254      * Submits a Runnable task for execution and returns a Future
255      * representing that task. The Future's {@code get} method will
256      * return {@code null} upon <em>successful</em> completion.
257      *
258      * @param task the task to submit
259      * @return a Future representing pending completion of the task
260      * @throws RejectedExecutionException if the task cannot be
261      *         scheduled for execution
262      * @throws NullPointerException if the task is null
263      */
264     Future<?> submit(Runnable task);
265 
266     /**
267      * Executes the given tasks, returning a list of Futures holding
268      * their status and results when all complete.
269      * {@link Future#isDone} is {@code true} for each
270      * element of the returned list.
271      * Note that a <em>completed</em> task could have
272      * terminated either normally or by throwing an exception.
273      * The results of this method are undefined if the given
274      * collection is modified while this operation is in progress.
275      *
276      * @param tasks the collection of tasks
277      * @param <T> the type of the values returned from the tasks
278      * @return a list of Futures representing the tasks, in the same
279      *         sequential order as produced by the iterator for the
280      *         given task list, each of which has completed
281      * @throws InterruptedException if interrupted while waiting, in
282      *         which case unfinished tasks are cancelled
283      * @throws NullPointerException if tasks or any of its elements are {@code null}
284      * @throws RejectedExecutionException if any task cannot be
285      *         scheduled for execution
286      */
287     <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
288         throws InterruptedException;
289 
290     /**
291      * Executes the given tasks, returning a list of Futures holding
292      * their status and results
293      * when all complete or the timeout expires, whichever happens first.
294      * {@link Future#isDone} is {@code true} for each
295      * element of the returned list.
296      * Upon return, tasks that have not completed are cancelled.
297      * Note that a <em>completed</em> task could have
298      * terminated either normally or by throwing an exception.
299      * The results of this method are undefined if the given
300      * collection is modified while this operation is in progress.
301      *
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      * @param <T> the type of the values returned from the tasks
306      * @return a list of Futures representing the tasks, in the same
307      *         sequential order as produced by the iterator for the
308      *         given task list. If the operation did not time out,
309      *         each task will have completed. If it did time out, some
310      *         of these tasks will not have completed.
311      * @throws InterruptedException if interrupted while waiting, in
312      *         which case unfinished tasks are cancelled
313      * @throws NullPointerException if tasks, any of its elements, or
314      *         unit are {@code null}
315      * @throws RejectedExecutionException if any task cannot be scheduled
316      *         for execution
317      */
318     <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks,
319                                   long timeout, TimeUnit unit)
320         throws InterruptedException;
321 
322     /**
323      * Executes the given tasks, returning the result
324      * of one that has completed successfully (i.e., without throwing
325      * an exception), if any do. Upon normal or exceptional return,
326      * tasks that have not completed are cancelled.
327      * The results of this method are undefined if the given
328      * collection is modified while this operation is in progress.
329      *
330      * @param tasks the collection of tasks
331      * @param <T> the type of the values returned from the tasks
332      * @return the result returned by one of the tasks
333      * @throws InterruptedException if interrupted while waiting
334      * @throws NullPointerException if tasks or any element task
335      *         subject to execution is {@code null}
336      * @throws IllegalArgumentException if tasks is empty
337      * @throws ExecutionException if no task successfully completes
338      * @throws RejectedExecutionException if tasks cannot be scheduled
339      *         for execution
340      */
341     <T> T invokeAny(Collection<? extends Callable<T>> tasks)
342         throws InterruptedException, ExecutionException;
343 
344     /**
345      * Executes the given tasks, returning the result
346      * of one that has completed successfully (i.e., without throwing
347      * an exception), if any do before the given timeout elapses.
348      * Upon normal or exceptional return, tasks that have not
349      * completed are cancelled.
350      * The results of this method are undefined if the given
351      * collection is modified while this operation is in progress.
352      *
353      * @param tasks the collection of tasks
354      * @param timeout the maximum time to wait
355      * @param unit the time unit of the timeout argument
356      * @param <T> the type of the values returned from the tasks
357      * @return the result returned by one of the tasks
358      * @throws InterruptedException if interrupted while waiting
359      * @throws NullPointerException if tasks, or unit, or any element
360      *         task subject to execution is {@code null}
361      * @throws TimeoutException if the given timeout elapses before
362      *         any task successfully completes
363      * @throws ExecutionException if no task successfully completes
364      * @throws RejectedExecutionException if tasks cannot be scheduled
365      *         for execution
366      */
367     <T> T invokeAny(Collection<? extends Callable<T>> tasks,
368                     long timeout, TimeUnit unit)
369         throws InterruptedException, ExecutionException, TimeoutException;
370 }