001: /*
002: * Written by Doug Lea with assistance from members of JCP JSR-166
003: * Expert Group and released to the public domain, as explained at
004: * http://creativecommons.org/licenses/publicdomain
005: */
006:
007: package java.util.concurrent;
008:
009: import java.util.List;
010: import java.util.Collection;
011: import java.security.PrivilegedAction;
012: import java.security.PrivilegedExceptionAction;
013:
014: /**
015: * An {@link Executor} that provides methods to manage termination and
016: * methods that can produce a {@link Future} for tracking progress of
017: * one or more asynchronous tasks.
018: *
019: * <p>
020: * An <tt>ExecutorService</tt> can be shut down, which will cause it
021: * to stop accepting new tasks. After being shut down, the executor
022: * will eventually terminate, at which point no tasks are actively
023: * executing, no tasks are awaiting execution, and no new tasks can be
024: * submitted.
025: *
026: * <p> Method <tt>submit</tt> extends base method {@link
027: * Executor#execute} by creating and returning a {@link Future} that
028: * can be used to cancel execution and/or wait for completion.
029: * Methods <tt>invokeAny</tt> and <tt>invokeAll</tt> perform the most
030: * commonly useful forms of bulk execution, executing a collection of
031: * tasks and then waiting for at least one, or all, to
032: * complete. (Class {@link ExecutorCompletionService} can be used to
033: * write customized variants of these methods.)
034: *
035: * <p>The {@link Executors} class provides factory methods for the
036: * executor services provided in this package.
037: *
038: * <h3>Usage Example</h3>
039: *
040: * Here is a sketch of a network service in which threads in a thread
041: * pool service incoming requests. It uses the preconfigured {@link
042: * Executors#newFixedThreadPool} factory method:
043: *
044: * <pre>
045: * class NetworkService {
046: * private final ServerSocket serverSocket;
047: * private final ExecutorService pool;
048: *
049: * public NetworkService(int port, int poolSize) throws IOException {
050: * serverSocket = new ServerSocket(port);
051: * pool = Executors.newFixedThreadPool(poolSize);
052: * }
053: *
054: * public void serve() {
055: * try {
056: * for (;;) {
057: * pool.execute(new Handler(serverSocket.accept()));
058: * }
059: * } catch (IOException ex) {
060: * pool.shutdown();
061: * }
062: * }
063: * }
064: *
065: * class Handler implements Runnable {
066: * private final Socket socket;
067: * Handler(Socket socket) { this.socket = socket; }
068: * public void run() {
069: * // read and service request
070: * }
071: * }
072: * </pre>
073: * @since 1.5
074: * @author Doug Lea
075: */
076: public interface ExecutorService extends Executor {
077:
078: /**
079: * Initiates an orderly shutdown in which previously submitted
080: * tasks are executed, but no new tasks will be
081: * accepted. Invocation has no additional effect if already shut
082: * down.
083: * @throws SecurityException if a security manager exists and
084: * shutting down this ExecutorService may manipulate threads that
085: * the caller is not permitted to modify because it does not hold
086: * {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
087: * or the security manager's <tt>checkAccess</tt> method denies access.
088: */
089: void shutdown();
090:
091: /**
092: * Attempts to stop all actively executing tasks, halts the
093: * processing of waiting tasks, and returns a list of the tasks that were
094: * awaiting execution.
095: *
096: * <p>There are no guarantees beyond best-effort attempts to stop
097: * processing actively executing tasks. For example, typical
098: * implementations will cancel via {@link Thread#interrupt}, so if any
099: * tasks mask or fail to respond to interrupts, they may never terminate.
100: *
101: * @return list of tasks that never commenced execution
102: * @throws SecurityException if a security manager exists and
103: * shutting down this ExecutorService may manipulate threads that
104: * the caller is not permitted to modify because it does not hold
105: * {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
106: * or the security manager's <tt>checkAccess</tt> method denies access.
107: */
108: List<Runnable> shutdownNow();
109:
110: /**
111: * Returns <tt>true</tt> if this executor has been shut down.
112: *
113: * @return <tt>true</tt> if this executor has been shut down
114: */
115: boolean isShutdown();
116:
117: /**
118: * Returns <tt>true</tt> if all tasks have completed following shut down.
119: * Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
120: * either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
121: *
122: * @return <tt>true</tt> if all tasks have completed following shut down
123: */
124: boolean isTerminated();
125:
126: /**
127: * Blocks until all tasks have completed execution after a shutdown
128: * request, or the timeout occurs, or the current thread is
129: * interrupted, whichever happens first.
130: *
131: * @param timeout the maximum time to wait
132: * @param unit the time unit of the timeout argument
133: * @return <tt>true</tt> if this executor terminated and <tt>false</tt>
134: * if the timeout elapsed before termination
135: * @throws InterruptedException if interrupted while waiting
136: */
137: boolean awaitTermination(long timeout, TimeUnit unit)
138: throws InterruptedException;
139:
140: /**
141: * Submits a value-returning task for execution and returns a Future
142: * representing the pending results of the task.
143: *
144: * <p>
145: * If you would like to immediately block waiting
146: * for a task, you can use constructions of the form
147: * <tt>result = exec.submit(aCallable).get();</tt>
148: *
149: * <p> Note: The {@link Executors} class includes a set of methods
150: * that can convert some other common closure-like objects,
151: * for example, {@link java.security.PrivilegedAction} to
152: * {@link Callable} form so they can be submitted.
153: *
154: * @param task the task to submit
155: * @return a Future representing pending completion of the task
156: * @throws RejectedExecutionException if task cannot be scheduled
157: * for execution
158: * @throws NullPointerException if task null
159: */
160: <T> Future<T> submit(Callable<T> task);
161:
162: /**
163: * Submits a Runnable task for execution and returns a Future
164: * representing that task that will upon completion return
165: * the given result
166: *
167: * @param task the task to submit
168: * @param result the result to return
169: * @return a Future representing pending completion of the task,
170: * and whose <tt>get()</tt> method will return the given result
171: * upon completion.
172: * @throws RejectedExecutionException if task cannot be scheduled
173: * for execution
174: * @throws NullPointerException if task null
175: */
176: <T> Future<T> submit(Runnable task, T result);
177:
178: /**
179: * Submits a Runnable task for execution and returns a Future
180: * representing that task.
181: *
182: * @param task the task to submit
183: * @return a Future representing pending completion of the task,
184: * and whose <tt>get()</tt> method will return <tt>null</tt>
185: * upon completion.
186: * @throws RejectedExecutionException if task cannot be scheduled
187: * for execution
188: * @throws NullPointerException if task null
189: */
190: Future<?> submit(Runnable task);
191:
192: /**
193: * Executes the given tasks, returning their results
194: * when all complete.
195: * Note that a <em>completed</em> task could have
196: * terminated either normally or by throwing an exception.
197: * The results of this method are undefined if the given
198: * collection is modified while this operation is in progress.
199: * @param tasks the collection of tasks
200: * @return A list of Futures representing the tasks, in the same
201: * sequential order as produced by the iterator for the given task
202: * list, each of which has completed.
203: * @throws InterruptedException if interrupted while waiting, in
204: * which case unfinished tasks are cancelled.
205: * @throws NullPointerException if tasks or any of its elements are <tt>null</tt>
206: * @throws RejectedExecutionException if any task cannot be scheduled
207: * for execution
208: */
209:
210: <T> List<Future<T>> invokeAll(Collection<Callable<T>> tasks)
211: throws InterruptedException;
212:
213: /**
214: * Executes the given tasks, returning their results
215: * when all complete or the timeout expires, whichever happens first.
216: * Upon return, tasks that have not completed are cancelled.
217: * Note that a <em>completed</em> task could have
218: * terminated either normally or by throwing an exception.
219: * The results of this method are undefined if the given
220: * collection is modified while this operation is in progress.
221: * @param tasks the collection of tasks
222: * @param timeout the maximum time to wait
223: * @param unit the time unit of the timeout argument
224: * @return A list of Futures representing the tasks, in the same
225: * sequential order as produced by the iterator for the given
226: * task list. If the operation did not time out, each task will
227: * have completed. If it did time out, some of thiese tasks will
228: * not have completed.
229: * @throws InterruptedException if interrupted while waiting, in
230: * which case unfinished tasks are cancelled.
231: * @throws NullPointerException if tasks, any of its elements, or
232: * unit are <tt>null</tt>
233: * @throws RejectedExecutionException if any task cannot be scheduled
234: * for execution
235: */
236: <T> List<Future<T>> invokeAll(Collection<Callable<T>> tasks,
237: long timeout, TimeUnit unit) throws InterruptedException;
238:
239: /**
240: * Executes the given tasks, returning the result
241: * of one that has completed successfully (i.e., without throwing
242: * an exception), if any do. Upon normal or exceptional return,
243: * tasks that have not completed are cancelled.
244: * The results of this method are undefined if the given
245: * collection is modified while this operation is in progress.
246: * @param tasks the collection of tasks
247: * @return The result returned by one of the tasks.
248: * @throws InterruptedException if interrupted while waiting
249: * @throws NullPointerException if tasks or any of its elements
250: * are <tt>null</tt>
251: * @throws IllegalArgumentException if tasks empty
252: * @throws ExecutionException if no task successfully completes
253: * @throws RejectedExecutionException if tasks cannot be scheduled
254: * for execution
255: */
256: <T> T invokeAny(Collection<Callable<T>> tasks)
257: throws InterruptedException, ExecutionException;
258:
259: /**
260: * Executes the given tasks, returning the result
261: * of one that has completed successfully (i.e., without throwing
262: * an exception), if any do before the given timeout elapses.
263: * Upon normal or exceptional return, tasks that have not
264: * 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: * @param tasks the collection of tasks
268: * @param timeout the maximum time to wait
269: * @param unit the time unit of the timeout argument
270: * @return The result returned by one of the tasks.
271: * @throws InterruptedException if interrupted while waiting
272: * @throws NullPointerException if tasks, any of its elements, or
273: * unit are <tt>null</tt>
274: * @throws TimeoutException if the given timeout elapses before
275: * any task successfully completes
276: * @throws ExecutionException if no task successfully completes
277: * @throws RejectedExecutionException if tasks cannot be scheduled
278: * for execution
279: */
280: <T> T invokeAny(Collection<Callable<T>> tasks, long timeout,
281: TimeUnit unit) throws InterruptedException,
282: ExecutionException, TimeoutException;
283:
284: }
|