/**
 * ctl维护两个概念上的参数：runState和workCount
 * runState表示线程池的运行状态，workCount表示有效的线程数量
 */
private final AtomicInteger ctl = new AtomicInteger(ctlOf(RUNNING, 0));

// 用于计算runState的二进制移位数，即32 - 3 = 29
private static final int COUNT_BITS = Integer.SIZE - 3;

// 容量是1 << 29 - 1，即低29位用于表示最大容量（最大只能是2^29 - 1）
private static final int CAPACITY   = (1 << COUNT_BITS) - 1;

// 高3位用于表示运行状态
// runState is stored in the high-order bits
private static final int RUNNING    = -1 << COUNT_BITS; // 高三位为111
private static final int SHUTDOWN   =  0 << COUNT_BITS; // 高三位为000
private static final int STOP       =  1 << COUNT_BITS; // 高三位为001
private static final int TIDYING    =  2 << COUNT_BITS; // 高三位为010
private static final int TERMINATED =  3 << COUNT_BITS; // 高三位为011

// Packing and unpacking ctl
// 从ctl中获取运行状态
private static int runStateOf(int c)     { return c & ~CAPACITY; }
// 从ctl中获取有效的线程数量
private static int workerCountOf(int c)  { return c & CAPACITY; }
// 根据运行状态和有效的线程数量获取ctl
private static int ctlOf(int rs, int wc) { return rs | wc; }

/*
 * Bit field accessors that don't require unpacking ctl.
 * These depend on the bit layout and on workerCount being never negative.
 */
// 比较运行状态
private static boolean runStateLessThan(int c, int s) {
    return c < s;
}

private static boolean runStateAtLeast(int c, int s) {
    return c >= s;
}

// 判断是否是运行状态
private static boolean isRunning(int c) {
    return c < SHUTDOWN;
}

/**
 * Attempt to CAS-increment the workerCount field of ctl.
 * CAS方式自增workCount
 */
private boolean compareAndIncrementWorkerCount(int expect) {
    return ctl.compareAndSet(expect, expect + 1);
}

/**
 * Attempt to CAS-decrement the workerCount field of ctl.
 * CAS方式自减workCount
 */
private boolean compareAndDecrementWorkerCount(int expect) {
    return ctl.compareAndSet(expect, expect - 1);
}

/**
 * Decrements the workerCount field of ctl. This is called only on
 * abrupt termination of a thread (see processWorkerExit). Other
 * decrements are performed within getTask.
 *
 * 自减workerCount，如果失败就自旋直至成功
 */
private void decrementWorkerCount() {
    do {} while (! compareAndDecrementWorkerCount(ctl.get()));
}

/**
 * Transitions runState to given target, or leaves it alone if
 * already at least the given target.
 *
 * 将runState转换为给定的targetState
 *
 * @param targetState the desired state, either SHUTDOWN or STOP
 *        (but not TIDYING or TERMINATED -- use tryTerminate for that)
 */
private void advanceRunState(int targetState) {
    for (;;) {
        // 获取ctl的值
        int c = ctl.get();
        // 只有在runState大于或等于targetState，才能转换
        if (runStateAtLeast(c, targetState) ||
                // 通过CAS方式修改ctl的runState为targetState
                ctl.compareAndSet(c, ctlOf(targetState, workerCountOf(c))))
            break;
    }
}

private final AtomicInteger ctl = new AtomicInteger(ctlOf(RUNNING, 0));

/**
 * The queue used for holding tasks and handing off to worker
 * threads.  We do not require that workQueue.poll() returning
 * null necessarily means that workQueue.isEmpty(), so rely
 * solely on isEmpty to see if the queue is empty (which we must
 * do for example when deciding whether to transition from
 * SHUTDOWN to TIDYING).  This accommodates special-purpose
 * queues such as DelayQueues for which poll() is allowed to
 * return null even if it may later return non-null when delays
 * expire.
 *
 * 阻塞队列
 */
private final BlockingQueue<Runnable> workQueue;

/**
 * Lock held on access to workers set and related bookkeeping.
 * While we could use a concurrent set of some sort, it turns out
 * to be generally preferable to use a lock. Among the reasons is
 * that this serializes interruptIdleWorkers, which avoids
 * unnecessary interrupt storms, especially during shutdown.
 * Otherwise exiting threads would concurrently interrupt those
 * that have not yet interrupted. It also simplifies some of the
 * associated statistics bookkeeping of largestPoolSize etc. We
 * also hold mainLock on shutdown and shutdownNow, for the sake of
 * ensuring workers set is stable while separately checking
 * permission to interrupt and actually interrupting.
 *
 * 主要的锁对象
 */
private final ReentrantLock mainLock = new ReentrantLock();

/**
 * Set containing all worker threads in pool. Accessed only when
 * holding mainLock.
 *
 * 用于存放worker
 */
private final HashSet<Worker> workers = new HashSet<Worker>();

/**
 * Wait condition to support awaitTermination
 *
 * 用于支持awaitTermination的等待队列
 */
private final Condition termination = mainLock.newCondition();

/**
 * Tracks largest attained pool size. Accessed only under mainLock.
 * 记录最大线程池大小，仅在获取锁的前提下可以访问
 */
private int largestPoolSize;

/**
 * Counter for completed tasks. Updated only on termination of
 * worker threads. Accessed only under mainLock.
 * 用于记录已完成的任务数
 * 仅在获取锁的前提下，worker线程终止时进行更新
 */
private long completedTaskCount;

/*
 * All user control parameters are declared as volatiles so that
 * ongoing actions are based on freshest values, but without need
 * for locking, since no internal invariants depend on them
 * changing synchronously with respect to other actions.
 */

/**
 * Factory for new threads. All threads are created using this
 * factory (via method addWorker).  All callers must be prepared
 * for addWorker to fail, which may reflect a system or user's
 * policy limiting the number of threads.  Even though it is not
 * treated as an error, failure to create threads may result in
 * new tasks being rejected or existing ones remaining stuck in
 * the queue. On the other hand, no special precautions exist to
 * handle OutOfMemoryErrors that might be thrown while trying to
 * create threads, since there is generally no recourse from
 * within this class.
 *
 * 线程工厂。所有线程都是使用线程工厂来创建的
 */
