// CoroutineScope的擴(kuò)展方法
public fun CoroutineScope.launch(
    context: CoroutineContext = EmptyCoroutineContext,
    start: CoroutineStart = CoroutineStart.DEFAULT,
    block: suspend CoroutineScope.() -> Unit
): Job {
    // 根據(jù)當(dāng)前上下文，計(jì)算得到新的上下文
    val newContext = newCoroutineContext(context)
    // 根據(jù)啟動(dòng)模式，創(chuàng)建不同的續(xù)體
    val coroutine = if (start.isLazy)
        LazyStandaloneCoroutine(newContext, block) else
        StandaloneCoroutine(newContext, active = true)
    // 啟動(dòng)協(xié)程
    coroutine.start(start, coroutine, block)
    return coroutine
}

public actual fun CoroutineScope.newCoroutineContext(context: CoroutineContext): CoroutineContext {
    // coroutineContext為CoroutineScope中保存的全局變量
    // 對(duì)上下文進(jìn)行相加
    val combined = coroutineContext + context
    // 用于debug
    val debug = if (DEBUG) combined + CoroutineId(COROUTINE_ID.incrementAndGet()) else combined
    // 如果上下文中沒(méi)有調(diào)度器,則添加一個(gè)默認(rèn)的調(diào)度器
    return if (combined !== Dispatchers.Default && combined[ContinuationInterceptor] == null)
        debug + Dispatchers.Default else debug
}

private open class StandaloneCoroutine(
    parentContext: CoroutineContext,
    active: Boolean
) : AbstractCoroutine<Unit>(parentContext, active) {
    override fun handleJobException(exception: Throwable): Boolean {
        handleCoroutineException(context, exception)
        return true
    }
}

public fun <R> start(start: CoroutineStart, receiver: R, block: suspend R.() -> T) {
    // 該方法用于完成父協(xié)程與子協(xié)程的綁定關(guān)聯(lián)，同時(shí)確保父協(xié)程啟動(dòng)
    initParentJob()
    // 該方法的寫(xiě)法等同于start.invoke(block, receiver, this)
    // 因此調(diào)用的CoroutineStart類(lèi)的方法
    start(block, receiver, this)
}

public enum class CoroutineStart {
    // 四種啟動(dòng)模式
    DEFAULT,
    LAZY,
    // 具有實(shí)驗(yàn)性，慎用
    @ExperimentalCoroutinesApi
    ATOMIC,
    // 具有實(shí)驗(yàn)性，慎用
    @ExperimentalCoroutinesApi
    UNDISPATCHED;
    // 根據(jù)不同的啟動(dòng)策略，啟動(dòng)協(xié)程，執(zhí)行block
    @InternalCoroutinesApi
    public operator fun <T> invoke(block: suspend () -> T, completion: Continuation<T>): Unit =
        when (this) {
            DEFAULT -> block.startCoroutineCancellable(completion)
            ATOMIC -> block.startCoroutine(completion)
            UNDISPATCHED -> block.startCoroutineUndispatched(completion)
            LAZY -> Unit // 該模式不主動(dòng)啟動(dòng)，等待用戶調(diào)用start方法
        }
    // 根據(jù)不同的啟動(dòng)策略，啟動(dòng)協(xié)程，執(zhí)行block
    @InternalCoroutinesApi
    public operator fun <R, T> invoke(block: suspend R.() -> T, receiver: R, completion: Continuation<T>): Unit =
        when (this) {
            DEFAULT -> block.startCoroutineCancellable(receiver, completion)
            ATOMIC -> block.startCoroutine(receiver, completion)
            UNDISPATCHED -> block.startCoroutineUndispatched(receiver, completion)
            LAZY -> Unit
        }
    // 當(dāng)前的啟動(dòng)模式是否為懶啟動(dòng)
    @InternalCoroutinesApi
    public val isLazy: Boolean get() = this === LAZY
}

