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 * <h3>Usage Examples</h3> 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 * The following method shuts down an {@code ExecutorService} in two phases, 110 * first by calling {@code shutdown} to reject incoming tasks, and then 111 * calling {@code shutdownNow}, if necessary, to cancel any lingering tasks: 112 * 113 * <pre> {@code 114 * void shutdownAndAwaitTermination(ExecutorService pool) { 115 * pool.shutdown(); // Disable new tasks from being submitted 116 * try { 117 * // Wait a while for existing tasks to terminate 118 * if (!pool.awaitTermination(60, TimeUnit.SECONDS)) { 119 * pool.shutdownNow(); // Cancel currently executing tasks 120 * // Wait a while for tasks to respond to being cancelled 121 * if (!pool.awaitTermination(60, TimeUnit.SECONDS)) 122 * System.err.println("Pool did not terminate"); 123 * } 124 * } catch (InterruptedException ie) { 125 * // (Re-)Cancel if current thread also interrupted 126 * pool.shutdownNow(); 127 * // Preserve interrupt status 128 * Thread.currentThread().interrupt(); 129 * } 130 * }}</pre> 131 * 132 * <p>Memory consistency effects: Actions in a thread prior to the 133 * submission of a {@code Runnable} or {@code Callable} task to an 134 * {@code ExecutorService} 135 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 136 * any actions taken by that task, which in turn <i>happen-before</i> the 137 * result is retrieved via {@code Future.get()}. 138 * 139 * @since 1.5 140 * @author Doug Lea 141 */ 142 public interface ExecutorService extends Executor { 143 144 /** 145 * Initiates an orderly shutdown in which previously submitted 146 * tasks are executed, but no new tasks will be accepted. 147 * Invocation has no additional effect if already shut down. 148 * 149 * <p>This method does not wait for previously submitted tasks to 150 * complete execution. Use {@link #awaitTermination awaitTermination} 151 * to do that. 152 */ shutdown()153 void shutdown(); 154 155 /** 156 * Attempts to stop all actively executing tasks, halts the 157 * processing of waiting tasks, and returns a list of the tasks 158 * that were awaiting execution. 159 * 160 * <p>This method does not wait for actively executing tasks to 161 * terminate. Use {@link #awaitTermination awaitTermination} to 162 * do that. 163 * 164 * <p>There are no guarantees beyond best-effort attempts to stop 165 * processing actively executing tasks. For example, typical 166 * implementations will cancel via {@link Thread#interrupt}, so any 167 * task that fails to respond to interrupts may never terminate. 168 * 169 * @return list of tasks that never commenced execution 170 */ shutdownNow()171 List<Runnable> shutdownNow(); 172 173 /** 174 * Returns {@code true} if this executor has been shut down. 175 * 176 * @return {@code true} if this executor has been shut down 177 */ isShutdown()178 boolean isShutdown(); 179 180 /** 181 * Returns {@code true} if all tasks have completed following shut down. 182 * Note that {@code isTerminated} is never {@code true} unless 183 * either {@code shutdown} or {@code shutdownNow} was called first. 184 * 185 * @return {@code true} if all tasks have completed following shut down 186 */ isTerminated()187 boolean isTerminated(); 188 189 /** 190 * Blocks until all tasks have completed execution after a shutdown 191 * request, or the timeout occurs, or the current thread is 192 * interrupted, whichever happens first. 193 * 194 * @param timeout the maximum time to wait 195 * @param unit the time unit of the timeout argument 196 * @return {@code true} if this executor terminated and 197 * {@code false} if the timeout elapsed before termination 198 * @throws InterruptedException if interrupted while waiting 199 */ awaitTermination(long timeout, TimeUnit unit)200 boolean awaitTermination(long timeout, TimeUnit unit) 201 throws InterruptedException; 202 203 /** 204 * Submits a value-returning task for execution and returns a 205 * Future representing the pending results of the task. The 206 * Future's {@code get} method will return the task's result upon 207 * successful completion. 208 * 209 * <p> 210 * If you would like to immediately block waiting 211 * for a task, you can use constructions of the form 212 * {@code result = exec.submit(aCallable).get();} 213 * 214 * <p>Note: The {@link Executors} class includes a set of methods 215 * that can convert some other common closure-like objects, 216 * for example, {@link java.security.PrivilegedAction} to 217 * {@link Callable} form so they can be submitted. 218 * 219 * @param task the task to submit 220 * @param <T> the type of the task's result 221 * @return a Future representing pending completion of the task 222 * @throws RejectedExecutionException if the task cannot be 223 * scheduled for execution 224 * @throws NullPointerException if the task is null 225 */ submit(Callable<T> task)226 <T> Future<T> submit(Callable<T> task); 227 228 /** 229 * Submits a Runnable task for execution and returns a Future 230 * representing that task. The Future's {@code get} method will 231 * return the given result upon successful completion. 232 * 233 * @param task the task to submit 234 * @param result the result to return 235 * @param <T> the type of the result 236 * @return a Future representing pending completion of the task 237 * @throws RejectedExecutionException if the task cannot be 238 * scheduled for execution 239 * @throws NullPointerException if the task is null 240 */ submit(Runnable task, T result)241 <T> Future<T> submit(Runnable task, T result); 242 243 /** 244 * Submits a Runnable task for execution and returns a Future 245 * representing that task. The Future's {@code get} method will 246 * return {@code null} upon <em>successful</em> completion. 247 * 248 * @param task the task to submit 249 * @return a Future representing pending completion of the task 250 * @throws RejectedExecutionException if the task cannot be 251 * scheduled for execution 252 * @throws NullPointerException if the task is null 253 */ submit(Runnable task)254 Future<?> submit(Runnable task); 255 256 /** 257 * Executes the given tasks, returning a list of Futures holding 258 * their status and results when all complete. 259 * {@link Future#isDone} is {@code true} for each 260 * element of the returned list. 261 * Note that a <em>completed</em> task could have 262 * terminated either normally or by throwing an exception. 263 * The results of this method are undefined if the given 264 * collection is modified while this operation is in progress. 265 * 266 * @param tasks the collection of tasks 267 * @param <T> the type of the values returned from the tasks 268 * @return a list of Futures representing the tasks, in the same 269 * sequential order as produced by the iterator for the 270 * given task list, each of which has completed 271 * @throws InterruptedException if interrupted while waiting, in 272 * which case unfinished tasks are cancelled 273 * @throws NullPointerException if tasks or any of its elements are {@code null} 274 * @throws RejectedExecutionException if any task cannot be 275 * scheduled for execution 276 */ invokeAll(Collection<? extends Callable<T>> tasks)277 <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) 278 throws InterruptedException; 279 280 /** 281 * Executes the given tasks, returning a list of Futures holding 282 * their status and results 283 * when all complete or the timeout expires, whichever happens first. 284 * {@link Future#isDone} is {@code true} for each 285 * element of the returned list. 286 * Upon return, tasks that have not completed are cancelled. 287 * Note that a <em>completed</em> task could have 288 * terminated either normally or by throwing an exception. 289 * The results of this method are undefined if the given 290 * collection is modified while this operation is in progress. 291 * 292 * @param tasks the collection of tasks 293 * @param timeout the maximum time to wait 294 * @param unit the time unit of the timeout argument 295 * @param <T> the type of the values returned from the tasks 296 * @return a list of Futures representing the tasks, in the same 297 * sequential order as produced by the iterator for the 298 * given task list. If the operation did not time out, 299 * each task will have completed. If it did time out, some 300 * of these tasks will not have completed. 301 * @throws InterruptedException if interrupted while waiting, in 302 * which case unfinished tasks are cancelled 303 * @throws NullPointerException if tasks, any of its elements, or 304 * unit are {@code null} 305 * @throws RejectedExecutionException if any task cannot be scheduled 306 * for execution 307 */ invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)308 <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks, 309 long timeout, TimeUnit unit) 310 throws InterruptedException; 311 312 /** 313 * Executes the given tasks, returning the result 314 * of one that has completed successfully (i.e., without throwing 315 * an exception), if any do. Upon normal or exceptional return, 316 * tasks that have not completed are cancelled. 317 * The results of this method are undefined if the given 318 * collection is modified while this operation is in progress. 319 * 320 * @param tasks the collection of tasks 321 * @param <T> the type of the values returned from the tasks 322 * @return the result returned by one of the tasks 323 * @throws InterruptedException if interrupted while waiting 324 * @throws NullPointerException if tasks or any element task 325 * subject to execution is {@code null} 326 * @throws IllegalArgumentException if tasks is empty 327 * @throws ExecutionException if no task successfully completes 328 * @throws RejectedExecutionException if tasks cannot be scheduled 329 * for execution 330 */ invokeAny(Collection<? extends Callable<T>> tasks)331 <T> T invokeAny(Collection<? extends Callable<T>> tasks) 332 throws InterruptedException, ExecutionException; 333 334 /** 335 * Executes the given tasks, returning the result 336 * of one that has completed successfully (i.e., without throwing 337 * an exception), if any do before the given timeout elapses. 338 * Upon normal or exceptional return, tasks that have not 339 * completed are cancelled. 340 * The results of this method are undefined if the given 341 * collection is modified while this operation is in progress. 342 * 343 * @param tasks the collection of tasks 344 * @param timeout the maximum time to wait 345 * @param unit the time unit of the timeout argument 346 * @param <T> the type of the values returned from the tasks 347 * @return the result returned by one of the tasks 348 * @throws InterruptedException if interrupted while waiting 349 * @throws NullPointerException if tasks, or unit, or any element 350 * task subject to execution is {@code null} 351 * @throws TimeoutException if the given timeout elapses before 352 * any task successfully completes 353 * @throws ExecutionException if no task successfully completes 354 * @throws RejectedExecutionException if tasks cannot be scheduled 355 * for execution 356 */ invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)357 <T> T invokeAny(Collection<? extends Callable<T>> tasks, 358 long timeout, TimeUnit unit) 359 throws InterruptedException, ExecutionException, TimeoutException; 360 } 361