private volatile ThreadFactory threadFactory;

/**
 * Handler called when saturated or shutdown in execute.
 * 当线程池饱和或关闭时，导致任务失败时的回调，用于通知调用者
 */
private volatile RejectedExecutionHandler handler;

/**
 * Timeout in nanoseconds for idle threads waiting for work.
 * Threads use this timeout when there are more than corePoolSize
 * present or if allowCoreThreadTimeOut. Otherwise they wait
 * forever for new work.
 * 等待线程最大的超时时间
 */
private volatile long keepAliveTime;

/**
 * If false (default), core threads stay alive even when idle.
 * If true, core threads use keepAliveTime to time out waiting
 * for work.
 * 当该值为false时，核心线程在空闲时也会保持活跃；这是默认值；
 * 当该值为true时，核心线程在空闲期间会有根据keepAliveTime计算等待任务的超时时间
 */
private volatile boolean allowCoreThreadTimeOut;

/**
 * Core pool size is the minimum number of workers to keep alive
 * (and not allow to time out etc) unless allowCoreThreadTimeOut
 * is set, in which case the minimum is zero.
 *
 * 核心池大小，保持存活的worker的最小数量（默认会忽略超时）
 * 但如果设置了allowCoreTimeOut为true，那么当核心线程闲置时会被回收。
 */
private volatile int corePoolSize;

/**
 * Maximum pool size. Note that the actual maximum is internally
 * bounded by CAPACITY.
 *
 * 最大线程池尺寸，被CAPACITY限制（2^29 - 1）
 */
private volatile int maximumPoolSize;

/**
 * The default rejected execution handler
 * 默认的拒绝执行策略处理器
 */
private static final RejectedExecutionHandler defaultHandler = new AbortPolicy();

/**
 * Permission required for callers of shutdown and shutdownNow.
 * We additionally require (see checkShutdownAccess) that callers
 * have permission to actually interrupt threads in the worker set
 * (as governed by Thread.interrupt, which relies on
 * ThreadGroup.checkAccess, which in turn relies on
 * SecurityManager.checkAccess). Shutdowns are attempted only if
 * these checks pass.
 *
 * All actual invocations of Thread.interrupt (see
 * interruptIdleWorkers and interruptWorkers) ignore
 * SecurityExceptions, meaning that the attempted interrupts
 * silently fail. In the case of shutdown, they should not fail
 * unless the SecurityManager has inconsistent policies, sometimes
 * allowing access to a thread and sometimes not. In such cases,
 * failure to actually interrupt threads may disable or delay full
 * termination. Other uses of interruptIdleWorkers are advisory,
 * and failure to actually interrupt will merely delay response to
 * configuration changes so is not handled exceptionally.
 */
private static final RuntimePermission shutdownPerm = new RuntimePermission("modifyThread");

/**
 * Class Worker mainly maintains interrupt control state for
 * threads running tasks, along with other minor bookkeeping.
 * This class opportunistically extends AbstractQueuedSynchronizer
 * to simplify acquiring and releasing a lock surrounding each
 * task execution.  This protects against interrupts that are
 * intended to wake up a worker thread waiting for a task from
 * instead interrupting a task being run.  We implement a simple
 * non-reentrant mutual exclusion lock rather than use ReentrantLock
 * because we do not want worker tasks to be able to reacquire the
 * lock when they invoke pool control methods like setCorePoolSize.
 *
 * Worker线程类，该类是AQS的子类
 */
private final class Worker extends AbstractQueuedSynchronizer implements Runnable
{
    /**
     * This class will never be serialized, but we provide a
     * serialVersionUID to suppress a javac warning.
     *
     * 该类不会被序列化，提供serialVersionUID是为了压制警告信息
     */
    private static final long serialVersionUID = 6138294804551838833L;

    /**
     * Thread this worker is running in.  Null if factory fails.
     * Worker所运行的线程
     * */
    final Thread thread;
    /**
     * Initial task to run.  Possibly null.
     * 运行的初始任务，是一个Runnable对象，可能为null
     * */
    Runnable firstTask;
    /**
     * Per-thread task counter
     * 当前Worker完成的任务数
     * */
    volatile long completedTasks;

    /**
     * Creates with given first task and thread from ThreadFactory.
     * 通过给定的firstTask和从ThreadFactory获取的线程创建一个Worker
     * @param firstTask the first task (null if none)
     */
    Worker(Runnable firstTask) {
        this.firstTask = firstTask;
        this.thread = getThreadFactory().newThread(this);
    }

    /**
     * Delegates main run loop to outer runWorker
     * 用于运行Worker
     * */
    public void run() {
        // 将主要的运行逻辑交给runWorker()方法
        runWorker(this);
    }

    // Lock methods
    //
    // The value 0 represents the unlocked state.
    // The value 1 represents the locked state.
    // 是否拥有独占锁
    protected boolean isHeldExclusively() {
        return getState() == 1;
    }

    // 尝试获取独占锁
    protected boolean tryAcquire(int unused) {
        if (compareAndSetState(0, 1)) {
            setExclusiveOwnerThread(Thread.currentThread());
            return true;
        }
        return false;
    }

    // 尝试释放独占锁
    protected boolean tryRelease(int unused) {
        setExclusiveOwnerThread(null);
        setState(0);
        return true;
    }

    // 获取锁
    public void lock()        { acquire(1); }
    // 尝试获取锁
    public boolean tryLock()  { return tryAcquire(1); }
    // 释放锁
    public void unlock()      { release(1); }
    // 判断是否拥有锁
    public boolean isLocked() { return isHeldExclusively(); }
}

// 使用默认的线程工厂和拒绝策略处理器创建线程池
public ThreadPoolExecutor(int corePoolSize,
                          int maximumPoolSize,
                          long keepAliveTime,
                          TimeUnit unit,
                          BlockingQueue<Runnable> workQueue) {
    this(corePoolSize, maximumPoolSize, keepAliveTime, unit, workQueue,
            Executors.defaultThreadFactory(), defaultHandler);
}

