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