internal fun <R, T> (suspend (R) -> T).startCoroutineCancellable(receiver: R, completion: Continuation<T>) =
    runSafely(completion) {
        // createCoroutineUnintercepted：創(chuàng)建協(xié)程
        // intercepted：攔截調(diào)度
        // resumeCancellableWith：恢復(fù)執(zhí)行
        createCoroutineUnintercepted(receiver, completion).intercepted().resumeCancellableWith(Result.success(Unit))
    }
// 如果創(chuàng)建的過(guò)程發(fā)生異常，則通知續(xù)體恢復(fù)后續(xù)代碼的執(zhí)行
private inline fun runSafely(completion: Continuation<*>, block: () -> Unit) {
    try {
        block()
    } catch (e: Throwable) {
        completion.resumeWith(Result.failure(e))
    }
}

public expect fun <R, T> (suspend R.() -> T).createCoroutineUnintercepted(
    receiver: R,
    completion: Continuation<T>
): Continuation<Unit>

public actual fun <R, T> (suspend R.() -> T).createCoroutineUnintercepted(
    receiver: R,
    completion: Continuation<T>
): Continuation<Unit> {
    // 用于debug
    val probeCompletion = probeCoroutineCreated(completion)
    return if (this is BaseContinuationImpl)
        create(receiver, probeCompletion)
    else {
        createCoroutineFromSuspendFunction(probeCompletion) {
            (this as Function2<R, Continuation<T>, Any?>).invoke(receiver, it)
        }
    }
}

private inline fun <T> createCoroutineFromSuspendFunction(
    completion: Continuation<T>,
    crossinline block: (Continuation<T>) -> Any?
): Continuation<Unit> {
    val context = completion.context
    // 如果上下文為空
    return if (context === EmptyCoroutineContext)
        // 創(chuàng)建一個(gè)受限協(xié)程
        object : RestrictedContinuationImpl(completion as Continuation<Any?>) {
            private var label = 0

            override fun invokeSuspend(result: Result<Any?>): Any? =
                when (label) {
                    0 -> {
                        label = 1
                        result.getOrThrow()
                        block(this)
                    }
                    1 -> {
                        label = 2
                        result.getOrThrow()
                    }
                    else -> error("This coroutine had already completed")
                }
        }
    else // 不為空，則創(chuàng)建一個(gè)正常的協(xié)程
        object : ContinuationImpl(completion as Continuation<Any?>, context) {
            private var label = 0

            override fun invokeSuspend(result: Result<Any?>): Any? =
                when (label) {
                    0 -> {
                        label = 1
                        result.getOrThrow()
                        block(this)
                    }
                    1 -> {
                        label = 2
                        result.getOrThrow()
                    }
                    else -> error("This coroutine had already completed")
                }
        }
}

public actual fun <T> Continuation<T>.intercepted(): Continuation<T> =
    (this as? ContinuationImpl)?.intercepted() ?: this

internal abstract class ContinuationImpl(
    completion: Continuation<Any?>?,
    private val _context: CoroutineContext?
) : BaseContinuationImpl(completion) {
    constructor(completion: Continuation<Any?>?) : this(completion, completion?.context)
    public override val context: CoroutineContext
        get() = _context!!
    @Transient
    private var intercepted: Continuation<Any?>? = null
    // 如果沒(méi)有緩存，則從上下文中獲取攔截器，調(diào)用interceptContinuation進(jìn)行攔截，
    // 將攔截的續(xù)體保存到全局變量
    public fun intercepted(): Continuation<Any?> =
        intercepted
            ?: (context[ContinuationInterceptor]?.interceptContinuation(this) ?: this)
                .also { intercepted = it }
    protected override fun releaseIntercepted() {
        val intercepted = intercepted
        if (intercepted != null && intercepted !== this) {
            context[ContinuationInterceptor]!!.releaseInterceptedContinuation(intercepted)
        }
        this.intercepted = CompletedContinuation // just in case
    }
}