// 使用默认拒绝策略处理器创建线程池
public ThreadPoolExecutor(int corePoolSize,
                          int maximumPoolSize,
                          long keepAliveTime,
                          TimeUnit unit,
                          BlockingQueue<Runnable> workQueue,
                          ThreadFactory threadFactory) {
    this(corePoolSize, maximumPoolSize, keepAliveTime, unit, workQueue,
            threadFactory, defaultHandler);
}

// 使用默认的线程工厂创建线程池
public ThreadPoolExecutor(int corePoolSize,
                          int maximumPoolSize,
                          long keepAliveTime,
                          TimeUnit unit,
                          BlockingQueue<Runnable> workQueue,
                          RejectedExecutionHandler handler) {
    this(corePoolSize, maximumPoolSize, keepAliveTime, unit, workQueue,
            Executors.defaultThreadFactory(), handler);
}

// 根据传入的参数创建线程池
public ThreadPoolExecutor(int corePoolSize,
                          int maximumPoolSize,
                          long keepAliveTime,
                          TimeUnit unit,
                          BlockingQueue<Runnable> workQueue,
                          ThreadFactory threadFactory,
                          RejectedExecutionHandler handler) {
    /**
     * 检查各类参数，
     * maximumPoolSize要大于0，
     * corePoolSize不能小于0，且corePoolSize不能大于maximumPoolSize
     * keepAliveTime不能小于0
     */
    if (corePoolSize < 0 ||
            maximumPoolSize <= 0 ||
            maximumPoolSize < corePoolSize ||
            keepAliveTime < 0)
        throw new IllegalArgumentException();
    // 工作队列，线程工厂和拒绝处理器不能为null
    if (workQueue == null || threadFactory == null || handler == null)
        throw new NullPointerException();
    // 对各项参数赋值
    this.corePoolSize = corePoolSize;
    this.maximumPoolSize = maximumPoolSize;
    this.workQueue = workQueue;
    this.keepAliveTime = unit.toNanos(keepAliveTime);
    this.threadFactory = threadFactory;
    this.handler = handler;
}

// Executors的defaultThreadFactory()方法
public static ThreadFactory defaultThreadFactory() {
    return new DefaultThreadFactory();
}

// DefaultThreadFactory类
static class DefaultThreadFactory implements ThreadFactory {
    private static final AtomicInteger poolNumber = new AtomicInteger(1);
    private final ThreadGroup group;
    private final AtomicInteger threadNumber = new AtomicInteger(1);
    private final String namePrefix;

    DefaultThreadFactory() {
        SecurityManager s = System.getSecurityManager();
        group = (s != null) ? s.getThreadGroup() : Thread.currentThread().getThreadGroup();
        // 线程名前缀
        namePrefix = "pool-" + poolNumber.getAndIncrement() + "-thread-";
    }

    public Thread newThread(Runnable r) {
        // 创建线程
        Thread t = new Thread(group, r, namePrefix + threadNumber.getAndIncrement(), 0);
        // 设置线程为非守护线程
        if (t.isDaemon())
            t.setDaemon(false);
        // 设置线程的优先级为NORM_PRIORITY
        if (t.getPriority() != Thread.NORM_PRIORITY)
            t.setPriority(Thread.NORM_PRIORITY);
        return t;
    }
}

// 默认使用AbortPolicy拒绝策略处理器
private static final RejectedExecutionHandler defaultHandler = new AbortPolicy();

/**
 * 将传入的Runnable包装为一个RunnableFuture对象，交由execute(Runnable)方法处理
 * 
 * @throws RejectedExecutionException {@inheritDoc}
 * @throws NullPointerException       {@inheritDoc}
 */
public Future<?> submit(Runnable task) {
    if (task == null) throw new NullPointerException();
    RunnableFuture<Void> ftask = newTaskFor(task, null);
    execute(ftask);
    return ftask;
}

/**
 * 将传入的Runnable和默认结果值包装为一个RunnableFuture对象，交由execute(Runnable)方法处理
 * 
 * @throws RejectedExecutionException {@inheritDoc}
 * @throws NullPointerException       {@inheritDoc}
 */
public <T> Future<T> submit(Runnable task, T result) {
    if (task == null) throw new NullPointerException();
    RunnableFuture<T> ftask = newTaskFor(task, result);
    execute(ftask);
    return ftask;
}

/**
 * 将传入的Callable包装为一个RunnableFuture对象，交由execute(Runnable)方法处理
 * 
 * @throws RejectedExecutionException {@inheritDoc}
 * @throws NullPointerException       {@inheritDoc}
 */
public <T> Future<T> submit(Callable<T> task) {
    if (task == null) throw new NullPointerException();
    RunnableFuture<T> ftask = newTaskFor(task);
    execute(ftask);
    return ftask;
}

/**
 * Executes the given task sometime in the future.  The task
 * may execute in a new thread or in an existing pooled thread.
 *
 * If the task cannot be submitted for execution, either because this
 * executor has been shutdown or because its capacity has been reached,
 * the task is handled by the current {@code RejectedExecutionHandler}.
 *
 * @param command the task to execute
 * @throws RejectedExecutionException at discretion of
 *         {@code RejectedExecutionHandler}, if the task
 *         cannot be accepted for execution
 * @throws NullPointerException if {@code command} is null
 */
