java.util.concurrent翻译----Executor框架--接口ExecutorService

package java.util.concurrent;
import java.util.List;
import java.util.Collection;

/**
* An {@link Executor} that provides methods to manage termination and
* methods that can produce a {@link Future} for tracking progress of
* one or more asynchronous tasks.
*
* Executor提供了管理终止的方法，以及可为跟踪一个或多个异步任务状况而生成 Future 的方法
*
* <p> An <tt>ExecutorService</tt> can be shut down, which will cause
* it to reject(拒绝) new tasks.  Two different methods are provided for
* shutting down an <tt>ExecutorService</tt>. The {@link #shutdown}
* method will allow previously submitted tasks to execute before
* terminating, while the {@link #shutdownNow} method prevents waiting
* tasks from starting and attempts to stop currently executing tasks.
* Upon(在...时) termination, an executor has no tasks actively executing, no
* tasks awaiting execution, and no new tasks can be submitted.  An
* unused <tt>ExecutorService</tt> should be shut down to allow
* reclamation(回收) of its resources.
*
* 可以关闭 ExecutorService，这将会导致其拒绝新任务。提供两个方法来关闭 ExecutorService 。
* shutdown 方法允许在终止前执行以前提交的任务，而shutdownow 方法阻止等待任务启动并偿试停止目前
* 正在执行的任务。在终止时，执行程序没有任务在执行，没有任务等待执行，也无法提交新任务。
* 应该关闭未使用的 ExecutorService以允许回收其收其资源。
*
* <p> Method <tt>submit</tt> extends base method {@link
* Executor#execute} by creating and returning a {@link Future} that
* can be used to cancel execution and/or wait for completion.
* Methods <tt>invokeAny</tt> and <tt>invokeAll</tt> perform the most
* commonly useful forms of bulk execution, executing a collection of
* tasks and then waiting for at least one, or all, to
* complete. (Class {@link ExecutorCompletionService} can be used to
* write customized variants of these methods.)
*
* 通过创建并返回一个可用于取消执行和/或等待完成的 Future，方法 submit 扩展了基本方法 Executor.execute(java.lang.Runnable)。
* 方法 invokeAny和invokeAll 是批量执行的最常用形式，它们执行了collection，然后等待至少一个，
* 或全部任务完成（可使用 ExecutorCompletionService 类来编写这些方法的自定义变体。）
*
* <p>The {@link Executors} class provides factory methods for the
* executor services provided in this package.
*
* Executors 类提供了用于此包中所提供的执行程序服务的工厂方法。
*
* <h3>Usage Examples</h3> 用于示例
*
* Here is a sketch(结构，概要) of a network service in which threads in a thread
* pool service incoming requests. It uses the preconfigured {@link
* Executors#newFixedThreadPool} factory method:
*
* 下面给出了一个网络服务的简单结构，这里的线程池中的线程作为传入的请求。它使用了预先配置的
* Executors.newFixedThreadPool(int) 工厂方法：
*
* <pre>
* class NetworkService implements Runnable {
*   private final ServerSocket serverSocket;
*   private final ExecutorService pool;
*
*   public NetworkService(int port, int poolSize)
*       throws IOException {
*     serverSocket = new ServerSocket(port);
*     pool = Executors.newFixedThreadPool(poolSize);
*   }
*
*   public void run() { // run the service
*     try {
*       for (;;) {
*         pool.execute(new Handler(serverSocket.accept()));
*       }
*     } catch (IOException ex) {
*       pool.shutdown();
*     }
*   }
* }
*
* class Handler implements Runnable {
*   private final Socket socket;
*   Handler(Socket socket) { this.socket = socket; }
*   public void run() {
*     // read and service request on socket
*   }
* }
* </pre>
*
* The following method shuts down an <tt>ExecutorService</tt> in two phases,
* first by calling <tt>shutdown</tt> to reject incoming tasks, and then
* calling <tt>shutdownNow</tt>, if necessary, to cancel any lingering tasks:
*
* 下列方法分两个阶段关闭 ExecutorService。第一阶段调用 shutdown 拒绝传入任务，
* 然后调用 shutdownNow（如有必要）取消所有遗留的任务：
*
* <pre>
* void shutdownAndAwaitTermination(ExecutorService pool) {
*   pool.shutdown(); // Disable new tasks from being submitted
*   try {
*     // Wait a while for existing tasks to terminate
*     if (!pool.awaitTermination(60, TimeUnit.SECONDS)) {
*       pool.shutdownNow(); // Cancel currently executing tasks
*       // Wait a while for tasks to respond to being cancelled
*       if (!pool.awaitTermination(60, TimeUnit.SECONDS))
*           System.err.println("Pool did not terminate");
*     }
*   } catch (InterruptedException ie) {
*     // (Re-)Cancel if current thread also interrupted
*     pool.shutdownNow();
*     // Preserve interrupt status
*     Thread.currentThread().interrupt();
*   }
* }
* </pre>
*
* <p>Memory consistency effects: Actions in a thread prior to the
* submission of a {@code Runnable} or {@code Callable} task to an
* {@code ExecutorService}
* <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
* any actions taken by that task, which in turn <i>happen-before</i> the
* result is retrieved via {@code Future.get()}.
*
* 内存一致性效果：线程中向 ExecutorService 提交 Runnable
* 或 Callable 任务之前的操作 happen-before 由该任务所提取的所有操作，
* 后者依次 happen-before 通过 Future.get() 获取的结果。
*
* @since 1.5
* @author Doug Lea
*/
public interface ExecutorService extends Executor {

/**
* Initiates(发起; 开始) an orderly shutdown in which previously submitted
* tasks are executed, but no new tasks will be accepted.
* Invocation has no additional effect if already shut down.
*
* 启动一次顺序关闭，执行以前提交的任务，但不接受新任务。
* 如果已经关闭，则调用没有其他作用。
*
* <p>This method does not wait for previously submitted tasks to
* complete execution.  Use {@link #awaitTermination awaitTermination}
* to do that.
*
* 此方法不等待先前提交的任务以完成执行
* 使用{@link #awaitTermination awaitTermination}要做到这一点。
*
* @throws SecurityException if a security manager exists and
*         shutting down this ExecutorService may manipulate(操作)
*         threads that the caller is not permitted to modify
*         because it does not hold {@link
*         java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
*         or the security manager's <tt>checkAccess</tt> method
*         denies access.
*
*  抛出 SecurityException 异常 - 如果安全管理器存在并且关闭，此ExecutorService
*  可能操作某些不允许调用者修改的线程（因为因为它没有保持 RuntimePermission("modifyThread")），
*  或者安全管理器的 checkAccess 方法拒绝访问
*/
void shutdown();

/**
* Attempts to stop all actively executing tasks, halts the
* processing of waiting tasks, and returns a list of the tasks
* that were awaiting execution.
* 试图停止所以正在执行的活动任务，暂停处理正在等待的任务，并返回等待执行的任务列表
*
* <p>This method does not wait for actively executing tasks to
* terminate.  Use {@link #awaitTermination awaitTermination} to
* do that.
* 为了终止此方法不会等待正在执行的活动任务
* 使用{@link #awaitTermination awaitTermination}要做到这一点。
*
* <p>There are no guarantees(保证) beyond best-effort（最大努力） attempts to stop
* processing actively executing tasks.  For example, typical
* implementations will cancel via {@link Thread#interrupt}, so any
* task that fails to respond to interrupts may never terminate.
* 无法保证能够停止正在处理的活动执行任务，但是会尽力尝试。
* 例如，通过 Thread.interrupt() 来取消是典型的实现，
* 所以任何任务无法响应中断都可能永远无法终止。
*
* @return list of tasks that never commenced(开始) execution
*           从未开始执行的任务的列表
* @throws SecurityException if a security manager exists and
*         shutting down this ExecutorService may manipulate
*         threads that the caller is not permitted to modify
*         because it does not hold {@link
*         java.lang.RuntimePermission}<tt>("modifyThread")</tt>,
*         or the security manager's <tt>checkAccess</tt> method
*         denies access.
*/
List<Runnable> shutdownNow();

/**
* Returns <tt>true</tt> if this executor has been shut down.
* 如果此执行程序已关闭，则返回 true。
* @return <tt>true</tt> if this executor has been shut down
*/
boolean isShutdown();

/**
* Returns <tt>true</tt> if all tasks have completed following shut down.
* Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
* either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
*
* 如果关闭后所有任务都已完成，则返回true。
* 注意，除非首先调用 shutdown或者shutdownNow,否则 isTerminated永不为true.
*
* @return <tt>true</tt> if all tasks have completed following shut down
*/
boolean isTerminated();

/**
* Blocks until all tasks have completed execution after a shutdown
* request, or the timeout occurs, or the current thread is
* interrupted, whichever happens first.
* 请求关闭，发生超时或者当前线程中断，无论哪一个首先发生之后，都将为导致阻塞，
* 直到所有任务完成执行。
*
* @param timeout the maximum time to wait  最长等待时间
* @param unit the time unit(单位) of the timeout argument  timeout参数的时间单位
* @return <tt>true</tt> if this executor terminated and
*         <tt>false</tt> if the timeout elapsed before termination
*         如果此执行程序终止，则返回 true；如果终止前超时期满，则返回 false
*
* @throws InterruptedException if interrupted while waiting
*          - 如果等待时发生中断
*/
boolean awaitTermination(long timeout, TimeUnit unit)
throws InterruptedException;

/**
* Submits a value-returning task for execution and returns a
* Future representing the pending（待定） results of the task. The
* Future's <tt>get</tt> method will return the task's result upon
* successful completion.
* 提交一个返回值的任务用于执行，返回一个代表任务的未决结果的 Future
* 该 Future的get方法在成功完成时将会返回该任务的结果
*
* <p>
* If you would like to immediately block waiting
* for a task, you can use constructions of the form
* <tt>result = exec.submit(aCallable).get();</tt>
* 如果想立即阻塞任务的等待，则可以使用result = exec.submit(aCallable).get(); 形式的构造。
*
* <p> Note: The {@link Executors} class includes a set of methods
* that can convert some other common closure-like objects,
* for example, {@link java.security.PrivilegedAction} to
* {@link Callable} form so they can be submitted.
* 注意：Executor 类包括了一组方法，可以转换某些常见的类似闭包的对象，
* 例如，将将 PrivilegedAction 转换为 Callable 形式，这样就可以提交它们了。
*
* @param task the task to submit - 要提交的任务
* @return a Future representing pending completion of the task
*          表示任务等待完成的 Future
*
* @throws RejectedExecutionException if the task cannot be
*         scheduled for execution - 如果任务无法安排执行
* @throws NullPointerException if the task is null
*/
<T> Future<T> submit(Callable<T> task);

/**
* Submits a Runnable task for execution and returns a Future
* representing that task. The Future's <tt>get</tt> method will
* return the given result upon successful completion.
* 提交一个Runnable任务用于执行，并返回一个代表该任务的Future。
* 该 Future 的get方法在成功完成时将会返回给定的结果。
*
* @param task the task to submit
* @param result the result to return
* @return a Future representing pending completion of the task
* @throws RejectedExecutionException if the task cannot be
*         scheduled for execution
* @throws NullPointerException if the task is null
*/
<T> Future<T> submit(Runnable task, T result);

/**
* Submits a Runnable task for execution and returns a Future
* representing that task. The Future's <tt>get</tt> method will
* return <tt>null</tt> upon <em>successful</em> completion.
*
* @param task the task to submit
* @return a Future representing pending completion of the task
* @throws RejectedExecutionException if the task cannot be
*         scheduled for execution
* @throws NullPointerException if the task is null
*/
Future<?> submit(Runnable task);

/**
* Executes the given tasks, returning a list of Futures holding
* their status and results when all complete.
* {@link Future#isDone} is <tt>true</tt> for each
* element of the returned list.
* Note that a <em>completed</em> task could have
* terminated either normally or by throwing an exception.
* The results of this method are undefined if the given
* collection is modified while this operation is in progress.
*
* 执行给定的任务，当所有任务完成或超时期满时（无论哪个首先发生），
* 返回保持任务状态和结果的 Future 列表。返回列表的所有元素的 Future.isDone() 为 true。
* 一旦返回后，即取消尚未完成的任务。
* 注意，可以正常地或通过抛出异常来终止已完成 任务。
* 如果此操作正在进行时修改了给定的 collection，则此方法的结果是不确定的。
*
* @param tasks the collection of tasks
* @return A list of Futures representing the tasks, in the same
*         sequential order as produced by the iterator for the
*         given task list, each of which has completed.
*         表示任务的 Future 列表，列表顺序与给定任务列表的迭代器所生成的顺序相同，
*         每个任务都已完成。
*
* @throws InterruptedException if interrupted while waiting, in
*         which case unfinished tasks are cancelled.
*         - 如果等待时发生中断，在这种情况下取消尚未完成的任务。
*
* @throws NullPointerException if tasks or any of its elements are <tt>null</tt>
* @throws RejectedExecutionException if any task cannot be
*         scheduled for execution
*/

<T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
throws InterruptedException;

/**
* Executes the given tasks, returning a list of Futures holding
* their status and results
* when all complete or the timeout expires, whichever happens first.
* {@link Future#isDone} is <tt>true</tt> for each
* element of the returned list.
* Upon return, tasks that have not completed are cancelled.
* Note that a <em>completed</em> task could have
* terminated either normally or by throwing an exception.
* The results of this method are undefined if the given
* collection is modified while this operation is in progress.
*
* 执行给定的任务，当所有任务完成或超时期满时（无论哪个首先发生），
* 返回保持任务状态和结果的 Future 列表。返回列表的所有元素的 Future.isDone() 为 true。
* 一旦返回后，即取消尚未完成的任务。
* 注意，可以正常地或通过抛出异常来终止已完成 任务。
* 如果此操作正在进行时修改了给定的 collection，则此方法的结果是不确定的。
*
* @param tasks the collection of tasks
* @param timeout the maximum time to wait  最长等待时间
* @param unit the time unit of the timeout argument
* @return a list of Futures representing the tasks, in the same
*         sequential order as produced by the iterator for the
*         given task list. If the operation did not time out,
*         each task will have completed. If it did time out, some
*         of these tasks will not have completed.
*         表示任务的 Future 列表，列表顺序与给定任务列表的迭代器所生成的顺序相同。
*         如果操作未超时，则已完成所有任务。如果确实超时了，则某些任务尚未完成。
*
* @throws InterruptedException if interrupted while waiting, in
*         which case unfinished tasks are cancelled
* @throws NullPointerException if tasks, any of its elements, or
*         unit are <tt>null</tt>
* @throws RejectedExecutionException if any task cannot be scheduled
*         for execution
*/
<T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks,
long timeout, TimeUnit unit)
throws InterruptedException;

