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 // BEGIN android-note 42 // removed security manager docs 43 // END android-note 44 45 /** 46 * An {@link Executor} that provides methods to manage termination and 47 * methods that can produce a {@link Future} for tracking progress of 48 * one or more asynchronous tasks. 49 * 50 * <p>An {@code ExecutorService} can be shut down, which will cause 51 * it to reject new tasks. Two different methods are provided for 52 * shutting down an {@code ExecutorService}. The {@link #shutdown} 53 * method will allow previously submitted tasks to execute before 54 * terminating, while the {@link #shutdownNow} method prevents waiting 55 * tasks from starting and attempts to stop currently executing tasks. 56 * Upon termination, an executor has no tasks actively executing, no 57 * tasks awaiting execution, and no new tasks can be submitted. An 58 * unused {@code ExecutorService} should be shut down to allow 59 * reclamation of its resources. 60 * 61 * <p>Method {@code submit} extends base method {@link 62 * Executor#execute(Runnable)} by creating and returning a {@link Future} 63 * that can be used to cancel execution and/or wait for completion. 64 * Methods {@code invokeAny} and {@code invokeAll} perform the most 65 * commonly useful forms of bulk execution, executing a collection of 66 * tasks and then waiting for at least one, or all, to 67 * complete. (Class {@link ExecutorCompletionService} can be used to 68 * write customized variants of these methods.) 69 * 70 * <p>The {@link Executors} class provides factory methods for the 71 * executor services provided in this package. 72 * 73 * <h2>Usage Examples</h2> 74 * 75 * Here is a sketch of a network service in which threads in a thread 76 * pool service incoming requests. It uses the preconfigured {@link 77 * Executors#newFixedThreadPool} factory method: 78 * 79 * <pre> {@code 80 * class NetworkService implements Runnable { 81 * private final ServerSocket serverSocket; 82 * private final ExecutorService pool; 83 * 84 * public NetworkService(int port, int poolSize) 85 * throws IOException { 86 * serverSocket = new ServerSocket(port); 87 * pool = Executors.newFixedThreadPool(poolSize); 88 * } 89 * 90 * public void run() { // run the service 91 * try { 92 * for (;;) { 93 * pool.execute(new Handler(serverSocket.accept())); 94 * } 95 * } catch (IOException ex) { 96 * pool.shutdown(); 97 * } 98 * } 99 * } 100 * 101 * class Handler implements Runnable { 102 * private final Socket socket; 103 * Handler(Socket socket) { this.socket = socket; } 104 * public void run() { 105 * // read and service request on socket 106 * } 107 * }}</pre> 108 * 109 * An {@code ExecutorService} may also be established and closed 110 * (shutdown, blocking until terminated) as follows; illustrating with 111 * a different {@code Executors} factory method: 112 * 113 * <pre> {@code 114 * try (ExecutorService e = Executors.newWorkStealingPool()) { 115 * // submit or execute many tasks with e ... 116 * }}</pre> 117 * 118 * Further customization is also possible. For example, the following 119 * method shuts down an {@code ExecutorService} in two phases, first 120 * by calling {@code shutdown} to reject incoming tasks, and then 121 * calling {@code shutdownNow}, if necessary, to cancel any lingering 122 * tasks: 123 * 124 * <pre> {@code 125 * void shutdownAndAwaitTermination(ExecutorService pool) { 126 * pool.shutdown(); // Disable new tasks from being submitted 127 * try { 128 * // Wait a while for existing tasks to terminate 129 * if (!pool.awaitTermination(60, TimeUnit.SECONDS)) { 130 * pool.shutdownNow(); // Cancel currently executing tasks 131 * // Wait a while for tasks to respond to being cancelled 132 * if (!pool.awaitTermination(60, TimeUnit.SECONDS)) 133 * System.err.println("Pool did not terminate"); 134 * } 135 * } catch (InterruptedException ex) { 136 * // (Re-)Cancel if current thread also interrupted 137 * pool.shutdownNow(); 138 * // Preserve interrupt status 139 * Thread.currentThread().interrupt(); 140 * } 141 * }}</pre> 142 * 143 * <p>Memory consistency effects: Actions in a thread prior to the 144 * submission of a {@code Runnable} or {@code Callable} task to an 145 * {@code ExecutorService} 146 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 147 * any actions taken by that task, which in turn <i>happen-before</i> the 148 * result is retrieved via {@code Future.get()}. 149 * 150 * @since 1.5 151 * @author Doug Lea 152 */ 153 public interface ExecutorService extends Executor, AutoCloseable { 154 155 /** 156 * Initiates an orderly shutdown in which previously submitted 157 * tasks are executed, but no new tasks will be accepted. 158 * Invocation has no additional effect if already shut down. 159 * 160 * <p>This method does not wait for previously submitted tasks to 161 * complete execution. Use {@link #awaitTermination awaitTermination} 162 * to do that. 163 */ shutdown()164 void shutdown(); 165 166 /** 167 * Attempts to stop all actively executing tasks, halts the 168 * processing of waiting tasks, and returns a list of the tasks 169 * that were awaiting execution. 170 * 171 * <p>This method does not wait for actively executing tasks to 172 * terminate. Use {@link #awaitTermination awaitTermination} to 173 * do that. 174 * 175 * <p>There are no guarantees beyond best-effort attempts to stop 176 * processing actively executing tasks. For example, typical 177 * implementations will cancel via {@link Thread#interrupt}, so any 178 * task that fails to respond to interrupts may never terminate. 179 * 180 * @return list of tasks that never commenced execution 181 */ shutdownNow()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 */ isShutdown()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 */ isTerminated()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 */ awaitTermination(long timeout, TimeUnit unit)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 */ submit(Callable<T> task)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 */ submit(Runnable task, T result)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 */ submit(Runnable task)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 */ invokeAll(Collection<? extends Callable<T>> tasks)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 */ invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)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 */ invokeAny(Collection<? extends Callable<T>> tasks)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 */ invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)368 <T> T invokeAny(Collection<? extends Callable<T>> tasks, 369 long timeout, TimeUnit unit) 370 throws InterruptedException, ExecutionException, TimeoutException; 371 372 /** 373 * Initiates an orderly shutdown in which previously submitted tasks are 374 * executed, but no new tasks will be accepted. This method waits until all 375 * tasks have completed execution and the executor has terminated. 376 * 377 * <p> If interrupted while waiting, this method stops all executing tasks as 378 * if by invoking {@link #shutdownNow()}. It then continues to wait until all 379 * actively executing tasks have completed. Tasks that were awaiting 380 * execution are not executed. The interrupt status will be re-asserted 381 * before this method returns. 382 * 383 * <p> If already terminated, invoking this method has no effect. 384 * 385 * @implSpec 386 * The default implementation invokes {@code shutdown()} and waits for tasks 387 * to complete execution with {@code awaitTermination}. 388 * 389 * @throws SecurityException if a security manager exists and 390 * shutting down this ExecutorService may manipulate 391 * threads that the caller is not permitted to modify 392 * because it does not hold {@link 393 * java.lang.RuntimePermission}{@code ("modifyThread")}, 394 * or the security manager's {@code checkAccess} method 395 * denies access. 396 * @since 19 397 */ 398 // TODO(b/369520931): Add desugaring support for this method. 399 @Override close()400 default void close() { 401 boolean terminated = isTerminated(); 402 if (!terminated) { 403 shutdown(); 404 boolean interrupted = false; 405 while (!terminated) { 406 try { 407 terminated = awaitTermination(1L, TimeUnit.DAYS); 408 } catch (InterruptedException e) { 409 if (!interrupted) { 410 shutdownNow(); 411 interrupted = true; 412 } 413 } 414 } 415 if (interrupted) { 416 Thread.currentThread().interrupt(); 417 } 418 } 419 } 420 } 421