public void execute(Runnable command) {
    // 参数检查
    if (command == null)
        throw new NullPointerException();
    /*
        * Proceed in 3 steps:
        *
        * 1. If fewer than corePoolSize threads are running, try to
        * start a new thread with the given command as its first
        * task.  The call to addWorker atomically checks runState and
        * workerCount, and so prevents false alarms that would add
        * threads when it shouldn't, by returning false.
        *
        * 2. If a task can be successfully queued, then we still need
        * to double-check whether we should have added a thread
        * (because existing ones died since last checking) or that
        * the pool shut down since entry into this method. So we
        * recheck state and if necessary roll back the enqueuing if
        * stopped, or start a new thread if there are none.
        *
        * 3. If we cannot queue task, then we try to add a new
        * thread.  If it fails, we know we are shut down or saturated
        * and so reject the task.
        */
    // 获取ctl值
    int c = ctl.get();
    // 计算workerCount是否小于corePoolSize
    if (workerCountOf(c) < corePoolSize) {
        /**
         * 如果小于，就调用addWorker()方法新建一个Worker线程来处理任务
         * 这里传入的core参数为true，表示创建的是核心线程
         */
        if (addWorker(command, true))
            // 如果添加成功，直接返回
            return;
        // 否则重新拿到ctl的值
        c = ctl.get();
    }
    /**
     * 走到这里，说明workerCount是大于等于corePoolSize的
     * 检查当前的runState是否是RUNNING，
     * 如果是，就将传入的command任务放入workQueue等待队列
     */
    if (isRunning(c) && workQueue.offer(command)) {
        // 放入等待队列成功之后，重新获取ctl的值进行检查
        int recheck = ctl.get();
        // 如果runState不是RUNNING状态，则将command任务从workQueue队列移除
        if (! isRunning(recheck) && remove(command))
            // 然后调用reject拒绝任务，底层会使用拒绝策略进行处理
            reject(command);
        // 否则如果workerCount为0，则新建一个线程（firstTask为null，core为false，非核心线程）
        else if (workerCountOf(recheck) == 0)
            addWorker(null, false);
    }
    /**
     * 走到这里说明将任务添加到workQueue失败了，等待队列已满，
     * 则创建一个非核心线程来处理任务
     */
    else if (!addWorker(command, false))
        // 如果创建失败则调用reject拒绝任务
        reject(command);
}

/**
 * Invokes the rejected execution handler for the given command.
 * Package-protected for use by ScheduledThreadPoolExecutor.
 *
 * 拒绝任务
 */
final void reject(Runnable command) {
    // 使用拒绝任务处理器来拒绝任务的执行
    handler.rejectedExecution(command, this);
}

/* Predefined RejectedExecutionHandlers */

/**
 * A handler for rejected tasks that runs the rejected task
 * directly in the calling thread of the {@code execute} method,
 * unless the executor has been shut down, in which case the task
 * is discarded.
 *
 * 调用者运行策略
 * 当线程池拒绝接受任务后，会由调用者自行运行任务
 */
public static class CallerRunsPolicy implements RejectedExecutionHandler {
    /**
     * Creates a {@code CallerRunsPolicy}.
     */
    public CallerRunsPolicy() { }

    /**
     * Executes task r in the caller's thread, unless the executor
     * has been shut down, in which case the task is discarded.
     *
     * @param r the runnable task requested to be executed
     * @param e the executor attempting to execute this task
     */
    public void rejectedExecution(Runnable r, ThreadPoolExecutor e) {
        // 如果线程池还未关闭，就直接运行任务
        if (!e.isShutdown()) {
            // 不启动新的线程，直接调用任务的run()方法
            r.run();
        }
    }
}

/**
 * A handler for rejected tasks that throws a
 * {@code RejectedExecutionException}.
 *
 * 中止策略，会直接抛出异常
 */
public static class AbortPolicy implements RejectedExecutionHandler {
    /**
     * Creates an {@code AbortPolicy}.
     */
    public AbortPolicy() { }

    /**
     * Always throws RejectedExecutionException.
     *
     * @param r the runnable task requested to be executed
     * @param e the executor attempting to execute this task
     * @throws RejectedExecutionException always.
     */
    public void rejectedExecution(Runnable r, ThreadPoolExecutor e) {
        throw new RejectedExecutionException("Task " + r.toString() +
                " rejected from " +
                e.toString());
    }
}

/**
 * A handler for rejected tasks that silently discards the
 * rejected task.
 * 抛弃策略，直接抛弃任务，不会做任何处理
 */
public static class DiscardPolicy implements RejectedExecutionHandler {
    /**
     * Creates a {@code DiscardPolicy}.
     */
    public DiscardPolicy() { }

    /**
     * Does nothing, which has the effect of discarding task r.
     *
     * @param r the runnable task requested to be executed
     * @param e the executor attempting to execute this task
     */
    public void rejectedExecution(Runnable r, ThreadPoolExecutor e) {
    }
}

/**
 * A handler for rejected tasks that discards the oldest unhandled
 * request and then retries {@code execute}, unless the executor
 * is shut down, in which case the task is discarded.
 *
 * 抛弃最旧策略，会将等待队列中等待最久的任务放弃执行，然后添加被拒绝的任务
 */
public static class DiscardOldestPolicy implements RejectedExecutionHandler {
    /**
     * Creates a {@code DiscardOldestPolicy} for the given executor.
     */
    public DiscardOldestPolicy() { }

    /**
     * Obtains and ignores the next task that the executor
     * would otherwise execute, if one is immediately available,
     * and then retries execution of task r, unless the executor
     * is shut down, in which case task r is instead discarded.
     *
     * @param r the runnable task requested to be executed
     * @param e the executor attempting to execute this task
     */
    public void rejectedExecution(Runnable r, ThreadPoolExecutor e) {
        // 如果线程池没有关闭
        if (!e.isShutdown()) {
            // 将等待最久的的任务移除，放弃执行
            e.getQueue().poll();
            // 然后添加被拒绝的任务
            e.execute(r);
        }
    }
}

/**
 * Checks if a new worker can be added with respect to current
 * pool state and the given bound (either core or maximum). If so,
 * the worker count is adjusted accordingly, and, if possible, a
 * new worker is created and started running firstTask as its
 * first task. This method returns false if the pool is stopped or
 * eligible to shut down. It also returns false if the thread
 * factory fails to create a thread when asked, which requires a
 * backout of workerCount, and a recheck for termination, in case
 * the existence of this worker was holding up termination.
 *
 * 添加Worker
 *
 * @param firstTask the task the new thread should run first (or
 * null if none). Workers are created with an initial first task
 * (in method execute()) to bypass queuing when there are fewer
 * than corePoolSize threads (in which case we always start one),
 * or when the queue is full (in which case we must bypass queue).
 * Initially idle threads are usually created via
 * prestartCoreThread or to replace other dying workers.
 *
 * @param core if true use corePoolSize as bound, else
 * maximumPoolSize. (A boolean indicator is used here rather than a
 * value to ensure reads of fresh values after checking other pool
 * state). 当core为true时以corePoolSize为上限，否则以maximumPoolSize为上限
 * @return true if successful
 */
