/**
 * 主池控制状态ctl是包含两个概念字段的原子整数: workerCount：指有效的线程数量；
 * runState：指运行状态，运行，关闭等。为了将workerCount和runState用1个int来表示，
 * 我们限制workerCount范围为(2 ^ 29) - 1，即用int的低29位用来表示workerCount，
 * 用int的高3位用来表示runState，这样workerCount和runState刚好用int可以完整表示。
 */
// 初始化时有效的线程数为0, 此时ctl为: 1010 0000 0000 0000 0000 0000 0000 0000 
private final AtomicInteger ctl = new AtomicInteger(ctlOf(RUNNING, 0)); 
// 高3位用来表示运行状态，此值用于运行状态向左移动的位数，即29位
private static final int COUNT_BITS = Integer.SIZE - 3;     
// 线程数容量，低29位表示有效的线程数, 0001 1111 1111 1111 1111 1111 1111 1111
private static final int CAPACITY   = (1 << COUNT_BITS) - 1;
/**
 * 大小关系：RUNNING < SHUTDOWN < STOP < TIDYING < TERMINATED，
 * 源码中频繁使用大小关系来作为条件判断。
 * 1110 0000 0000 0000 0000 0000 0000 0000 运行
 * 0000 0000 0000 0000 0000 0000 0000 0000 关闭
 * 0010 0000 0000 0000 0000 0000 0000 0000 停止
 * 0100 0000 0000 0000 0000 0000 0000 0000 整理
 * 0110 0000 0000 0000 0000 0000 0000 0000 终止
 */
private static final int RUNNING    = -1 << COUNT_BITS; // 运行
private static final int SHUTDOWN   =  0 << COUNT_BITS; // 关闭
private static final int STOP       =  1 << COUNT_BITS; // 停止
private static final int TIDYING    =  2 << COUNT_BITS; // 整理
private static final int TERMINATED =  3 << COUNT_BITS; // 终止
/**
 * 得到运行状态:入参c为ctl的值，~CAPACITY高3位为1低29位全为0, 
 * 因此运算结果为ctl的高3位, 也就是运行状态
 */
private static int runStateOf(int c)     { return c & ~CAPACITY; }  
/**
 * 得到有效的线程数:入参c为ctl的值, CAPACITY高3为为0, 
 * 低29位全为1, 因此运算结果为ctl的低29位, 也就是有效的线程数
 */
private static int workerCountOf(int c)  { return c & CAPACITY; }   
/**
 * 得到ctl的值：高3位的运行状态和低29位的有效线程数进行或运算, 
 * 组合成一个完成的32位数
 */
private static int ctlOf(int rs, int wc) { return rs | wc; }    
// 状态c是否小于s
private static boolean runStateLessThan(int c, int s) { 
    return c < s;
}
// 状态c是否大于等于s
private static boolean runStateAtLeast(int c, int s) {
    return c >= s;
}
// 状态c是否为RUNNING（小于SHUTDOWN的状态只有RUNNING）
private static boolean isRunning(int c) {
    return c < SHUTDOWN;
}
// 使用CAS增加一个有效的线程
private boolean compareAndIncrementWorkerCount(int expect) {    
    return ctl.compareAndSet(expect, expect + 1);
}
// 使用CAS减少一个有效的线程
private boolean compareAndDecrementWorkerCount(int expect) {    
    return ctl.compareAndSet(expect, expect - 1);
}
// 减少一个有效的线程
private void decrementWorkerCount() {
    do {} while (! compareAndDecrementWorkerCount(ctl.get()));
}
// 工作队列
private final BlockingQueue<Runnable> workQueue;    
// 锁
private final ReentrantLock mainLock = new ReentrantLock(); 
// 包含线程池中的所有工作线程,只有在mainLock的情况下才能访问,Worker集合
private final HashSet<Worker> workers = new HashSet<Worker>();
private final Condition termination = mainLock.newCondition();
// 跟踪线程池的最大到达大小，仅在mainLock下访问
private int largestPoolSize;
// 总的完成的任务数
private long completedTaskCount;
// 线程工厂，用于创建线程
private volatile ThreadFactory threadFactory;
// 拒绝策略
private volatile RejectedExecutionHandler handler;
/**
 * 线程超时时间，当线程数超过corePoolSize时生效, 
 * 如果有线程空闲时间超过keepAliveTime, 则会被终止
 */
private volatile long keepAliveTime;    
// 是否允许核心线程超时，默认false，false情况下核心线程会一直存活。
private volatile boolean allowCoreThreadTimeOut;
// 核心线程数
private volatile int corePoolSize;
// 最大线程数
private volatile int maximumPoolSize;
// 默认饱和策略（拒绝策略）, 抛异常
private static final RejectedExecutionHandler defaultHandler = 
    new AbortPolicy();
