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 97365de1056414750d0a7d1fdd26025fd247f0d04Jesse Wilsonimport java.util.List; 108eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilsonimport java.util.Collection; 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 * 50a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * <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 * 84a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * <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 191adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a Future representing pending completion of the task 192bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws RejectedExecutionException if the task cannot be 193bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * scheduled for execution 194bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws NullPointerException if the task is null 195adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 196adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project <T> Future<T> submit(Callable<T> task); 197adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 198adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 199bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Submits a Runnable task for execution and returns a Future 20091770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * representing that task. The Future's {@code get} method will 201bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * return the given result upon successful completion. 202adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 203adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param task the task to submit 204adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param result the result to return 205bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @return a Future representing pending completion of the task 206bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws RejectedExecutionException if the task cannot be 207bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * scheduled for execution 208bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws NullPointerException if the task is null 209adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 210adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project <T> Future<T> submit(Runnable task, T result); 211adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 212adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 213bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Submits a Runnable task for execution and returns a Future 21491770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * representing that task. The Future's {@code get} method will 21591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * return {@code null} upon <em>successful</em> completion. 216adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 217adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param task the task to submit 218bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @return a Future representing pending completion of the task 219bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws RejectedExecutionException if the task cannot be 220bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * scheduled for execution 221bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws NullPointerException if the task is null 222adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 223adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project Future<?> submit(Runnable task); 224adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 225adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 226bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Executes the given tasks, returning a list of Futures holding 227bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * their status and results when all complete. 22891770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * {@link Future#isDone} is {@code true} for each 229bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * element of the returned list. 230adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Note that a <em>completed</em> task could have 231adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * terminated either normally or by throwing an exception. 232adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The results of this method are undefined if the given 233adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * collection is modified while this operation is in progress. 234bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 235adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param tasks the collection of tasks 23691770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @return a list of Futures representing the tasks, in the same 237bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * sequential order as produced by the iterator for the 23891770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * given task list, each of which has completed 239adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting, in 24091770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * which case unfinished tasks are cancelled 24191770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @throws NullPointerException if tasks or any of its elements are {@code null} 242bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws RejectedExecutionException if any task cannot be 243bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * scheduled for execution 244adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 2456232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) 246adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException; 247adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 248adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 249bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * Executes the given tasks, returning a list of Futures holding 250bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * their status and results 251adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * when all complete or the timeout expires, whichever happens first. 25291770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * {@link Future#isDone} is {@code true} for each 253bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * element of the returned list. 254adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Upon return, tasks that have not completed are cancelled. 255adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Note that a <em>completed</em> task could have 256adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * terminated either normally or by throwing an exception. 257adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The results of this method are undefined if the given 258adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * collection is modified while this operation is in progress. 259bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 260adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param tasks the collection of tasks 261adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param timeout the maximum time to wait 262adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param unit the time unit of the timeout argument 263bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @return a list of Futures representing the tasks, in the same 264bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * sequential order as produced by the iterator for the 265bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * given task list. If the operation did not time out, 266bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * each task will have completed. If it did time out, some 267bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * of these tasks will not have completed. 268adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting, in 269bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * which case unfinished tasks are cancelled 270adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws NullPointerException if tasks, any of its elements, or 27191770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * unit are {@code null} 272adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws RejectedExecutionException if any task cannot be scheduled 273bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * for execution 274adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 2756232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks, 276bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson long timeout, TimeUnit unit) 277adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException; 278adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 279adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 280adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Executes the given tasks, returning the result 281adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * of one that has completed successfully (i.e., without throwing 282adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an exception), if any do. Upon normal or exceptional return, 283adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * tasks that have not completed are cancelled. 284adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The results of this method are undefined if the given 285adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * collection is modified while this operation is in progress. 286bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 287adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param tasks the collection of tasks 288bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @return the result returned by one of the tasks 289adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting 2906232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson * @throws NullPointerException if tasks or any element task 29191770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * subject to execution is {@code null} 292bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * @throws IllegalArgumentException if tasks is empty 293adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws ExecutionException if no task successfully completes 294adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws RejectedExecutionException if tasks cannot be scheduled 295bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * for execution 296adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 2976232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson <T> T invokeAny(Collection<? extends Callable<T>> tasks) 298adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException, ExecutionException; 299adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 300adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 301adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Executes the given tasks, returning the result 302adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * of one that has completed successfully (i.e., without throwing 303adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an exception), if any do before the given timeout elapses. 304adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Upon normal or exceptional return, tasks that have not 305adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * completed are cancelled. 306adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The results of this method are undefined if the given 307adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * collection is modified while this operation is in progress. 308bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 309adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param tasks the collection of tasks 310adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param timeout the maximum time to wait 311adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param unit the time unit of the timeout argument 31291770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * @return the result returned by one of the tasks 313adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws InterruptedException if interrupted while waiting 3146232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson * @throws NullPointerException if tasks, or unit, or any element 31591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * task subject to execution is {@code null} 316adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws TimeoutException if the given timeout elapses before 317bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * any task successfully completes 318adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws ExecutionException if no task successfully completes 319adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws RejectedExecutionException if tasks cannot be scheduled 320bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * for execution 321adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 3226232a5efed0ea103e35aec73206e5e03a8b82e0cJesse Wilson <T> T invokeAny(Collection<? extends Callable<T>> tasks, 323bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson long timeout, TimeUnit unit) 324adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws InterruptedException, ExecutionException, TimeoutException; 325adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 326