ExecutorService 源码每个方法的介绍 告别迷糊

 摘要：最近发现网上很多讲解 shutdown  shutdownNow 等方法分文章，说的云里雾里，闲着没事，看了看源码，顺带英文原文，彻底了解这些方法，后续会将线程池这块知识慢慢补充上来。

public interface ExecutorService extends Executor {

    /**
	   对已经提交的线程启动一个有序的关闭
     * Initiates an orderly shutdown in which previously submitted
	   线程池中已经提交的task会正常运行，但是线程池不接受新的task即新的线程任务
     * tasks are executed, but no new tasks will be accepted.
	   对于已经关闭的线程池没有任何影响
     * Invocation has no additional effect if already shut down.
     *
     *
     */
     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.
     *
	 这个方法不会像awaitTermination方法一样，它不会等待活跃线程执行完毕
     * <p>This method does not wait for actively executing tasks to
     * terminate.  Use {@link #awaitTermination awaitTermination} to
     * do that.
     *  
	 
	   它只是尽可能尝试去停止正在运行的活跃线程，但是不做任何保证。
     * <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.
     *返回未被执行的任务列表
     * @return list of tasks that never commenced execution
     */
    List<Runnable> shutdownNow();

    /**
	  若线程池已经调用了 shutdown此方法会返回true
     * Returns {@code true} if this executor has been shut down.
     *
     * @return {@code true} if this executor has been shut down
     */
    boolean isShutdown();



    /**
	  在线程池调用shutdiown之后，直到最后线程中中所有正在运行的任务结束，该方法回返回true
     * Returns {@code true} if all tasks have completed following shut down.
	  注意：若你在线程池没有调用shutdown 或者shutdownNoe  的时候调用了isTerminated，那么将永远返回true
     * Note that {@code isTerminated} is never {@code true} unless
     * either {@code shutdown} or {@code shutdownNow} was called first.
     *当池中所有的task运行完毕，才会返回true
     * @return {@code true} if all tasks have completed following shut down
     */
    boolean isTerminated();



    /**
	  要么调用shutdown之后所有task执行完毕，要么超时又或者调用了中断，否则的话这个方法会一直阻塞等待。
	  下面这个方法是友好的，因为如果是僵尸线程，在你调用isTerminated的时候将会永远False.
     * 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
     * @return {@code true} if this executor terminated and
     *         {@code false} if the timeout elapsed before termination
     * @throws InterruptedException if interrupted while waiting
     */
    boolean awaitTermination(long timeout, TimeUnit unit)
        throws InterruptedException;



    /**
	*submit  往执行器中提交一个任务，返回一个Future对象，future中包含该任务的返回值。
	 *Future中的我get方法可以获取到该返回值
     * Submits a value-returning task for execution and returns a
     * Future representing the pending results of the task. The
     * Future's {@code get} method will return the task's result upon
     * successful completion.
     *
     * <p>
	    若你想阻塞等待某个任务，可以这样：exec.submit(aCallable).get()
     * If you would like to immediately block waiting
     * for a task, you can use constructions of the form
     * {@code result = exec.submit(aCallable).get();}
        task 是要提交的线程
     * @param task the task to submit
	   T是该线程返回值的类型(泛型)
     * @param <T> the type of the task's result
     * @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(Callable<T> task);



    /**
	 submit  往执行器中提交一个任务，返回一个Future对象，future中包含该任务的返回值。
	 *Future中的我get方法可以获取到result
     */
	 
	 
    <T> Future<T> submit(Runnable task, T result);

    /**
     下面的submit 无返回值，或者说返回值是NULL
     * @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);

    /**
	  执行集合中的所有线程当所有的线程执行完毕之后，将每个线程的执行结果用Future<T>包裹之后房屋集合中，
	  之后返回包含所有线程执行结果的集合。和submit不同的是，批量执行，批量返回。
     * Executes the given tasks, returning a list of Futures holding
     * their status and results when all complete.
     * {@link Future#isDone} is {@code true} 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.
     *
     * @param tasks the collection of tasks(线程集合)
     * @param <T> the type of the values returned from the 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
     * @throws InterruptedException if interrupted while waiting, in
     *         which case unfinished tasks are cancelled
     * @throws NullPointerException if tasks or any of its elements are {@code null}
     * @throws RejectedExecutionException if any task cannot be
     *         scheduled for execution
     */
    <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
        throws InterruptedException;

    /**
	  执行集合中的所有线程当所有的线程执行完毕之后，将每个线程的执行结果用Future<T>包裹之后房屋集合中，
	  之后返回包含所有线程执行结果的集合。和submit不同的是，批量执行，批量返回。
	  当集合中存在某个僵尸线程的时候，任务迟迟无法完成，这里设置了超时，也就是到了超时时间之后会返回结果，不再等待。
     * 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 {@code true} 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.
     *
     * @param tasks the collection of tasks
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @param <T> the type of the values returned from the tasks
     * @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.
     * @throws InterruptedException if interrupted while waiting, in
     *         which case unfinished tasks are cancelled
     * @throws NullPointerException if tasks, any of its elements, or
     *         unit are {@code null}
     * @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;

    /**
	   参数是一个集合，集合中的每个线程任务都继承自Callable<T>，当集合中的任意一个线程完成时就返回该线程的返回值，
	   同时取消其他的线程。
     *
     * @param tasks the collection of tasks
     * @param <T> the type of the values returned from the 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 {@code 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;

    /**
     参数是一个集合，集合中的每个线程任务都继承自Callable<T>，当集合中的任意一个线程完成时就返回该线程的返回值，
	   同时取消其他的线程。 同时支持超时参数。
     * @param tasks the collection of tasks
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @param <T> the type of the values returned from the tasks
     * @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 {@code 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;
}