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 }