| 13 |
|
* methods that can produce a {@link Future} for tracking progress of |
| 14 |
|
* one or more asynchronous tasks. |
| 15 |
|
* |
| 16 |
< |
* <p>An <tt>ExecutorService</tt> can be shut down, which will cause |
| 16 |
> |
* <p>An {@code ExecutorService} can be shut down, which will cause |
| 17 |
|
* it to reject new tasks. Two different methods are provided for |
| 18 |
< |
* shutting down an <tt>ExecutorService</tt>. The {@link #shutdown} |
| 18 |
> |
* shutting down an {@code ExecutorService}. The {@link #shutdown} |
| 19 |
|
* method will allow previously submitted tasks to execute before |
| 20 |
|
* terminating, while the {@link #shutdownNow} method prevents waiting |
| 21 |
|
* tasks from starting and attempts to stop currently executing tasks. |
| 22 |
|
* Upon termination, an executor has no tasks actively executing, no |
| 23 |
|
* tasks awaiting execution, and no new tasks can be submitted. An |
| 24 |
< |
* unused <tt>ExecutorService</tt> should be shut down to allow |
| 24 |
> |
* unused {@code ExecutorService} should be shut down to allow |
| 25 |
|
* reclamation of its resources. |
| 26 |
|
* |
| 27 |
< |
* <p>Method <tt>submit</tt> extends base method {@link |
| 27 |
> |
* <p>Method {@code submit} extends base method {@link |
| 28 |
|
* Executor#execute} by creating and returning a {@link Future} that |
| 29 |
|
* can be used to cancel execution and/or wait for completion. |
| 30 |
< |
* Methods <tt>invokeAny</tt> and <tt>invokeAll</tt> perform the most |
| 30 |
> |
* Methods {@code invokeAny} and {@code invokeAll} perform the most |
| 31 |
|
* commonly useful forms of bulk execution, executing a collection of |
| 32 |
|
* tasks and then waiting for at least one, or all, to |
| 33 |
|
* complete. (Class {@link ExecutorCompletionService} can be used to |
| 72 |
|
* } |
| 73 |
|
* }}</pre> |
| 74 |
|
* |
| 75 |
< |
* The following method shuts down an <tt>ExecutorService</tt> in two phases, |
| 76 |
< |
* first by calling <tt>shutdown</tt> to reject incoming tasks, and then |
| 77 |
< |
* calling <tt>shutdownNow</tt>, if necessary, to cancel any lingering tasks: |
| 75 |
> |
* The following method shuts down an {@code ExecutorService} in two phases, |
| 76 |
> |
* first by calling {@code shutdown} to reject incoming tasks, and then |
| 77 |
> |
* calling {@code shutdownNow}, if necessary, to cancel any lingering tasks: |
| 78 |
|
* |
| 79 |
|
* <pre> {@code |
| 80 |
|
* void shutdownAndAwaitTermination(ExecutorService pool) { |
| 120 |
|
* shutting down this ExecutorService may manipulate |
| 121 |
|
* threads that the caller is not permitted to modify |
| 122 |
|
* because it does not hold {@link |
| 123 |
< |
* java.lang.RuntimePermission}<tt>("modifyThread")</tt>, |
| 124 |
< |
* or the security manager's <tt>checkAccess</tt> method |
| 123 |
> |
* java.lang.RuntimePermission}{@code ("modifyThread")}, |
| 124 |
> |
* or the security manager's {@code checkAccess} method |
| 125 |
|
* denies access. |
| 126 |
|
*/ |
| 127 |
|
void shutdown(); |
| 145 |
|
* shutting down this ExecutorService may manipulate |
| 146 |
|
* threads that the caller is not permitted to modify |
| 147 |
|
* because it does not hold {@link |
| 148 |
< |
* java.lang.RuntimePermission}<tt>("modifyThread")</tt>, |
| 149 |
< |
* or the security manager's <tt>checkAccess</tt> method |
| 148 |
> |
* java.lang.RuntimePermission}{@code ("modifyThread")}, |
| 149 |
> |
* or the security manager's {@code checkAccess} method |
| 150 |
|
* denies access. |
| 151 |
|
*/ |
| 152 |
|
List<Runnable> shutdownNow(); |
| 153 |
|
|
| 154 |
|
/** |
| 155 |
< |
* Returns <tt>true</tt> if this executor has been shut down. |
| 155 |
> |
* Returns {@code true} if this executor has been shut down. |
| 156 |
|
* |
| 157 |
< |
* @return <tt>true</tt> if this executor has been shut down |
| 157 |
> |
* @return {@code true} if this executor has been shut down |
| 158 |
|
*/ |
| 159 |
|
boolean isShutdown(); |
| 160 |
|
|
| 161 |
|
/** |
| 162 |
< |
* Returns <tt>true</tt> if all tasks have completed following shut down. |
| 163 |
< |
* Note that <tt>isTerminated</tt> is never <tt>true</tt> unless |
| 164 |
< |
* either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first. |
| 162 |
> |
* Returns {@code true} if all tasks have completed following shut down. |
| 163 |
> |
* Note that {@code isTerminated} is never {@code true} unless |
| 164 |
> |
* either {@code shutdown} or {@code shutdownNow} was called first. |
| 165 |
|
* |
| 166 |
< |
* @return <tt>true</tt> if all tasks have completed following shut down |
| 166 |
> |
* @return {@code true} if all tasks have completed following shut down |
| 167 |
|
*/ |
| 168 |
|
boolean isTerminated(); |
| 169 |
|
|
| 174 |
|
* |
| 175 |
|
* @param timeout the maximum time to wait |
| 176 |
|
* @param unit the time unit of the timeout argument |
| 177 |
< |
* @return <tt>true</tt> if this executor terminated and |
| 178 |
< |
* <tt>false</tt> if the timeout elapsed before termination |
| 177 |
> |
* @return {@code true} if this executor terminated and |
| 178 |
> |
* {@code false} if the timeout elapsed before termination |
| 179 |
|
* @throws InterruptedException if interrupted while waiting |
| 180 |
|
*/ |
| 181 |
|
boolean awaitTermination(long timeout, TimeUnit unit) |
| 184 |
|
/** |
| 185 |
|
* Submits a value-returning task for execution and returns a |
| 186 |
|
* Future representing the pending results of the task. The |
| 187 |
< |
* Future's <tt>get</tt> method will return the task's result upon |
| 187 |
> |
* Future's {@code get} method will return the task's result upon |
| 188 |
|
* successful completion. |
| 189 |
|
* |
| 190 |
|
* <p> |
| 191 |
|
* If you would like to immediately block waiting |
| 192 |
|
* for a task, you can use constructions of the form |
| 193 |
< |
* <tt>result = exec.submit(aCallable).get();</tt> |
| 193 |
> |
* {@code result = exec.submit(aCallable).get();} |
| 194 |
|
* |
| 195 |
|
* <p>Note: The {@link Executors} class includes a set of methods |
| 196 |
|
* that can convert some other common closure-like objects, |
| 207 |
|
|
| 208 |
|
/** |
| 209 |
|
* Submits a Runnable task for execution and returns a Future |
| 210 |
< |
* representing that task. The Future's <tt>get</tt> method will |
| 210 |
> |
* representing that task. The Future's {@code get} method will |
| 211 |
|
* return the given result upon successful completion. |
| 212 |
|
* |
| 213 |
|
* @param task the task to submit |
| 221 |
|
|
| 222 |
|
/** |
| 223 |
|
* Submits a Runnable task for execution and returns a Future |
| 224 |
< |
* representing that task. The Future's <tt>get</tt> method will |
| 225 |
< |
* return <tt>null</tt> upon <em>successful</em> completion. |
| 224 |
> |
* representing that task. The Future's {@code get} method will |
| 225 |
> |
* return {@code null} upon <em>successful</em> completion. |
| 226 |
|
* |
| 227 |
|
* @param task the task to submit |
| 228 |
|
* @return a Future representing pending completion of the task |
| 235 |
|
/** |
| 236 |
|
* Executes the given tasks, returning a list of Futures holding |
| 237 |
|
* their status and results when all complete. |
| 238 |
< |
* {@link Future#isDone} is <tt>true</tt> for each |
| 238 |
> |
* {@link Future#isDone} is {@code true} for each |
| 239 |
|
* element of the returned list. |
| 240 |
|
* Note that a <em>completed</em> task could have |
| 241 |
|
* terminated either normally or by throwing an exception. |
| 248 |
|
* given task list, each of which has completed. |
| 249 |
|
* @throws InterruptedException if interrupted while waiting, in |
| 250 |
|
* which case unfinished tasks are cancelled. |
| 251 |
< |
* @throws NullPointerException if tasks or any of its elements are <tt>null</tt> |
| 251 |
> |
* @throws NullPointerException if tasks or any of its elements are {@code null} |
| 252 |
|
* @throws RejectedExecutionException if any task cannot be |
| 253 |
|
* scheduled for execution |
| 254 |
|
*/ |
| 259 |
|
* Executes the given tasks, returning a list of Futures holding |
| 260 |
|
* their status and results |
| 261 |
|
* when all complete or the timeout expires, whichever happens first. |
| 262 |
< |
* {@link Future#isDone} is <tt>true</tt> for each |
| 262 |
> |
* {@link Future#isDone} is {@code true} for each |
| 263 |
|
* element of the returned list. |
| 264 |
|
* Upon return, tasks that have not completed are cancelled. |
| 265 |
|
* Note that a <em>completed</em> task could have |
| 278 |
|
* @throws InterruptedException if interrupted while waiting, in |
| 279 |
|
* which case unfinished tasks are cancelled |
| 280 |
|
* @throws NullPointerException if tasks, any of its elements, or |
| 281 |
< |
* unit are <tt>null</tt> |
| 281 |
> |
* unit are {@code null} |
| 282 |
|
* @throws RejectedExecutionException if any task cannot be scheduled |
| 283 |
|
* for execution |
| 284 |
|
*/ |
| 298 |
|
* @return the result returned by one of the tasks |
| 299 |
|
* @throws InterruptedException if interrupted while waiting |
| 300 |
|
* @throws NullPointerException if tasks or any element task |
| 301 |
< |
* subject to execution is <tt>null</tt> |
| 301 |
> |
* subject to execution is {@code null} |
| 302 |
|
* @throws IllegalArgumentException if tasks is empty |
| 303 |
|
* @throws ExecutionException if no task successfully completes |
| 304 |
|
* @throws RejectedExecutionException if tasks cannot be scheduled |
| 322 |
|
* @return the result returned by one of the tasks |
| 323 |
|
* @throws InterruptedException if interrupted while waiting |
| 324 |
|
* @throws NullPointerException if tasks, or unit, or any element |
| 325 |
< |
* task subject to execution is <tt>null</tt> |
| 325 |
> |
* task subject to execution is {@code null} |
| 326 |
|
* @throws TimeoutException if the given timeout elapses before |
| 327 |
|
* any task successfully completes |
| 328 |
|
* @throws ExecutionException if no task successfully completes |
