// 關(guān)閉，不會接受新的任務(wù)，也不會等待未完成的任務(wù)
// 如果需要等待未完成的任務(wù)，可以使用 awaitTermination 方法
void shutdown();
// executor 是否已經(jīng)關(guān)閉了，返回值 true 表示已關(guān)閉
boolean isShutdown();
// 所有的任務(wù)是否都已經(jīng)終止，是的話，返回 true
boolean isTerminated();
// 在超時時間內(nèi)，等待剩余的任務(wù)終止
boolean awaitTermination(long timeout, TimeUnit unit)
    throws InterruptedException;
// 提交有返回值的任務(wù)，使用 get 方法可以阻塞等待任務(wù)的執(zhí)行結(jié)果返回
<T> Future<T> submit(Callable<T> task);
// 提交沒有返回值的任務(wù)，如果使用 get 方法的話，任務(wù)執(zhí)行完之后得到的是 null 值
Future<?> submit(Runnable task);
// 給定任務(wù)集合，返回已經(jīng)執(zhí)行完成的 Future 集合，每個返回的 Future 都是 isDone = true 的狀態(tài)
<T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
    throws InterruptedException;
// 給定任務(wù)中有一個執(zhí)行成功就返回，如果拋異常，其余未完成的任務(wù)將被取消
<T> T invokeAny(Collection<? extends Callable<T>> tasks)
    throws InterruptedException, ExecutionException;

// 把 Runnable 轉(zhuǎn)化成 RunnableFuture
// RunnableFuture 是一個接口，實現(xiàn)了 Runnable 和 Future
// FutureTask 是 RunnableFuture 的實現(xiàn)類，主要是對任務(wù)進行各種管理
// Runnable + Future => RunnableFuture => FutureTask
protected <T> RunnableFuture<T> newTaskFor(Runnable runnable, T value) {
    return new FutureTask<T>(runnable, value);
}
protected <T> RunnableFuture<T> newTaskFor(Callable<T> callable) {
    return new FutureTask<T>(callable);
}
// 提交無返回值的任務(wù)
public Future<?> submit(Runnable task) {
    if (task == null) throw new NullPointerException();
    // ftask 其實是 FutureTask
    RunnableFuture<Void> ftask = newTaskFor(task, null);
    execute(ftask);
    return ftask;
}
// 提交有返回值的任務(wù)
public <T> Future<T> submit(Callable<T> task) {
    if (task == null) throw new NullPointerException();
    // ftask 其實是 FutureTask
    RunnableFuture<T> ftask = newTaskFor(task);
    execute(ftask);
    return ftask;
}

//ctl 線程池狀態(tài)控制字段，由兩部分組成：
//1:workerCount  wc 工作線程數(shù)，我們限制 workerCount 最大到(2^29)-1，大概 5 億個線程
//2:runState rs 線程池的狀態(tài)，提供了生命周期的控制，源碼中有很多關(guān)于狀態(tài)的校驗，狀態(tài)枚舉如下：
//RUNNING（-536870912）：接受新任務(wù)或者處理隊列里的任務(wù)。
//SHUTDOWN（0）：不接受新任務(wù)，但仍在處理已經(jīng)在隊列里面的任務(wù)。
//STOP（-536870912）：不接受新任務(wù)，也不處理隊列中的任務(wù)，對正在執(zhí)行的任務(wù)進行中斷。
//TIDYING（1073741824）： 所以任務(wù)都被中斷，workerCount 是 0，整理狀態(tài)
//TERMINATED（1610612736）： terminated() 已經(jīng)完成的時候
//runState 之間的轉(zhuǎn)變過程：
//RUNNING -> SHUTDOWN：調(diào)用 shudown(),finalize()
//(RUNNING or SHUTDOWN) -> STOP：調(diào)用shutdownNow()
//SHUTDOWN -> TIDYING -> workerCount ==0
//STOP -> TIDYING -> workerCount ==0
//TIDYING -> TERMINATED -> terminated() 執(zhí)行完成之后
private final AtomicInteger ctl = new AtomicInteger(ctlOf(RUNNING, 0));
private static final int COUNT_BITS = Integer.SIZE - 3;// 29
private static final int CAPACITY   = (1 << COUNT_BITS) - 1;// =(2^29)-1=536870911
// Packing and unpacking ctl
private static int ctlOf(int rs, int wc) { return rs | wc; }
private static int workerCountOf(int c)  { return c & CAPACITY; }
private static int runStateOf(int c)     { return c & ~CAPACITY; }
// runState is stored in the high-order bits
private static final int RUNNING    = -1 << COUNT_BITS;//-536870912
private static final int SHUTDOWN   =  0 << COUNT_BITS;//0
private static final int STOP       =  1 << COUNT_BITS;//-536870912
private static final int TIDYING    =  2 << COUNT_BITS;//1073741824
private static final int TERMINATED =  3 << COUNT_BITS;//1610612736
// 已完成任務(wù)的計數(shù)
volatile long completedTasks;
// 線程池最大容量
private int largestPoolSize;
// 已經(jīng)完成的任務(wù)數(shù)
private long completedTaskCount;
// 用戶可控制的參數(shù)都是 volatile 修飾的
// 可以使用 threadFactory 創(chuàng)建 thread
// 創(chuàng)建失敗一般不拋出異常，只有在 OutOfMemoryError 時候才會
private volatile ThreadFactory threadFactory;
// 飽和或者運行中拒絕任務(wù)的 handler 處理類
private volatile RejectedExecutionHandler handler;
// 線程存活時間設(shè)置
private volatile long keepAliveTime;
// 設(shè)置 true 的話，核心線程空閑 keepAliveTime 時間后，也會被回收
private volatile boolean allowCoreThreadTimeOut;
// coreSize
private volatile int corePoolSize;
// maxSize 最大限制 (2^29)-1
private volatile int maximumPoolSize;
// 默認的拒絕策略
private static final RejectedExecutionHandler defaultHandler =
    new AbortPolicy();
