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 }