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