// 隊列會 hold 住任務(wù)，并且利用隊列的阻塞的特性，來保持線程的存活周期
private final BlockingQueue<Runnable> workQueue;
// 大多數(shù)情況下是控制對 workers 的訪問權(quán)限
private final ReentrantLock mainLock = new ReentrantLock();
private final Condition termination = mainLock.newCondition();
// 包含線程池中所有的工作線程
private final HashSet<Worker> workers = new HashSet<Worker>();

// 線程池中任務(wù)執(zhí)行的最小單元
// Worker 繼承 AQS，具有鎖功能
// Worker 實現(xiàn) Runnable，本身是一個可執(zhí)行的任務(wù)
private final class Worker
    extends AbstractQueuedSynchronizer
    implements Runnable
{
    // 任務(wù)運行的線程
    final Thread thread;
    // 需要執(zhí)行的任務(wù)
    Runnable firstTask;
    // 非常巧妙的設(shè)計,Worker本身是個 Runnable,把自己作為任務(wù)傳遞給 thread
    // 內(nèi)部有個屬性又設(shè)置了 Runnable
    Worker(Runnable firstTask) {
        setState(-1); // inhibit interrupts until runWorker
        this.firstTask = firstTask;
        // 把 Worker 自己作為 thread 運行的任務(wù)
        this.thread = getThreadFactory().newThread(this);
    }
   /** Worker 本身是 Runnable，run 方法是 Worker 執(zhí)行的入口， runWorker 是外部的方法 */
    public void run() {
        runWorker(this);
    }
    private static final long serialVersionUID = 6138294804551838833L;
    // Lock methods
    // 0 代表沒有鎖住，1 代表鎖住
    protected boolean isHeldExclusively() {
        return getState() != 0;
    }
    // 嘗試加鎖，CAS 賦值為 1，表示鎖住
    protected boolean tryAcquire(int unused) {
        if (compareAndSetState(0, 1)) {
            setExclusiveOwnerThread(Thread.currentThread());
            return true;
        }
        return false;
    }
    // 嘗試釋放鎖，釋放鎖沒有 CAS 校驗，可以任意的釋放鎖
    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(); }
    void interruptIfStarted() {
        Thread t;
        if (getState() >= 0 && (t = thread) != null && !t.isInterrupted()) {
            try {
                t.interrupt();
            } catch (SecurityException ignore) {
            }
        }
    }
}