public abstract class CoroutineDispatcher :
    AbstractCoroutineContextElement(ContinuationInterceptor), ContinuationInterceptor {
     ...
    // 將續(xù)體包裹成DispatchedContinuation，并傳入當(dāng)前調(diào)度器 
    public final override fun <T> interceptContinuation(continuation: Continuation<T>): Continuation<T> =
        DispatchedContinuation(this, continuation)
    ...
}

public fun <T> Continuation<T>.resumeCancellableWith(result: Result<T>): Unit = when (this) {
    is DispatchedContinuation -> resumeCancellableWith(result)
    else -> resumeWith(result)
}

internal class DispatchedContinuation<in T>(
    @JvmField val dispatcher: CoroutineDispatcher,
    @JvmField val continuation: Continuation<T>
) : DispatchedTask<T>(MODE_ATOMIC_DEFAULT), CoroutineStackFrame, Continuation<T> by continuation {
    ...
    @Suppress("NOTHING_TO_INLINE")
    inline fun resumeCancellableWith(result: Result<T>) {
        val state = result.toState()
        // 是否進(jìn)行調(diào)度
        if (dispatcher.isDispatchNeeded(context)) {
            _state = state
            resumeMode = MODE_CANCELLABLE
            // 進(jìn)行調(diào)度
            dispatcher.dispatch(context, this)
        } else {// Dispatcher.Unconfined調(diào)度器會(huì)走這里
            executeUnconfined(state, MODE_CANCELLABLE) {
                // 協(xié)程未被取消
                if (!resumeCancelled()) {
                    // 恢復(fù)執(zhí)行
                    resumeUndispatchedWith(result)
                }
            }
        }
    }
    // 恢復(fù)執(zhí)行前判斷協(xié)程是否已經(jīng)取消執(zhí)行
    @Suppress("NOTHING_TO_INLINE")
    inline fun resumeCancelled(): Boolean {
        // 獲取當(dāng)前的協(xié)程任務(wù)
        val job = context[Job]
        // 如果不為空且不活躍
        if (job != null && !job.isActive) {
            // 拋出異常
            resumeWithException(job.getCancellationException())
            return true
        }
        return false
    }
    @Suppress("NOTHING_TO_INLINE")
    inline fun resumeUndispatchedWith(result: Result<T>) {
        // 該方法在指定的上下文中執(zhí)行，在執(zhí)行后同步協(xié)程上下文變化
        withCoroutineContext(context, countOrElement) {
            // 調(diào)用續(xù)體的resumeWith方法
            continuation.resumeWith(result)
        }
    }
    ...
}
// Dispatchers.Unconfined模式下的調(diào)度
private inline fun DispatchedContinuation<*>.executeUnconfined(
    contState: Any?, mode: Int, doYield: Boolean = false,
    block: () -> Unit
): Boolean {
    // 從ThreadLocal中獲取EventLoop
    val eventLoop = ThreadLocalEventLoop.eventLoop
    // doYield表示是否正在讓出執(zhí)行
    // 如果正在讓出執(zhí)行，并且執(zhí)行隊(duì)列還是空的，說(shuō)明不需要執(zhí)行，返回false
    if (doYield && eventLoop.isUnconfinedQueueEmpty) return false
    // 如果EventLoop當(dāng)前還在被Unconfined調(diào)度器使用
    return if (eventLoop.isUnconfinedLoopActive) {
        _state = contState
        resumeMode = mode
        // 向隊(duì)列中添加當(dāng)前的任務(wù)
        eventLoop.dispatchUnconfined(this)
        // 返回 true
        true
    } else {
        // 重新運(yùn)行EventLoop
        runUnconfinedEventLoop(eventLoop, block = block)
        // 返回false
        false
    }
}