private boolean addWorker(Runnable firstTask, boolean core) {
    retry:
    for (;;) {
        // 获取runState
        int c = ctl.get();
        int rs = runStateOf(c);

        // Check if queue empty only if necessary.
        /**
         * 如果runState大于等于SHUTDOWN（即为SHUTDOWN、STOP、TIDYING或TERMINATED），则返回false，
         * 即如果线程池停止或有资格关闭，则此方法返回false；分为以下五种情况：
         * 1，如果runState为STOP、TIDYING或TERMINATED则直接返回false；
         *    这三个状态表示已经进入最后的清理终止，不接受任务不处理队列任务。
         * 2，如果runState为SHUTDOWN，但firstTask不为null时直接返回false；
         *    SHUTDOWN状态表示不接受任务但处理队列任务，因此任务不为null时返回false。
         * 3，如果runState为SHUTDOWN，firstTask为null，但workQueue为空时直接返回false；
         *    此时线程池有资格关闭，因此会直接返回false。
         * 4. 如果runState为SHUTDOWN，firstTask为null，但workQueue不为为空，通过校验；
         *    SHUTDOWN状态下可以处理队列任务。
         * 5. runState为RUNNING，通过检验。
         */
        if (rs >= SHUTDOWN &&
                ! (rs == SHUTDOWN && firstTask == null && ! workQueue.isEmpty()))
            return false;

        // 状态符合条件，使用无限for循环
        for (;;) {
            // 获取workerCount
            int wc = workerCountOf(c);
            /**
             * core参数可用于判断添加的是否是核心线程；
             * 如果workerCount大于等于CAPACITY，表示线程池已经满了，无法添加Worker，直接返回false结束；
             * 或者当添加核心线程时，workerCount大于等于corePoolSize，无法添加Worker，直接返回false结束；
             * 当添加非核心线程时，workerCount大于等于maximumPoolSize，无法添加Worker，直接返回false结束；
             */
            if (wc >= CAPACITY ||
                    wc >= (core ? corePoolSize : maximumPoolSize))
                return false;
            // 如果成功将workerCount加1，那么跳出外层循环
            if (compareAndIncrementWorkerCount(c))
                break retry;
            /**
             * 走到这里说明尝试workerCount加1失败，
             * 重新获取runState与之前保存的runState值rs对比，如果不同说明runState被改变了，
             * 因此直接开始下一次外层循环重新尝试
             */
            c = ctl.get();  // Re-read ctl
            if (runStateOf(c) != rs)
                continue retry;
            // else CAS failed due to workerCount change; retry inner loop
        }
    }

    // 使用firstTask创建一个新的Worker
    Worker w = new Worker(firstTask);
    // 获取Worker线程
    Thread t = w.thread;

    // 加锁
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();
    try {
        // Recheck while holding lock.
        // Back out on ThreadFactory failure or if
        // shut down before lock acquired.
        // 获取ctl和runState
        int c = ctl.get();
        int rs = runStateOf(c);

        /**
         * 如果创建的Worker线程为null，即线程工厂创建线程失败
         * 或者虽然创建的Worker线程不为null，但runState被关闭了（处于STOP、TIDYING或TERMINATED状态）
         * 且如果runState处于SHUTDOWN，且firstTask不为null
         * 说明无法创建Worker
         */
        if (t == null || (rs >= SHUTDOWN && ! (rs == SHUTDOWN && firstTask == null))) {
            // 将workerCount减1
            decrementWorkerCount();
            // 尝试将runState转换为TERMINATED，并返回false表示添加Worker失败
            tryTerminate();
            return false;
        }

        // 符合条件，添加新创建的worker
        workers.add(w);

        // 更新largestPoolSize
        int s = workers.size();
        if (s > largestPoolSize)
            largestPoolSize = s;
    } finally {
        // 解锁
        mainLock.unlock();
    }

    // 启动worker线程
    t.start();
    // It is possible (but unlikely) for a thread to have been
    // added to workers, but not yet started, during transition to
    // STOP, which could result in a rare missed interrupt,
    // because Thread.interrupt is not guaranteed to have any effect
    // on a non-yet-started Thread (see Thread#interrupt).
    // 如果runState为STOP，且worker线程没有被中断，那么尝试中断worker线程
    if (runStateOf(ctl.get()) == STOP && ! t.isInterrupted())
        t.interrupt();

    return true;
}

/**
 * Main worker run loop.  Repeatedly gets tasks from queue and
 * executes them, while coping with a number of issues:
 *
 * 1. We may start out with an initial task, in which case we
 * don't need to get the first one. Otherwise, as long as pool is
 * running, we get tasks from getTask. If it returns null then the
 * worker exits due to changed pool state or configuration
 * parameters.  Other exits result from exception throws in
 * external code, in which case completedAbruptly holds, which
 * usually leads processWorkerExit to replace this thread.
 *
 * 2. Before running any task, the lock is acquired to prevent
 * other pool interrupts while the task is executing, and
 * clearInterruptsForTaskRun called to ensure that unless pool is
 * stopping, this thread does not have its interrupt set.
 *
 * 3. Each task run is preceded by a call to beforeExecute, which
 * might throw an exception, in which case we cause thread to die
 * (breaking loop with completedAbruptly true) without processing
 * the task.
 *
 * 4. Assuming beforeExecute completes normally, we run the task,
 * gathering any of its thrown exceptions to send to
 * afterExecute. We separately handle RuntimeException, Error
 * (both of which the specs guarantee that we trap) and arbitrary
 * Throwables.  Because we cannot rethrow Throwables within
 * Runnable.run, we wrap them within Errors on the way out (to the
 * thread's UncaughtExceptionHandler).  Any thrown exception also
 * conservatively causes thread to die.
 *
 * 5. After task.run completes, we call afterExecute, which may
 * also throw an exception, which will also cause thread to
 * die. According to JLS Sec 14.20, this exception is the one that
 * will be in effect even if task.run throws.
 *
 * The net effect of the exception mechanics is that afterExecute
 * and the thread's UncaughtExceptionHandler have as accurate
 * information as we can provide about any problems encountered by
 * user code.
 *
 * @param w the worker
 */
