lib/classpath/external/jsr166/java/util/concurrent/ExecutorService.java

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