internal inline fun DispatchedTask<*>.runUnconfinedEventLoop(
    eventLoop: EventLoop,
    block: () -> Unit
) {
    // 引用計(jì)數(shù)+1
    eventLoop.incrementUseCount(unconfined = true)
    try {
        // 先執(zhí)行當(dāng)前的任務(wù)
        block()
        // 循環(huán)分發(fā)任務(wù)
        while (true) {
            // 全部執(zhí)行完畢，則退出分發(fā)
            if (!eventLoop.processUnconfinedEvent()) break
        }
    } catch (e: Throwable) {
        handleFatalException(e, null)
    } finally {
        // 引用計(jì)數(shù)+1
        eventLoop.decrementUseCount(unconfined = true)
    }
}

internal abstract class BaseContinuationImpl(
    public val completion: Continuation<Any?>?
) : Continuation<Any?>, CoroutineStackFrame, Serializable {
    public final override fun resumeWith(result: Result<Any?>) {
        var current = this
        var param = result
        // 循環(huán)
        while (true) {
            // 用于debug
            probeCoroutineResumed(current)
            // current環(huán)境下
            with(current) {
                // completion用于續(xù)體執(zhí)行完的回調(diào)，為空，則拋出異常
                // 這里的completion就是一開(kāi)始創(chuàng)建的StandaloneCoroutine對(duì)象
                val completion = completion!! 
                // 獲取執(zhí)行后的結(jié)果
                val outcome: Result<Any?> =
                    try {
                        // 核心執(zhí)行
                        val outcome = invokeSuspend(param)
                        // 如果返回值為COROUTINE_SUSPENDED，說(shuō)明協(xié)程掛起，退出循環(huán)
                        if (outcome === COROUTINE_SUSPENDED) return
                        // 返回結(jié)果成功
                        Result.success(outcome)
                    } catch (exception: Throwable) {
                        // 返回結(jié)果失敗
                        Result.failure(exception)
                    }
                // 釋放攔截的續(xù)體，狀態(tài)機(jī)終止
                releaseIntercepted() 
                // 這里沒(méi)有直接調(diào)用resume，而是通過(guò)循環(huán)代替遞歸
                // 這也是resumeWith方法聲明為final的原因
                if (completion is BaseContinuationImpl) {
                    // 這種情況一般為多個(gè)suspend方法按順序執(zhí)行
                    // 等待下一次循環(huán)
                    current = completion
                    param = outcome
                } else {
                    // 返回結(jié)果
                    completion.resumeWith(outcome)
                    return
                }
            }
        }
    }
    protected abstract fun invokeSuspend(result: Result<Any?>): Any?
    protected open fun releaseIntercepted() {
        // does nothing here, overridden in ContinuationImpl
    }
    public open fun create(completion: Continuation<*>): Continuation<Unit> {
        throw UnsupportedOperationException("create(Continuation) has not been overridden")
    }
    public open fun create(value: Any?, completion: Continuation<*>): Continuation<Unit> {
        throw UnsupportedOperationException("create(Any?;Continuation) has not been overridden")
    }
     ...
}

object : ContinuationImpl(completion as Continuation<Any?>, context) {
    // 初始狀態(tài)
    private var label = 0
    override fun invokeSuspend(result: Result<Any?>): Any? =
            when (label) {
                0 -> {
                    label = 1
                    // 先去獲取一次結(jié)果，如果有異常，則直接拋出，避免執(zhí)行
                    // 比如在調(diào)度器中，如果發(fā)現(xiàn)協(xié)程已經(jīng)取消，
                    // 則調(diào)用resumeWithException方法，在這里直接被拋出
                    result.getOrThrow()
                    // 把當(dāng)前續(xù)體傳入，執(zhí)行協(xié)程
                    // 可能發(fā)生掛起
                    block(this)
                }
                1 -> {
                    // 如果協(xié)程發(fā)生了掛起，那么恢復(fù)掛起后會(huì)走到這里
                    label = 2
                    // 獲取最終的執(zhí)行結(jié)果
                    result.getOrThrow()
                }
                else -> error("This coroutine had already completed")
            }
}

internal enum class CoroutineSingletons { COROUTINE_SUSPENDED, UNDECIDED, RESUMED }