final void runWorker(Worker w) {
    // 引用worker的firstTask任务，并清除worker的firstTask
    Runnable task = w.firstTask;
    w.firstTask = null;
    // 用于标识worker是不是因异常而死亡
    boolean completedAbruptly = true;
    try {
        // worker取任务执行
        while (task != null || (task = getTask()) != null) {
            // 加锁
            w.lock();
            clearInterruptsForTaskRun();
            try {
                // 执行beforeExecute()钩子方法
                beforeExecute(w.thread, task);
                // 用于记录运行过程中的异常
                Throwable thrown = null;
                try {
                    // 执行任务
                    task.run();
                } catch (RuntimeException x) {
                    thrown = x; throw x;
                } catch (Error x) {
                    thrown = x; throw x;
                } catch (Throwable x) {
                    thrown = x; throw new Error(x);
                } finally {
                    // 执行afterExecute()钩子方法
                    afterExecute(task, thrown);
                }
            } finally {
                // 将执行完的任务清空
                task = null;
                // 将worker的完成任务数加1
                w.completedTasks++;
                // 解锁
                w.unlock();
            }
        }
        // 运行到这里表示运行过程中没有出现异常
        completedAbruptly = false;
    } finally {
        // 调用processWorkerExit()方法处理Worker的后续清理和退出流程
        processWorkerExit(w, completedAbruptly);
    }
}

/**
 * Ensures that unless the pool is stopping, the current thread
 * does not have its interrupt set. This requires a double-check
 * of state in case the interrupt was cleared concurrently with a
 * shutdownNow -- if so, the interrupt is re-enabled.
 */
private void clearInterruptsForTaskRun() {
    /**
     * 判断当前runState是否为RUNNING或SHUTDOWN，
     * 如果是则判断当前线程是否是中断的（判断同时会清除中断标志位为false），
     * 如果当前线程是中断然后再次判断runState是否为TIDYING或TERMINATED，
     * 如果是，则对当前线程进行中断
     */
    if (runStateLessThan(ctl.get(), STOP) &&
            Thread.interrupted() &&
            runStateAtLeast(ctl.get(), STOP))
        Thread.currentThread().interrupt();
}

/**
 * Performs blocking or timed wait for a task, depending on
 * current configuration settings, or returns null if this worker
 * must exit because of any of:
 * 1. There are more than maximumPoolSize workers (due to
 *    a call to setMaximumPoolSize).
 * 2. The pool is stopped.
 * 3. The pool is shutdown and the queue is empty.
 * 4. This worker timed out waiting for a task, and timed-out
 *    workers are subject to termination (that is,
 *    {@code allowCoreThreadTimeOut || workerCount > corePoolSize})
 *    both before and after the timed wait.
 *
 * @return task, or null if the worker must exit, in which case
 *         workerCount is decremented
 */
private Runnable getTask() {
    // 用于记录poll()方法是否超时
    boolean timedOut = false; // Did the last poll() time out?

    retry:
    // 无限循环
    for (;;) {
        // 获取ctl和runState
        int c = ctl.get();
        int rs = runStateOf(c);

        // 检查状态
        // Check if queue empty only if necessary.
        if (rs >= SHUTDOWN && (rs >= STOP || workQueue.isEmpty())) {
            /**
             * 如果runState为STOP、TIDYING或TERMINATED
             * 或者runState为SHUTDOWN，且workerQueue为空
             * 将workerCount减1，返回null结束运行
             */
            decrementWorkerCount();
            return null;
        }

        // 记录worker是否能够被移除
        boolean timed;      // Are workers subject to culling?

        // 无限循环
        for (;;) {
            // 获取workerCount
            int wc = workerCountOf(c);
            /**
             * 判断当前Worker是否可以被移除，即当前Worker是否可以一直等待任务。
             * 如果allowCoreThreadTimeOut为true，或者workerCount大于核心线程数，
             * 则当前线程是有超时时间的（keepAliveTime），无法一直等待任务
             * 如果allowCoreThreadTimeOut为false，表示核心线程不会超时，
             * 且如果此时workerCount小于等于corePoolSize，则表示这些核心线程将永远存活
             */
            timed = allowCoreThreadTimeOut || wc > corePoolSize;
            // workerCount小于等于核心线程数，且没有超时，则跳出内层循环
            if (wc <= maximumPoolSize && ! (timedOut && timed))
                break;
            // 否则表示已超时，将workerCount减1，如果成功直接返回null
            if (compareAndDecrementWorkerCount(c))
                return null;
            // 走到这里说明上一步workerCount减1失败了，重新读取ctl
            c = ctl.get();  // Re-read ctl
            // 如果与之前的runState不同，表示线程池状态发生改变了，跳出到外层循环重试
            if (runStateOf(c) != rs)
                continue retry;
            // else CAS failed due to workerCount change; retry inner loop
        }

        try {
            /**
             * 根据线程是否会超时来分别调用相应的方法，
             * poll()方法附带超时机制；take()方法没有超时机制，并且可能会阻塞等待
             */
            Runnable r = timed ?
                    workQueue.poll(keepAliveTime, TimeUnit.NANOSECONDS) :
                    workQueue.take();
            // 如果获取到的任务不为null则返回
            if (r != null)
                return r;
            // 走到这里表示获取操作超时了
            timedOut = true;
        } catch (InterruptedException retry) {
            // 被中断，可能是超时等待过程中被中断了
            timedOut = false;
        }
    }
}

