1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Written by Doug Lea with assistance from members of JCP JSR-166 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Expert Group and released to the public domain, as explained at 4a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * http://creativecommons.org/publicdomain/zero/1.0/ 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 7adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage java.util.concurrent; 8edf43d27e240d82106f39ae91404963c23987234Narayan Kamath 98eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilsonimport java.util.Collection; 10e8b323c7cb7d55be9a4df579231e44f04f53d766Przemyslaw Szczepaniakimport java.util.List; 11a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson 12a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson// BEGIN android-note 13a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson// removed security manager docs 14a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson// END android-note 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 16adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * An {@link Executor} that provides methods to manage termination and 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * methods that can produce a {@link Future} for tracking progress of 19bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * one or more asynchronous tasks. 20adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 2191770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * <p>An {@code ExecutorService} can be shut down, which will cause 22bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * it to reject new tasks. Two different methods are provided for 2391770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * shutting down an {@code ExecutorService}. The {@link #shutdown} 24bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * method will allow previously submitted tasks to execute before 25bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * terminating, while the {@link #shutdownNow} method prevents waiting 26bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * tasks from starting and attempts to stop currently executing tasks. 27bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Upon termination, an executor has no tasks actively executing, no 28bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * tasks awaiting execution, and no new tasks can be submitted. An 2991770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * unused {@code ExecutorService} should be shut down to allow 30bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * reclamation of its resources. 31adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 3291770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * <p>Method {@code submit} extends base method {@link 33edf43d27e240d82106f39ae91404963c23987234Narayan Kamath * Executor#execute(Runnable)} by creating and returning a {@link Future} 34edf43d27e240d82106f39ae91404963c23987234Narayan Kamath * that can be used to cancel execution and/or wait for completion. 3591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * Methods {@code invokeAny} and {@code invokeAll} perform the most 36adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * commonly useful forms of bulk execution, executing a collection of 37adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * tasks and then waiting for at least one, or all, to 38adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * complete. (Class {@link ExecutorCompletionService} can be used to 39adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * write customized variants of these methods.) 40adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 41adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The {@link Executors} class provides factory methods for the 42adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * executor services provided in this package. 43adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 44bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * <h3>Usage Examples</h3> 45adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 46adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Here is a sketch of a network service in which threads in a thread 47adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * pool service incoming requests. It uses the preconfigured {@link 48adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Executors#newFixedThreadPool} factory method: 49adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 50e8b323c7cb7d55be9a4df579231e44f04f53d766Przemyslaw Szczepaniak * <pre> {@code 51bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * class NetworkService implements Runnable { 52bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * private final ServerSocket serverSocket; 53bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * private final ExecutorService pool; 54bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 55bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * public NetworkService(int port, int poolSize) 56bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * throws IOException { 57bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * serverSocket = new ServerSocket(port); 58bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * pool = Executors.newFixedThreadPool(poolSize); 59bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } 60bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 61bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * public void run() { // run the service 62bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * try { 63bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * for (;;) { 64bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * pool.execute(new Handler(serverSocket.accept())); 65bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } 66bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } catch (IOException ex) { 67bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * pool.shutdown(); 68bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } 69bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } 70bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } 71bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 72bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * class Handler implements Runnable { 73bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * private final Socket socket; 74bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Handler(Socket socket) { this.socket = socket; } 75bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * public void run() { 76bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * // read and service request on socket 77bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } 78a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * }}</pre> 79adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 8091770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * The following method shuts down an {@code ExecutorService} in two phases, 8191770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * first by calling {@code shutdown} to reject incoming tasks, and then 8291770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * calling {@code shutdownNow}, if necessary, to cancel any lingering tasks: 83adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 84e8b323c7cb7d55be9a4df579231e44f04f53d766Przemyslaw Szczepaniak * <pre> {@code 85bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * void shutdownAndAwaitTermination(ExecutorService pool) { 86bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * pool.shutdown(); // Disable new tasks from being submitted 87bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * try { 88bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * // Wait a while for existing tasks to terminate 89bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * if (!pool.awaitTermination(60, TimeUnit.SECONDS)) { 90bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * pool.shutdownNow(); // Cancel currently executing tasks 91bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * // Wait a while for tasks to respond to being cancelled 92bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * if (!pool.awaitTermination(60, TimeUnit.SECONDS)) 93bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * System.err.println("Pool did not terminate"); 94bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } 95bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } catch (InterruptedException ie) { 96bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * // (Re-)Cancel if current thread also interrupted 97bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * pool.shutdownNow(); 98bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * // Preserve interrupt status 99bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Thread.currentThread().interrupt(); 100bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * } 101a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * }}</pre> 102bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 103bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * <p>Memory consistency effects: Actions in a thread prior to the 104bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * submission of a {@code Runnable} or {@code Callable} task to an 105bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * {@code ExecutorService} 106bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 107bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * any actions taken by that task, which in turn <i>happen-before</i> the 108bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * result is retrieved via {@code Future.get()}. 109bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since 1.5 111adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @author Doug Lea 112adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 113adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic interface ExecutorService extends Executor { 114adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 115adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 116adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Initiates an orderly shutdown in which previously submitted 117bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * tasks are executed, but no new tasks will be accepted. 118bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Invocation has no additional effect if already shut down. 119bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 120bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * <p>This method does not wait for previously submitted tasks to 121bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * complete execution. Use {@link #awaitTermination awaitTermination} 122bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * to do that. 123adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 124adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project void shutdown(); 125adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 126adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 127adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Attempts to stop all actively executing tasks, halts the 128bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * processing of waiting tasks, and returns a list of the tasks 129bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * that were awaiting execution. 130bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 131bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * <p>This method does not wait for actively executing tasks to 132bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * terminate. Use {@link #awaitTermination awaitTermination} to 133bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * do that. 134bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 135adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>There are no guarantees beyond best-effort attempts to stop 136adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * processing actively executing tasks. For example, typical 137bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * implementations will cancel via {@link Thread#interrupt}, so any 138bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * task that fails to respond to interrupts may never terminate. 139adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 140adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return list of tasks that never commenced execution 141adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 142adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project List<Runnable> shutdownNow(); 143adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 144adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 14591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * Returns {@code true} if this executor has been shut down. 146adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 14791770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @return {@code true} if this executor has been shut down 148adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 149adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project boolean isShutdown(); 150adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 151adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 15291770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * Returns {@code true} if all tasks have completed following shut down. 15391770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * Note that {@code isTerminated} is never {@code true} unless 15491770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * either {@code shutdown} or {@code shutdownNow} was called first. 155adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 15691770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @return {@code true} if all tasks have completed following shut down 157adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 158adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project boolean isTerminated(); 159adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 160adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 161adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Blocks until all tasks have completed execution after a shutdown 162adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * request, or the timeout occurs, or the current thread is 163adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * interrupted, whichever happens first. 164adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 165adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param timeout the maximum time to wait 166adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param unit the time unit of the timeout argument 16791770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @return {@code true} if this executor terminated and 16891770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * {@code false} if the timeout elapsed before termination 169adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting 170adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 171adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project boolean awaitTermination(long timeout, TimeUnit unit) 172adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException; 173adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 174adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 175bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Submits a value-returning task for execution and returns a 176bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Future representing the pending results of the task. The 17791770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * Future's {@code get} method will return the task's result upon 178bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * successful completion. 179adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 180adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p> 181adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If you would like to immediately block waiting 182adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * for a task, you can use constructions of the form 18391770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * {@code result = exec.submit(aCallable).get();} 184adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 18591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * <p>Note: The {@link Executors} class includes a set of methods 186adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * that can convert some other common closure-like objects, 187adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * for example, {@link java.security.PrivilegedAction} to 188adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@link Callable} form so they can be submitted. 189adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 190adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param task the task to submit 191be0e537d8953365ae5a008350461ccf777a719fbNeil Fuller * @param <T> the type of the task's result 192adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a Future representing pending completion of the task 193bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws RejectedExecutionException if the task cannot be 194bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * scheduled for execution 195bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws NullPointerException if the task is null 196adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 197adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project <T> Future<T> submit(Callable<T> task); 198adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 199adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 200bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Submits a Runnable task for execution and returns a Future 20191770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * representing that task. The Future's {@code get} method will 202bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * return the given result upon successful completion. 203adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 204adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param task the task to submit 205adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param result the result to return 206be0e537d8953365ae5a008350461ccf777a719fbNeil Fuller * @param <T> the type of the result 207bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @return a Future representing pending completion of the task 208bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws RejectedExecutionException if the task cannot be 209bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * scheduled for execution 210bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws NullPointerException if the task is null 211adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 212adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project <T> Future<T> submit(Runnable task, T result); 213adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 214adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 215bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Submits a Runnable task for execution and returns a Future 21691770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * representing that task. The Future's {@code get} method will 21791770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * return {@code null} upon <em>successful</em> completion. 218adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 219adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param task the task to submit 220bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @return a Future representing pending completion of the task 221bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws RejectedExecutionException if the task cannot be 222bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * scheduled for execution 223bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws NullPointerException if the task is null 224adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 225adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project Future<?> submit(Runnable task); 226adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 227adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 228bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Executes the given tasks, returning a list of Futures holding 229bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * their status and results when all complete. 23091770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * {@link Future#isDone} is {@code true} for each 231bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * element of the returned list. 232adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Note that a <em>completed</em> task could have 233adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * terminated either normally or by throwing an exception. 234adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The results of this method are undefined if the given 235adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * collection is modified while this operation is in progress. 236bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 237adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param tasks the collection of tasks 238be0e537d8953365ae5a008350461ccf777a719fbNeil Fuller * @param <T> the type of the values returned from the tasks 23991770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @return a list of Futures representing the tasks, in the same 240bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * sequential order as produced by the iterator for the 24191770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * given task list, each of which has completed 242adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting, in 24391770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * which case unfinished tasks are cancelled 24491770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @throws NullPointerException if tasks or any of its elements are {@code null} 245bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws RejectedExecutionException if any task cannot be 246bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * scheduled for execution 247adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 2486232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) 249adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException; 250adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 251adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 252bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Executes the given tasks, returning a list of Futures holding 253bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * their status and results 254adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * when all complete or the timeout expires, whichever happens first. 25591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * {@link Future#isDone} is {@code true} for each 256bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * element of the returned list. 257adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Upon return, tasks that have not completed are cancelled. 258adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Note that a <em>completed</em> task could have 259adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * terminated either normally or by throwing an exception. 260adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The results of this method are undefined if the given 261adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * collection is modified while this operation is in progress. 262bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 263adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param tasks the collection of tasks 264adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param timeout the maximum time to wait 265adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param unit the time unit of the timeout argument 266be0e537d8953365ae5a008350461ccf777a719fbNeil Fuller * @param <T> the type of the values returned from the tasks 267bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @return a list of Futures representing the tasks, in the same 268bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * sequential order as produced by the iterator for the 269bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * given task list. If the operation did not time out, 270bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * each task will have completed. If it did time out, some 271bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * of these tasks will not have completed. 272adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting, in 273bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * which case unfinished tasks are cancelled 274adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws NullPointerException if tasks, any of its elements, or 27591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * unit are {@code null} 276adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws RejectedExecutionException if any task cannot be scheduled 277bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * for execution 278adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 2796232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks, 280bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson long timeout, TimeUnit unit) 281adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException; 282adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 283adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 284adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Executes the given tasks, returning the result 285adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * of one that has completed successfully (i.e., without throwing 286adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an exception), if any do. Upon normal or exceptional return, 287adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * tasks that have not completed are cancelled. 288adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The results of this method are undefined if the given 289adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * collection is modified while this operation is in progress. 290bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 291adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param tasks the collection of tasks 292be0e537d8953365ae5a008350461ccf777a719fbNeil Fuller * @param <T> the type of the values returned from the tasks 293bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @return the result returned by one of the tasks 294adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting 2956232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson * @throws NullPointerException if tasks or any element task 29691770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * subject to execution is {@code null} 297bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws IllegalArgumentException if tasks is empty 298adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws ExecutionException if no task successfully completes 299adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws RejectedExecutionException if tasks cannot be scheduled 300bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * for execution 301adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 3026232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson <T> T invokeAny(Collection<? extends Callable<T>> tasks) 303adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException, ExecutionException; 304adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 305adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 306adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Executes the given tasks, returning the result 307adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * of one that has completed successfully (i.e., without throwing 308adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an exception), if any do before the given timeout elapses. 309adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Upon normal or exceptional return, tasks that have not 310adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * completed are cancelled. 311adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The results of this method are undefined if the given 312adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * collection is modified while this operation is in progress. 313bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 314adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param tasks the collection of tasks 315adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param timeout the maximum time to wait 316adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param unit the time unit of the timeout argument 317be0e537d8953365ae5a008350461ccf777a719fbNeil Fuller * @param <T> the type of the values returned from the tasks 31891770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @return the result returned by one of the tasks 319adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting 3206232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson * @throws NullPointerException if tasks, or unit, or any element 32191770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * task subject to execution is {@code null} 322adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws TimeoutException if the given timeout elapses before 323bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * any task successfully completes 324adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws ExecutionException if no task successfully completes 325adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws RejectedExecutionException if tasks cannot be scheduled 326bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * for execution 327adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 3286232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson <T> T invokeAny(Collection<? extends Callable<T>> tasks, 329bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson long timeout, TimeUnit unit) 330adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException, ExecutionException, TimeoutException; 331adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 332