public void execute(Runnable command) {
    if (command == null)
        throw new NullPointerException();
    int c = ctl.get();
    // 工作的線程小于核心線程數(shù)，創(chuàng)建新的線程，成功返回，失敗不拋異常
    if (workerCountOf(c) < corePoolSize) {
        if (addWorker(command, true))
            return;
        // 線程池狀態(tài)可能發(fā)生變化
        c = ctl.get();
    }
    // 工作的線程大于等于核心線程數(shù)，或者新建線程失敗
    // 線程池狀態(tài)正常，并且可以入隊的話，嘗試入隊列
    if (isRunning(c) && workQueue.offer(command)) {
        int recheck = ctl.get();
        // 如果線程池狀態(tài)異常 嘗試從隊列中移除任務(wù)，可以移除的話就拒絕掉任務(wù)
        if (!isRunning(recheck) && remove(command))
            reject(command);
        // 發(fā)現(xiàn)可運行的線程數(shù)是 0，就初始化一個線程，這里是個極限情況，入隊的時候，突然發(fā)現(xiàn)
        // 可用線程都被回收了
        else if (workerCountOf(recheck) == 0)
            // Runnable是空的，不會影響新增線程，但是線程在 start 的時候不會運行
            // Thread.run() 里面有判斷
            addWorker(null, false);
    }
    // 隊列滿了，開啟線程到 maxSize，如果失敗直接拒絕,
    else if (!addWorker(command, false))
        reject(command);
}

// 結(jié)合線程池的情況看是否可以添加新的 worker
// firstTask 不為空可以直接執(zhí)行，為空執(zhí)行不了，Thread.run()方法有判斷，Runnable為空不執(zhí)行
// core 為 true 表示線程最大新增個數(shù)是 coresize，false 表示最大新增個數(shù)是 maxsize
// 返回 true 代表成功，false 失敗
// break retry 跳到retry處，且不再進入循環(huán)
// continue retry 跳到retry處，且再次進入循環(huán)
private boolean addWorker(Runnable firstTask, boolean core) {
    retry:
    // 先是各種狀態(tài)的校驗
    for (;;) {
        int c = ctl.get();
        int rs = runStateOf(c);
        // Check if queue empty only if necessary.
        // rs >= SHUTDOWN 說明線程池狀態(tài)不正常
        if (rs >= SHUTDOWN &&
            ! (rs == SHUTDOWN &&
               firstTask == null &&
               ! workQueue.isEmpty()))
            return false;
        for (;;) {
            int wc = workerCountOf(c);
            // 工作中的線程數(shù)大于等于容量，或者大于等于 coreSize or maxSize
            if (wc >= CAPACITY ||
                wc >= (core ? corePoolSize : maximumPoolSize))
                return false;
            if (compareAndIncrementWorkerCount(c))
                // break 結(jié)束 retry 的 for 循環(huán)
                break retry;
            c = ctl.get();  // Re-read ctl
            // 線程池狀態(tài)被更改
            if (runStateOf(c) != rs)
                // 跳轉(zhuǎn)到retry位置
                continue retry;
            // else CAS failed due to workerCount change; retry inner loop
        }
    }
    boolean workerStarted = false;
    boolean workerAdded = false;
    Worker w = null;
    try {
        // 巧妙的設(shè)計，Worker 本身是個 Runnable.
        // 在初始化的過程中，會把 worker 丟給 thread 去初始化
        w = new Worker(firstTask);
        final Thread t = w.thread;
        if (t != null) {
            final ReentrantLock mainLock = this.mainLock;
            mainLock.lock();
            try {
                // Recheck while holding lock.
                // Back out on ThreadFactory failure or if
                // shut down before lock acquired.
                int rs = runStateOf(ctl.get());
                if (rs < SHUTDOWN ||
                    (rs == SHUTDOWN && firstTask == null)) {
                    if (t.isAlive()) // precheck that t is startable
                        throw new IllegalThreadStateException();
                    workers.add(w);
                    int s = workers.size();
                    if (s > largestPoolSize)
                        largestPoolSize = s;
                    workerAdded = true;
                }
            } finally {
                mainLock.unlock();
            }
            if (workerAdded) {
                // 啟動線程，實際上去執(zhí)行 Worker.run 方法
                t.start();
                workerStarted = true;
            }
        }
    } finally {
        if (! workerStarted)
            addWorkerFailed(w);
    }
    return workerStarted;
}

public void run() {
    runWorker(this);
}