/**
 * Performs cleanup and bookkeeping for a dying worker. Called
 * only from worker threads. Unless completedAbruptly is set,
 * assumes that workerCount has already been adjusted to account
 * for exit.  This method removes thread from worker set, and
 * possibly terminates the pool or replaces the worker if either
 * it exited due to user task exception or if fewer than
 * corePoolSize workers are running or queue is non-empty but
 * there are no workers.
 *
 * @param w the worker
 * @param completedAbruptly if the worker died due to user exception
 *                          用于标识Worker线程死亡是否是由于用户产生的异常
 */
private void processWorkerExit(Worker w, boolean completedAbruptly) {
    // completedAbruptly为true，此时workerCount还没有更新，因此需要手动减1
    if (completedAbruptly) // If abrupt, then workerCount wasn't adjusted
        decrementWorkerCount();

    // 获取锁
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();
    try {
        // 更新完成的任务数量
        completedTaskCount += w.completedTasks;
        // 从workers数组中移除w
        workers.remove(w);
    } finally {
        // 解锁
        mainLock.unlock();
    }

    // 尝试终止线程池
    tryTerminate();

    // 获取ctl
    int c = ctl.get();
    // 如果runState状态是SHUTDOWN或RUNNING，即还没有停止
    if (runStateLessThan(c, STOP)) {
        // 如果worker处理任务过程中没有出现异常
        if (!completedAbruptly) {
            /**
             * 获取允许的最小核心线程数，逻辑如下：
             * 1. 如果不允许核心线程超时，则min为核心线程数
             * 2. 如果允许核心线程超时，且workQueue不为空，则min为1，
             *    以确保至少有一个worker来处理队列里的任务
             */
            int min = allowCoreThreadTimeOut ? 0 : corePoolSize;
            if (min == 0 && ! workQueue.isEmpty())
                min = 1;
            // 当workerCount大于等于min时，直接返回，不需要添加新的Worker。
            if (workerCountOf(c) >= min)
                return; // replacement not needed
        }
        /**
         * 添加一个新的Worker线程，走到这里有下面两种情况：
         * 1. worker中的任务因异常而退出了，此时Worker也会因抛出异常而终止，因此需要添加新的Worker；
         * 2. workerCount小于计算出来的最小线程数，有可能是因为核心线程超时了，因此需要添加新的Worker。
         */
        addWorker(null, false);
    }
}

/**
 * Transitions to TERMINATED state if either (SHUTDOWN and pool
 * and queue empty) or (STOP and pool empty).  If otherwise
 * eligible to terminate but workerCount is nonzero, interrupts an
 * idle worker to ensure that shutdown signals propagate. This
 * method must be called following any action that might make
 * termination possible -- reducing worker count or removing tasks
 * from the queue during shutdown. The method is non-private to
 * allow access from ScheduledThreadPoolExecutor.
 *
 * 当runState为SHUTDOWN或者STOP，且线程池为空时，尝试转换runState为TERMINATED
 */
final void tryTerminate() {
    for (;;) {
        // 获取ctl
        int c = ctl.get();
        /**
         * 判断条件是否满足，如果不满足，直接返回
         * 1. 是RUNNING或SHUTDOWN状态，不满足；
         * 2. 是TIDYING或TERMINATED状态，不满足；
         * 3. 是SHUTDOWN状态，但workQueue不为空，不满足
         */
        if (isRunning(c) ||
                runStateAtLeast(c, TIDYING) ||
                (runStateOf(c) == SHUTDOWN && ! workQueue.isEmpty()))
            return;
        // 如果worker数量不为0
        if (workerCountOf(c) != 0) { // Eligible to terminate
            /**
             * 尝试中断worker中的线程，
             * ONLY_ONE表示只尝试中断第一个worker中的线程
             */
            interruptIdleWorkers(ONLY_ONE);
            return;
        }

        // 获取锁
        final ReentrantLock mainLock = this.mainLock;
        mainLock.lock();
        try {
            // 先修改runState为TIDYING，workerCount为0
            if (ctl.compareAndSet(c, ctlOf(TIDYING, 0))) {
                try {
                    // 修改成功后，尝试调用终止钩子方法
                    terminated();
                } finally {
                    // 最终将runState修改为TERMINATED，workerCount修改为0
                    ctl.set(ctlOf(TERMINATED, 0));
                    // 唤醒等待在termination上的所有线程
                    termination.signalAll();
                }
                return;
            }
        } finally {
            // 解锁
            mainLock.unlock();
        }
        // else retry on failed CAS
    }
}

public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException {
    // 转换超时时间
    long nanos = unit.toNanos(timeout);
    // 获取锁
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();
    try {
        for (;;) {
            // 尝试将runState转换为TERMINATED状态
            if (runStateAtLeast(ctl.get(), TERMINATED))
                // 成功就返回true
                return true;
            // 否则判断是否超时，如果超时就返回false
            if (nanos <= 0)
                return false;
            // 计算超时时间
            nanos = termination.awaitNanos(nanos);
        }
    } finally {
        // 解锁
        mainLock.unlock();
    }
}

/**
 * Interrupts all threads, even if active. Ignores SecurityExceptions
 * (in which case some threads may remain uninterrupted).
 *
 * 中断所有worker中的线程
 */
private void interruptWorkers() {
    // 获取锁
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();
    try {
        // 遍历Worker
        for (Worker w : workers) {
            try {
                // 中断Worker中的线程
                w.thread.interrupt();
            } catch (SecurityException ignore) {
            }
        }
    } finally {
        // 解锁
        mainLock.unlock();
    }
}

/**
 * Interrupts threads that might be waiting for tasks (as
 * indicated by not being locked) so they can check for
 * termination or configuration changes. Ignores
 * SecurityExceptions (in which case some threads may remain
 * uninterrupted).
 *
 * 中断空闲的Worker中的线程
 *
 * @param onlyOne If true, interrupt at most one worker. This is
 * called only from tryTerminate when termination is otherwise
 * enabled but there are still other workers.  In this case, at
 * most one waiting worker is interrupted to propagate shutdown
 * signals in case all threads are currently waiting.
 * Interrupting any arbitrary thread ensures that newly arriving
 * workers since shutdown began will also eventually exit.
 * To guarantee eventual termination, it suffices to always
 * interrupt only one idle worker, but shutdown() interrupts all
 * idle workers so that redundant workers exit promptly, not
 * waiting for a straggler task to finish.
 */