/**
* Executes the given tasks, returning the result
* of one that has completed successfully (i.e., without throwing
* an exception), if any do. Upon normal or exceptional return,
* tasks that have not completed are cancelled.
* The results of this method are undefined if the given
* collection is modified while this operation is in progress.
*
* 执行给定的任务，如果某个任务已成功完成（也就是未抛出异常），则返回其结果。
* 一旦正常或异常返回后，则取消尚未完成的任务。如果此操作正在进行时修改了给定的 collection，
* 则此方法的结果是不确定的。
*
* @param tasks the collection of tasks
* @return the result returned by one of the tasks  某个任务返回的结果
*
* @throws InterruptedException if interrupted while waiting 如果等待时发生中断
* @throws NullPointerException if tasks or any element task
*         subject to execution is <tt>null</tt>  如果任务或其任意元素为 null
*
* @throws IllegalArgumentException if tasks is empty
* @throws ExecutionException if no task successfully completes
* @throws RejectedExecutionException if tasks cannot be scheduled
*         for execution
*/
<T> T invokeAny(Collection<? extends Callable<T>> tasks)
throws InterruptedException, ExecutionException;

/**
* Executes the given tasks, returning the result
* of one that has completed successfully (i.e., without throwing
* an exception), if any do before the given timeout elapses.
* Upon normal or exceptional return, tasks that have not
* completed are cancelled.
* The results of this method are undefined if the given
* collection is modified while this operation is in progress.
*
* 执行给定的任务，如果在给定的超时期满前某个任务已成功完成（也就是未抛出异常），则返回其结果。
* 一旦正常或异常返回后，则取消尚未完成的任务。如果此操作正在进行时修改了给定的 collection，
* 则此方法的结果是不确定的。
*
* @param tasks the collection of tasks  - 任务 collection
* @param timeout the maximum time to wait - 最长等待时间
* @param unit the time unit of the timeout argument - timeout 参数的时间单位
*
* @return the result returned by one of the tasks.  某个任务返回的结果
*
* @throws InterruptedException if interrupted while waiting - 如果等待时发生中断
* @throws NullPointerException if tasks, or unit, or any element
*         task subject to execution is <tt>null</tt>  - 如果任务或其任意元素或 unit 为 null
*
* @throws TimeoutException if the given timeout elapses before
*         any task successfully completes  - 如果在所有任务成功完成之前给定的超时期满
* @throws ExecutionException if no task successfully completes  - 如果没有任务成功完成
* @throws RejectedExecutionException if tasks cannot be scheduled  - 如果任务无法安排执行
*         for execution
*/
<T> T invokeAny(Collection<? extends Callable<T>> tasks,
long timeout, TimeUnit unit)
throws InterruptedException, ExecutionException, TimeoutException;
}