Source for java.util.concurrent.ExecutorService

   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: }