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