final void runWorker(Worker w) {
    Thread wt = Thread.currentThread();
    Runnable task = w.firstTask;
    //幫助gc回收
    w.firstTask = null;
    w.unlock(); // allow interrupts
    boolean completedAbruptly = true;
    try {
        // task 為空的情況：
        // 1：任務(wù)入隊列了，極限情況下，發(fā)現(xiàn)沒有運行的線程，于是新增一個線程；
        // 2：線程執(zhí)行完任務(wù)執(zhí)行，再次回到 while 循環(huán)。
        // 如果 task 為空，會使用 getTask 方法阻塞從隊列中拿數(shù)據(jù)，如果拿不到數(shù)據(jù)，會阻塞住
        while (task != null || (task = getTask()) != null) {
            //鎖住 worker
            w.lock();
            // 線程池 stop 中,但是線程沒有到達中斷狀態(tài)，幫助線程中斷
            if ((runStateAtLeast(ctl.get(), STOP) ||
                 (Thread.interrupted() &&
                  runStateAtLeast(ctl.get(), STOP))) &&
                !wt.isInterrupted())
                wt.interrupt();
            try {
                //執(zhí)行 before 鉤子函數(shù)
                beforeExecute(wt, task);
                Throwable thrown = null;
                try {
                    //同步執(zhí)行任務(wù)
                    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 {
                    //執(zhí)行 after 鉤子函數(shù),如果這里拋出異常，會覆蓋 catch 的異常
                    //所以這里異常最好不要拋出來
                    afterExecute(task, thrown);
                }
            } finally {
                //任務(wù)執(zhí)行完成，計算解鎖
                task = null;
                w.completedTasks++;
                w.unlock();
            }
        }
        completedAbruptly = false;
    } finally {
        //做一些拋出異常的善后工作
        processWorkerExit(w, completedAbruptly);
    }
}

/**
 * run 方法可以直接被調(diào)用
 * 也可以由線程池進行調(diào)用
 */
public void run() {
    // 狀態(tài)不是任務(wù)創(chuàng)建，或者當前任務(wù)已經(jīng)有線程在執(zhí)行了
    if (state != NEW ||
        !UNSAFE.compareAndSwapObject(this, runnerOffset,
                                     null, Thread.currentThread()))
        return;
    try {
        Callable<V> c = callable;
        // Callable 不為空，并且已經(jīng)初始化完成
        if (c != null && state == NEW) {
            V result;
            boolean ran;
            try {
                // 調(diào)用執(zhí)行
                result = c.call();
                ran = true;
            } catch (Throwable ex) {
                result = null;
                ran = false;
                setException(ex);
            }
            // 給 outcome 賦值
            if (ran)
                set(result);
        }
    } finally {
        // runner must be non-null until state is settled to
        // prevent concurrent calls to run()
        runner = null;
        // state must be re-read after nulling runner to prevent
        // leaked interrupts
        int s = state;
        if (s >= INTERRUPTING)
            handlePossibleCancellationInterrupt(s);
    }
}

// 從阻塞隊列中拿任務(wù)
private Runnable getTask() {
    boolean timedOut = false; // Did the last poll() time out?
    for (;;) {
        int c = ctl.get();
        int rs = runStateOf(c);
        //線程池關(guān)閉 && 隊列為空，不需要在運行了，直接放回
        if (rs >= SHUTDOWN && (rs >= STOP || workQueue.isEmpty())) {
            decrementWorkerCount();
            return null;
        }
        int wc = workerCountOf(c);
        // Are workers subject to culling?
        // true  運行的線程數(shù)大于 coreSize || 核心線程也可以被滅亡
        boolean timed = allowCoreThreadTimeOut || wc > corePoolSize;
        // 隊列以 LinkedBlockingQueue 為例，timedOut 為 true 的話說明下面 poll 方法執(zhí)行返回的是 null
        // 說明在等待 keepAliveTime 時間后，隊列中仍然沒有數(shù)據(jù)
        // 說明此線程已經(jīng)空閑了 keepAliveTime 了
        // 再加上 wc > 1 || workQueue.isEmpty() 的判斷
        // 所以使用 compareAndDecrementWorkerCount 方法使線程池數(shù)量減少 1
        // 并且直接 return，return 之后，此空閑的線程會自動被回收
        if ((wc > maximumPoolSize || (timed && timedOut))
            && (wc > 1 || workQueue.isEmpty())) {
            if (compareAndDecrementWorkerCount(c))
                return null;
            continue;
        }
        try {
            // 從隊列中阻塞拿 worker
            Runnable r = timed ?
                workQueue.poll(keepAliveTime, TimeUnit.NANOSECONDS) :
                workQueue.take();
            if (r != null)
                return r;
            // 設(shè)置已超時，說明此時隊列沒有數(shù)據(jù)
            timedOut = true;
        } catch (InterruptedException retry) {
            timedOut = false;
        }
    }
}