private static final RuntimePermission shutdownPerm =
    new RuntimePermission("modifyThread");
/**
 * Worker类，每个Worker包含一个线程、一个初始任务、一个任务计算器
 */
private final class Worker   
    extends AbstractQueuedSynchronizer
    implements Runnable
{
    private static final long serialVersionUID = 6138294804551838833L;
    final Thread thread;    // Worker对应的线程
    Runnable firstTask; // 运行的初始任务。
    volatile long completedTasks;   // 每个线程的任务计数器
    Worker(Runnable firstTask) {
        setState(-1); // 禁止中断，直到runWorker
        this.firstTask = firstTask; // 设置为初始任务
        // 使用当前线程池的线程工厂创建一个线程
        this.thread = getThreadFactory().newThread(this);  
    }
    // 将主运行循环委托给外部runWorker
    public void run() {
        runWorker(this);
    }
    // Lock methods
    //
    // The value 0 represents the unlocked state.
    // The value 1 represents the locked state.
    /**
     * 通过AQS的同步状态来实现锁机制。state为0时代表锁未被获取（解锁状态），
     * state为1时代表锁已经被获取（加锁状态）。
     */
    protected boolean isHeldExclusively() { // 
        return getState() != 0; 
    }
    protected boolean tryAcquire(int unused) {  // 尝试获取锁
        if (compareAndSetState(0, 1)) { // 使用CAS尝试将state设置为1，即尝试获取锁
            // 成功将state设置为1，则当前线程拥有独占访问权
            setExclusiveOwnerThread(Thread.currentThread());    
            return true;
        }
        return false;
    }
    protected boolean tryRelease(int unused) {  // 尝试释放锁
        setExclusiveOwnerThread(null);  // 释放独占访问权：即将独占访问线程设为null
        setState(0);    // 解锁：将state设置为0
        return true;
    }
    public void lock()        { acquire(1); }   // 加锁
    public boolean tryLock()  { return tryAcquire(1); } // 尝试加锁
    public void unlock()      { release(1); }   // 解锁
    public boolean isLocked() { return isHeldExclusively(); }  // 是否为加锁状态 
    void interruptIfStarted() { // 如果线程启动了，则进行中断
        Thread t;
        if (getState() >= 0 && (t = thread) != null && !t.isInterrupted()) {
            try {
                t.interrupt();
            } catch (SecurityException ignore) {
            }
        }
    }
}

/**
 * Rolls back the worker thread creation.
 * - removes worker from workers, if present
 * - decrements worker count
 * - rechecks for termination, in case the existence of this
 *   worker was holding up termination
 */
private void addWorkerFailed(Worker w) {    // 回滚Worker的添加，就是将Worker移除
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();
    try {
        if (w != null)
            workers.remove(w);  // 移除Worker
        decrementWorkerCount(); // 有效线程数-1
        tryTerminate(); // 有worker线程移除，可能是最后一个线程退出需要尝试终止线程池
    } finally {
        mainLock.unlock();
    }
}

private Runnable getTask() {    // Worker从工作队列获取任务
    boolean timedOut = false; // poll方法取任务是否超时
    for (;;) {  // 无线循环
        int c = ctl.get();  // ctl
        int rs = runStateOf(c); // 当前运行状态
        // 如果线程池运行状态为停止，或者可以停止（状态为SHUTDOWN并且队列为空）
        // 则返回null，代表当前Worker需要移除
        if (rs >= SHUTDOWN && (rs >= STOP || workQueue.isEmpty())) {    
            decrementWorkerCount(); // 将workerCount - 1
            // 返回null前将workerCount - 1,
            // 因此processWorkerExit中completedAbruptly＝false时无需再减
            return null;
        }
        int wc = workerCountOf(c);  // 当前的workerCount
        // 判断当前Worker是否可以被移除, 即当前Worker是否可以一直等待任务。
        // 如果allowCoreThreadTimeOut为true，或者workerCount大于核心线程数，
        // 则当前线程是有超时时间的（keepAliveTime），无法一直等待任务。
        boolean timed = allowCoreThreadTimeOut || wc > corePoolSize;    
        // 如果wc超过最大线程数 或者 当前线程会超时并且已经超时，
        // 并且wc > 1 或者 工作队列为空，则返回null，代表当前Worker需要移除
        if ((wc > maximumPoolSize || (timed && timedOut))
            && (wc > 1 || workQueue.isEmpty())) {   // 确保有Worker可以移除 
            if (compareAndDecrementWorkerCount(c))
                // 返回null前将workerCount - 1，
                // 因此processWorkerExit中completedAbruptly＝false时无需再减
                return null;    
            continue;
        }
        try {
            // 根据线程是否会超时调用相应的方法，poll为带超时的获取任务方法
            // take()为不带超时的获取任务方法，会一直阻塞直到获取到任务
            Runnable r = timed ? 
                workQueue.poll(keepAliveTime, TimeUnit.NANOSECONDS) :
                workQueue.take();
            if (r != null)
                return r;
            timedOut = true;    // 走到这代表当前线程获取任务超时
        } catch (InterruptedException retry) {
            timedOut = false;   // 被中断
        }
    }
}