private void interruptIdleWorkers(boolean onlyOne) {
    // 获取锁
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();
    try {
        // 遍历Worker
        for (Worker w : workers) {
            // 获取worker中的线程
            Thread t = w.thread;
            // 如果t没有中断，尝试获取worker的锁
            if (!t.isInterrupted() && w.tryLock()) {
                try {
                    // 尝试中断t
                    t.interrupt();
                } catch (SecurityException ignore) {
                } finally {
                    // 解锁Worker
                    w.unlock();
                }
            }
            /**
             * 如果onlyOne，则直接break
             * 即这个参数表示只尝试中断第一个worker中的线程
             */
            if (onlyOne)
                break;
        }
    } finally {
        mainLock.unlock();
    }
}

/**
 * Common form of interruptIdleWorkers, to avoid having to
 * remember what the boolean argument means.
 * 重载方法，传入的onlyOne参数为false
 * 即将对所有的空闲Worker中的线程进行中断尝试
 */
private void interruptIdleWorkers() {
    interruptIdleWorkers(false);
}

/**
 * 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.
 *
 * 发起线程池的有序关闭，会对所有空闲Worker进行中断
 * 但已经运行的任务还会继续运行
 *
 * @throws SecurityException {@inheritDoc}
 */
public void shutdown() {
    // 加锁
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();
    try {
        // 检查可否关闭的权限
        checkShutdownAccess();
        // 将runState转换为SHUTDOWN
        advanceRunState(SHUTDOWN);
        // 中断空闲的Worker
        interruptIdleWorkers();
        // 调用onShutdown()钩子方法
        onShutdown(); // hook for ScheduledThreadPoolExecutor
    } finally {
        // 解锁
        mainLock.unlock();
    }
    // 尝试终止线程池
    tryTerminate();
}

/**
 * Attempts to stop all actively executing tasks, halts the
 * processing of waiting tasks, and returns a list of the tasks
 * that were awaiting execution. These tasks are drained (removed)
 * from the task queue upon return from this method.
 *
 * <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.  This implementation
 * cancels tasks via {@link Thread#interrupt}, so any task that
 * fails to respond to interrupts may never terminate.
 *
 * 发起线程池的有序关闭，会对所有的Worker进行中断
 * 已经运行的任务
 *
 * @throws SecurityException {@inheritDoc}
 */
public List<Runnable> shutdownNow() {
    List<Runnable> tasks;
    // 加锁
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();
    try {
        // 检查可否关闭的权限
        checkShutdownAccess();
        // 将runState转换为SHUTDOWN
        advanceRunState(STOP);
        // 中断所有的Worker
        interruptWorkers();
        // 将队列中的任务全部取出赋值给task
        tasks = drainQueue();
    } finally {
        // 解锁
        mainLock.unlock();
    }
    // 尝试终止线程池
    tryTerminate();
    // 返回保存的任务
    return tasks;
}

/**
 * Performs any further cleanup following run state transition on
 * invocation of shutdown.  A no-op here, but used by
 * ScheduledThreadPoolExecutor to cancel delayed tasks.
 */
void onShutdown() {
}

/**
 * Method invoked prior to executing the given Runnable in the
 * given thread.  This method is invoked by thread {@code t} that
 * will execute task {@code r}, and may be used to re-initialize
 * ThreadLocals, or to perform logging.
 *
 * <p>This implementation does nothing, but may be customized in
 * subclasses. Note: To properly nest multiple overridings, subclasses
 * should generally invoke {@code super.beforeExecute} at the end of
 * this method.
 *
 * 执行前钩子函数
 *
 * @param t the thread that will run task {@code r}
 * @param r the task that will be executed
 */
protected void beforeExecute(Thread t, Runnable r) { }

/**
 * Method invoked upon completion of execution of the given Runnable.
 * This method is invoked by the thread that executed the task. If
 * non-null, the Throwable is the uncaught {@code RuntimeException}
 * or {@code Error} that caused execution to terminate abruptly.
 *
 * <p>This implementation does nothing, but may be customized in
 * subclasses. Note: To properly nest multiple overridings, subclasses
 * should generally invoke {@code super.afterExecute} at the
 * beginning of this method.
 *
 * <p><b>Note:</b> When actions are enclosed in tasks (such as
 * {@link FutureTask}) either explicitly or via methods such as
 * {@code submit}, these task objects catch and maintain
 * computational exceptions, and so they do not cause abrupt
 * termination, and the internal exceptions are <em>not</em>
 * passed to this method. If you would like to trap both kinds of
 * failures in this method, you can further probe for such cases,
 * as in this sample subclass that prints either the direct cause
 * or the underlying exception if a task has been aborted:
 *
 *  <pre> {@code
 * class ExtendedExecutor extends ThreadPoolExecutor {
 *   // ...
 *   protected void afterExecute(Runnable r, Throwable t) {
 *     super.afterExecute(r, t);
 *     if (t == null && r instanceof Future<?>) {
 *       try {
 *         Object result = ((Future<?>) r).get();
 *       } catch (CancellationException ce) {
 *           t = ce;
 *       } catch (ExecutionException ee) {
 *           t = ee.getCause();
 *       } catch (InterruptedException ie) {
 *           Thread.currentThread().interrupt(); // ignore/reset
 *       }
 *     }
 *     if (t != null)
 *       System.out.println(t);
 *   }
 * }}</pre>
 *
 * 执行后钩子函数
 *
 * @param r the runnable that has completed
 * @param t the exception that caused termination, or null if
 * execution completed normally
 */
protected void afterExecute(Runnable r, Throwable t) { }

/**
 * Method invoked when the Executor has terminated.  Default
 * implementation does nothing. Note: To properly nest multiple
 * overridings, subclasses should generally invoke
 * {@code super.terminated} within this method.
 *
 * 线程池已终止的钩子函数
 */
protected void terminated() { }