private void processWorkerExit(Worker w, boolean completedAbruptly) {   // Worker的退出
    // 如果Worker是异常死亡（completedAbruptly=true），则workerCount-1；
    // 如果completedAbruptly为false的时候（正常超时退出），则代表task=getTask()等于null，
    // getTask()方法中返回null的地方，都已经将workerCount - 1，所以此处无需再-1
    if (completedAbruptly) 
        decrementWorkerCount();
    final ReentrantLock mainLock = this.mainLock;
    mainLock.lock();    // 加锁
    try {
        completedTaskCount += w.completedTasks; // 该Worker完成的任务数加到总完成的任务数
        workers.remove(w);  // 移除该Worker
    } finally {
        mainLock.unlock();
    }
    tryTerminate(); // 有Worker线程移除，可能是最后一个线程退出，需要尝试终止线程池
    int c = ctl.get();  // 获取当前的ctl
    if (runStateLessThan(c, STOP)) {  // 如果线程池的运行状态还没停止（RUNNING或SHUTDOWN）
        if (!completedAbruptly) {   // 如果Worker不是异常死亡
            // min为线程池的理论最小线程数:如果允许核心线程超时则min为0,否则min为核心线程数
            int min = allowCoreThreadTimeOut ? 0 : corePoolSize;    
            // 如果min为0,工作队列不为空,将min设置为1,确保至少有1个Worker来处理队列里的任务 
            if (min == 0 && ! workQueue.isEmpty())
                min = 1;
            // 当前有效的线程数>=min，直接返回;
            if (workerCountOf(c) >= min)
                return; // replacement not needed 
            // 如果代码走到这边，代表workerCountOf(c) < min，此时会走到下面的addWorker方法。
            // 通过getTask方法我们知道，当allowCoreThreadTimeOut为false
            // 并且workerCount<=corePoolSize时，是不会走到processWorkerExit方法的。
            // 因此走到这边只可能是当前移除的Worker是最后一个Worker，但是此时工作
            // 队列还不为空，因此min被设置成了1，所以需要在添加一个Worker来处理工作队列。
        }
        addWorker(null, false); // 添加一个Worker
    }
}

final void tryTerminate() { // 尝试终止线程池
    for (;;) {
        int c = ctl.get();
        // 只有当前状态为STOP 或者 SHUTDOWN并且队列为空，才会尝试整理并终止
        // 1: 当前状态为RUNNING，则不尝试终止，直接返回
        // 2: 当前状态为TIDYING或TERMINATED，代表有其他线程正在执行终止，直接返回
        // 3: 当前状态为SHUTDOWN 并且 workQueue不为空，则不尝试终止，直接返回
        if (isRunning(c) || // 1
            runStateAtLeast(c, TIDYING) ||  // 2
            (runStateOf(c) == SHUTDOWN && ! workQueue.isEmpty()))   // 3
            return;
        // 走到这代表线程池可以终止（通过上面的校验）
        // 如果此时有效线程数不为0， 将中断一个空闲的Worker，以确保关闭信号传播
        if (workerCountOf(c) != 0) { // Eligible to terminate 
            interruptIdleWorkers(ONLY_ONE);
            return;
        }
        final ReentrantLock mainLock = this.mainLock;
        mainLock.lock();    // 加锁，终止线程池
        try {
            // 使用CAS将ctl的运行状态设置为TIDYING，有效线程数设置为0
            if (ctl.compareAndSet(c, ctlOf(TIDYING, 0))) {  
                try {
                    terminated();   // 供用户重写的terminated方法，默认为空
                } finally {
                    // 将ctl的运行状态设置为TERMINATED，有效线程数设置为0
                    ctl.set(ctlOf(TERMINATED, 0));  
                    termination.signalAll();
                }
                return;
            }
        } finally {
            mainLock.unlock();
        }
        // else retry on failed CAS
    }
}