协程原理——CPS变换 ⭐⭐⭐

// Direct Style: 人类最自然的阅读方式
fun loadUser(): User {
    val token = login("admin", "1234")   // 第一步：登录，拿到 token
    val user = fetchUser(token)           // 第二步：用 token 拉取用户信息
    return user                           // 第三步：返回结果
}

// Callback Style: 异步的"真实面貌"
fun loadUser(callback: (User) -> Unit) {
    // 第一步：发起登录，传入回调
    login("admin", "1234") { token ->
        // 第二步：登录成功后，在回调里继续请求用户
        fetchUser(token) { user ->
            // 第三步：拿到用户后，通过最外层回调返回
            callback(user)
        }
    }
}

fun example() {
    val a = computeA()       // ← 执行到这里
    // ---------- 挂起点 ----------
    val b = computeB(a)      // ┐
    val c = computeC(b)      // │ 这三行就是"挂起点之后的 Continuation"
    println(c)               // ┘
}

// ========== Direct Style ==========
// 函数通过 return 返回结果给调用者
fun add(a: Int, b: Int): Int {
    return a + b               // 结果直接 return
}
val result = add(1, 2)         // 调用者通过返回值拿到结果
println(result)                // 继续处理
 
// ========== CPS Style ==========
// 函数不再 return，而是把结果传给 continuation 参数
fun addCPS(a: Int, b: Int, cont: (Int) -> Unit) {
    val sum = a + b            // 计算结果
    cont(sum)                  // 不 return！把结果"传递"给续体
}
addCPS(1, 2) { result ->      // 调用者把"后续逻辑"以 lambda 传入
    println(result)            // 这就是 continuation —— "拿到结果后要做的事"
}

// ========== 你写的 suspend 代码（Direct Style）==========
suspend fun loadUser(): User {
    val token = login("admin", "1234")   // 挂起点 1
    val user = fetchUser(token)           // 挂起点 2
    return user
}
 
// ========== 编译器变换后的"等价"代码（CPS Style 伪码）==========
// 1. 函数签名变了：多了 Continuation 参数，返回值变成 Object
fun loadUser(cont: Continuation<User>): Object {
    // 2. 不再 return User，而是通过 cont.resumeWith(user) 传递结果
    // 3. 如果需要挂起，return COROUTINE_SUSPENDED 这个特殊标记
    
    login("admin", "1234", object : Continuation<String> {
        override fun resumeWith(result: Result<String>) {
            val token = result.getOrThrow()        // 拿到 token
            fetchUser(token, object : Continuation<User> {
                override fun resumeWith(result: Result<User>) {
                    val user = result.getOrThrow()  // 拿到 user
                    cont.resumeWith(Result.success(user)) // 把最终结果交给外层续体
                }
            })
        }
    })
    return COROUTINE_SUSPENDED  // 告诉调用者：我挂起了，别等我
}

// 你眼中的世界（源码）：
// ┌──────────────────────────────┐
// │  suspend fun doWork(): T     │  ← 看起来是普通函数
// │      val a = stepA()         │  ← 看起来同步返回
// │      val b = stepB(a)        │  ← 看起来同步返回
// │      return b                │  ← 正常 return
// │  }                           │
// └──────────────────────────────┘
//
// JVM 眼中的世界（字节码）：
// ┌──────────────────────────────────────────────────────┐
// │  fun doWork(cont: Continuation<T>): Object           │
// │      when (cont.label) {                             │
// │          0 -> { cont.label = 1; return stepA(cont) } │ ← 可能挂起
// │          1 -> { cont.label = 2; return stepB(a,cont)}│ ← 可能挂起
// │          2 -> { cont.resumeWith(b); return b }       │ ← 完成
// │      }                                               │
// │  }                                                   │
// └──────────────────────────────────────────────────────┘

// 你写的 Kotlin 源码
suspend fun fetchUser(userId: String): User {
    // 模拟网络请求
    delay(1000)
    return User(userId, "Zhangsan")
}

// 编译器变换后的等价签名（伪 Java 表示）
// 1. 新增了一个 Continuation 参数（尾部追加）
// 2. 返回值从 User 变成了 Object
public Object fetchUser(String userId, Continuation<? super User> $completion) {
    // ... 内部实现被改造为状态机（后续章节详解）
}

// 源码：无参 suspend 函数
suspend fun doWork(): String
 
// 编译后：只有 Continuation 一个参数
// fun doWork($completion: Continuation<? super String>): Object?
 
 
// 源码：单参数 suspend 函数
suspend fun fetchUser(id: String): User
 
// 编译后：Continuation 追加在最后
// fun fetchUser(id: String, $completion: Continuation<? super User>): Object?
 
 
// 源码：多参数 suspend 函数
suspend fun sendMessage(to: String, content: String): Boolean
 
// 编译后：Continuation 依然在最后
// fun sendMessage(to: String, content: String, $completion: Continuation<? super Boolean>): Object?

// 编译后的函数体内部（伪代码逻辑）
public Object fetchUser(String userId, Continuation<? super User> $completion) {
    // 情况1: 函数真的挂起了 → 返回 COROUTINE_SUSPENDED 哨兵值
    // 情况2: 函数没有挂起（直接完成）→ 返回实际结果 User 对象
}

// Kotlin 标准库源码中的定义
// 它是一个内部的特殊单例对象
@SinceKotlin("1.3")
@InlineOnly
@Suppress("NOTHING_TO_INLINE")
public inline fun <T> suspendCoroutineUninterceptedOrReturn(
    crossinline block: (Continuation<T>) -> Any? // 返回 Any?，即可以是 T 也可以是 COROUTINE_SUSPENDED
): T = TODO() // intrinsic，由编译器处理
 
// COROUTINE_SUSPENDED 的实际定义
internal val COROUTINE_SUSPENDED: Any = CoroutineSingletons.COROUTINE_SUSPENDED

suspend fun getValue(cache: Map<String, User>, key: String): User {
    // 情况1: 缓存命中 → 直接返回，根本不需要挂起
    cache[key]?.let { return it }
    
    // 情况2: 缓存未命中 → 需要发起网络请求，真正挂起
    return fetchFromNetwork(key) // 这是另一个 suspend 函数
}

// 伪代码：展示编译器生成的调用逻辑
// 假设在某个状态机的某个分支里调用 fetchUser
 
val result = fetchUser(userId, continuation) // 调用编译后的函数
 
if (result === COROUTINE_SUSPENDED) {
    // 函数挂起了！
    // 当前协程的执行到此暂停
    // 等 fetchUser 内部异步操作完成后
    // 会通过 continuation.resumeWith() 恢复执行
    return COROUTINE_SUSPENDED // 向上层传播挂起信号
}
 
// 函数没有挂起，同步返回了结果
// 直接将 result 强转为目标类型继续使用
val user = result as User
// ... 继续执行后续逻辑

// ===================== 编译前：你写的源码 =====================
 
suspend fun loginAndFetchUser(name: String, pwd: String): User {
    val token = login(name, pwd)       // 挂起点 1
    val user = fetchUser(token)        // 挂起点 2
    return user
}

// ===================== 编译后：反编译的伪 Java 代码 =====================
 
// 返回值: Object? (可能是 User，也可能是 COROUTINE_SUSPENDED)
// 新增参数: Continuation<? super User> $completion
public Object loginAndFetchUser(
        String name,             // 原始参数 1
        String pwd,              // 原始参数 2
        Continuation<? super User> $completion  // 编译器追加的 Continuation
) {
    // 内部会生成一个继承自 ContinuationImpl 的匿名内部类
    // 这个类就是「状态机」，通过 label 字段跟踪执行进度
    // 具体的状态机实现将在下一节详解...
 
    // 关键点：
    // 1. 如果 login() 挂起 → 返回 COROUTINE_SUSPENDED
    // 2. 如果 login() 没挂起但 fetchUser() 挂起 → 返回 COROUTINE_SUSPENDED
    // 3. 如果两者都没挂起 → 直接返回 User 对象
}

suspend fun calculate(a: Int, b: Int): Double

// 一个包含两个挂起点的 suspend 函数
suspend fun loadAndCombine(input: String): String {
    val token = fetchToken()          // ← 挂起点 1
    val data = fetchData(token)       // ← 挂起点 2
    return "Result: $data"            // ← 最终返回（非挂起）
}

┌─────────────────────────────────────────────────────────┐
│ Block 0 (label == 0)                                    │
│   ● 函数入口                                             │
│   ● 调用 fetchToken() → 可能挂起                         │
├─────────────────────────────────────────────────────────┤
│ Block 1 (label == 1)                                    │
│   ● 拿到 fetchToken 的结果 → 赋值给 token               │
│   ● 调用 fetchData(token) → 可能挂起                    │
├─────────────────────────────────────────────────────────┤
│ Block 2 (label == 2)                                    │
│   ● 拿到 fetchData 的结果 → 赋值给 data                 │
│   ● 拼接字符串并 return                                  │
└─────────────────────────────────────────────────────────┘

// ========== 编译器生成的状态机伪代码 ==========
// 这是 loadAndCombine 编译后的核心逻辑（简化表达）
 
// continuation 对象内部字段：
var label: Int = 0          // 状态标记，初始为 0
var resultToken: Any? = null // 用于跨挂起保存 token 的值
var resultData: Any? = null  // 用于跨挂起保存 data 的值
 
fun invokeSuspend(result: Result<Any?>): Any? {
    when (label) {
 
        0 -> {
            // ===== Block 0：函数入口 =====
            label = 1  // ★ 先把 label 设为 1，为可能的挂起做准备
            val outcome = fetchToken(this)  // 将自身（Continuation）传入
            if (outcome === COROUTINE_SUSPENDED) {
                return COROUTINE_SUSPENDED  // 真的挂起了，退出
            }
            // 如果没挂起，outcome 就是真实结果，直接往下走
            resultToken = outcome
            // ↓↓ fall-through 到 Block 1 ↓↓
        }
 
        1 -> {
            // ===== Block 1：fetchToken 恢复后 =====
            resultToken = result.getOrThrow()  // 从 result 中取出恢复值
            label = 2  // ★ 设置下一个状态
            val outcome = fetchData(resultToken as String, this)
            if (outcome === COROUTINE_SUSPENDED) {
                return COROUTINE_SUSPENDED
            }
            resultData = outcome
            // ↓↓ fall-through 到 Block 2 ↓↓
        }
 
        2 -> {
            // ===== Block 2：fetchData 恢复后 =====
            resultData = result.getOrThrow()
            return "Result: $resultData"  // 最终返回
        }
 
        else -> throw IllegalStateException("call to 'resume' before 'invoke' with coroutine")
    }
}

// ========== 编译器实际生成的 Java 字节码反编译（简化版）==========
 
// 这个内部类就是 loadAndCombine 对应的状态机
final class LoadAndCombineContinuation extends ContinuationImpl {
 
    int label;              // 状态标记
    Object L$0;             // 保存局部变量的槽位（如 token）
    Object result;          // 当前步骤的返回结果
 
    // 状态机的核心方法
    @Nullable
    public final Object invokeSuspend(@NotNull Object $result) {
        // 哨兵值：代表 "已挂起"
        Object COROUTINE_SUSPENDED = IntrinsicsKt.getCOROUTINE_SUSPENDED();
 
        // ====== switch-case 状态分发 ======
        switch (this.label) {
 
            case 0:
                // --- Block 0 ---
                ResultKt.throwOnFailure($result);   // 检查上一步是否有异常
                this.label = 1;                     // 设置下一状态为 1
                Object tokenResult = fetchToken(this); // 调用 suspend 函数
                if (tokenResult == COROUTINE_SUSPENDED) {
                    return COROUTINE_SUSPENDED;     // 真的挂起 → 退出
                }
                // 没挂起 → tokenResult 就是实际值，继续往下
                // ↓↓ fall-through ↓↓
 
            case 1:
                // --- Block 1 ---
                ResultKt.throwOnFailure($result);   // 检查异常
                String token = (String) $result;    // 从恢复结果中取值
                this.L$0 = token;                   // 保存 token 到字段（跨挂起存活）
                this.label = 2;                     // 设置下一状态为 2
                Object dataResult = fetchData(token, this);
                if (dataResult == COROUTINE_SUSPENDED) {
                    return COROUTINE_SUSPENDED;
                }
                // ↓↓ fall-through ↓↓
 
            case 2:
                // --- Block 2 ---
                ResultKt.throwOnFailure($result);   // 检查异常
                String data = (String) $result;     // 取出 data
                return "Result: " + data;           // 返回最终结果
 
            default:
                throw new IllegalStateException("call to 'resume' before 'invoke' with coroutine");
        }
    }
}

// ====== 挂起中的 Continuation 对象内存状态 ======
// LoadAndCombineContinuation {
//     label  = 1          ← 下次恢复时进入 case 1
//     L$0    = null       ← token 还没有值
//     result = null       ← 还没有恢复结果
// }

// ====== 第二次挂起时的内存状态 ======
// LoadAndCombineContinuation {
//     label  = 2          ← 下次恢复进入 case 2
//     L$0    = "abc123"   ← token 已保存
//     result = null
// }

suspend fun example() {
    val a = computeA()          // a 在挂起点之后还要用 → 必须保存
    val b = "hello"             // b 在挂起点之后还要用 → 必须保存
    val temp = a.length         // temp 只在这一段用 → 不需要保存
    val c = suspendFunction()   // ← 挂起点
    println(a)                  // a 在这里被使用
    println(b)                  // b 在这里被使用
    println(c)                  // c 是恢复值，直接从 result 取
}

// ====== Continuation 对象的字段布局 ======
// ExampleContinuation {
//     label: Int = 0
//     L$0: Object = null    // 用于保存变量 a
//     L$1: Object = null    // 用于保存变量 b
//     // 注意：temp 没有对应字段！编译器知道它不需要跨挂起保存
//     // 注意：c 也没有字段！它是恢复时从 $result 直接获取的
// }

suspend fun safeFetch(): String {
    return try {
        val data = fetchData()   // ← 如果这里异常恢复
        "Got: $data"
    } catch (e: Exception) {     // ← 这个 catch 能正常捕获！
        "Error: ${e.message}"
    }
}

suspend fun process(): Int {
    val x = stepA()       // suspend 调用
    val y = stepB(x)      // suspend 调用
    val z = stepC(y)      // suspend 调用
    return x + y + z
}

// 一个包含两个挂起点的 suspend 函数
suspend fun loadUserData(): String {
    val token = getToken()           // ← 挂起点 1：调用 suspend 函数
    val user = getUser(token)        // ← 挂起点 2：调用 suspend 函数
    return "Hello, ${user.name}"     // 普通语句，非挂起点
}

┌─────────────────────────────────────────────────────────────┐
│                  loadUserData() 函数体                       │
├──────────────────┬──────────────────┬───────────────────────┤
│   代码块 0        │   代码块 1        │   代码块 2             │
│                  │                  │                       │
│ (函数入口)        │ (挂起点1恢复后)   │ (挂起点2恢复后)        │
│                  │                  │                       │
│ 调用 getToken()  │ 取回 token 结果   │ 取回 user 结果         │
│ → 可能挂起       │ 调用 getUser()    │ 拼接字符串             │
│                  │ → 可能挂起       │ return 最终结果         │
├──────────────────┼──────────────────┼───────────────────────┤
│    label = 0     │    label = 1     │    label = 2          │
└──────────────────┴──────────────────┴───────────────────────┘

// 编译器生成的 Continuation 子类（伪代码，简化表示）
class LoadUserDataContinuation(
    val completion: Continuation<String>  // 上层调用者的 Continuation
) : ContinuationImpl(completion) {
 
    var label: Int = 0            // 状态标记，初始为 0
    var result: Any? = null       // 存储上一步的返回结果
    var token: String? = null     // 临时变量：跨挂起点保存的局部变量
 
    override fun invokeSuspend(result: Result<Any?>): Any? {
        this.result = result
        // 调用状态机主体（即原函数的变换版本）
        return loadUserData(this)
    }
}

// 编译器对 loadUserData() 的 CPS 变换 + 状态机改写（伪代码）
fun loadUserData(continuation: Continuation<String>): Any? {
 
    // ① 获取或创建 Continuation 对象
    // 首次调用时创建新的 Continuation，后续恢复时复用同一个对象
    val cont = if (continuation is LoadUserDataContinuation) {
        continuation   // 恢复调用：复用已有的 Continuation
    } else {
        LoadUserDataContinuation(continuation)  // 首次调用：包装外部 Continuation
    }
 
    // ② 从 Continuation 中取出上一步结果
    var result = cont.result
 
    // ③ 状态机主体：根据 label 跳转到对应代码块
    when (cont.label) {
 
        0 -> {
            // 【代码块 0】—— 函数入口，执行到第一个挂起点
            cont.label = 1                        // 先将 label 设为下一个状态
            val outcome = getToken(cont)          // 调用 suspend 函数，传入 cont
            if (outcome == COROUTINE_SUSPENDED) { // 如果真的挂起了
                return COROUTINE_SUSPENDED        // 立即返回，让出执行权
            }
            // 如果没有真正挂起（同步返回），则 outcome 就是结果
            result = outcome
            // 注意：这里不 return，而是 fall-through 到下一个代码块
            // 但在实际字节码中，编译器通常用 goto 或循环实现 fall-through
        }
 
        1 -> {
            // 【代码块 1】—— 从挂起点 1 恢复，执行到挂起点 2
            val token = result as String          // 取出 getToken() 的结果
            cont.token = token                    // 保存到 Continuation 字段（跨挂起点）
            cont.label = 2                        // 设置下一个状态
            val outcome = getUser(token, cont)    // 调用 suspend 函数
            if (outcome == COROUTINE_SUSPENDED) {
                return COROUTINE_SUSPENDED
            }
            result = outcome
        }
 
        2 -> {
            // 【代码块 2】—— 从挂起点 2 恢复，执行到函数结束
            val user = result as User             // 取出 getUser() 的结果
            return "Hello, ${user.name}"          // 最终结果，返回给调用者
        }
 
        else -> throw IllegalStateException("Unexpected label: ${cont.label}")
    }
    // 实际编译器生成的代码不会走到这里
}

异步操作完成
  → Dispatcher 调度
    → cont.resumeWith(Result.success(value))
      → ContinuationImpl.resumeWith()
        → invokeSuspend(result)       // 将 result 存入 cont.result
          → loadUserData(cont)        // 再次调用函数本身
            → when(cont.label) {      // 根据 label 跳转
                1 -> { ... }          // 从对应位置继续
              }

// 包含 try-catch 和循环的 suspend 函数
suspend fun fetchWithRetry(url: String): String {
    repeat(3) { attempt ->               // 循环 3 次
        try {
            val result = httpGet(url)    // ← 挂起点：网络请求
            return result                // 成功则直接返回
        } catch (e: Exception) {
            delay(1000L * attempt)       // ← 挂起点：延迟重试
        }
    }
    throw RuntimeException("All retries failed")
}

// fetchWithRetry 编译后的状态机伪代码（简化）
fun fetchWithRetry(url: String, cont: Continuation<String>): Any? {
    val sm = cont as? FetchWithRetryContinuation
        ?: FetchWithRetryContinuation(cont)
 
    when (sm.label) {
        0 -> {
            sm.attempt = 0              // 初始化循环计数器
            sm.label = 1                // 跳到循环体开始
            // fall-through 到 label 1
        }
        1 -> {
            // 循环体入口：调用 httpGet
            if (sm.attempt >= 3) {      // 循环条件检查
                throw RuntimeException("All retries failed")
            }
            sm.label = 2               // 设置下一状态为"处理 httpGet 结果"
            val outcome = httpGet(url, sm)
            if (outcome == COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
            sm.result = outcome
        }
        2 -> {
            // httpGet 返回后
            try {
                return sm.result as String    // 成功，直接返回
            } catch (e: Exception) {
                sm.label = 3                  // 进入 delay 状态
                val outcome = delay(1000L * sm.attempt, sm)
                if (outcome == COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
                sm.result = outcome
            }
        }
        3 -> {
            // delay 返回后，准备下一次循环
            sm.attempt++                // 循环计数器 +1
            sm.label = 1                // 跳回循环体入口
            // fall-through 或 continue loop
        }
    }
    // 实际实现中外层有 while(true) 循环驱动 fall-through
}

// Continuation 对象在内存中的状态变化
 
// ======= 初始状态 (label = 0) =======
LoadUserDataContinuation@0x7f {
    label:      0           // → 即将执行代码块 0
    result:     null        // → 还没有任何结果
    token:      null        // → 局部变量未赋值
    completion: Caller@0x3a // → 指向调用者的 Continuation
}
 
// ======= getToken() 挂起后 (label = 1) =======
LoadUserDataContinuation@0x7f {
    label:      1           // → 恢复后执行代码块 1
    result:     null        // → 等待 getToken 结果填入
    token:      null        // → 还未获得 token
    completion: Caller@0x3a // → 不变
}
 
// ======= getToken() 完成, resumeWith 调用 =======
LoadUserDataContinuation@0x7f {
    label:      1           // → when 匹配到 1
    result:     "abc123"    // → getToken 的结果已填入
    token:      null        // → 即将在代码块 1 中赋值
    completion: Caller@0x3a
}
 
// ======= 代码块 1 执行中 =======
LoadUserDataContinuation@0x7f {
    label:      2           // → 已更新为下一状态
    result:     "abc123"
    token:      "abc123"    // → 已保存，供 getUser 使用
    completion: Caller@0x3a
}
 
// ======= getUser() 完成, 最终返回 =======
LoadUserDataContinuation@0x7f {
    label:      2           // → when 匹配到 2
    result:     User(name="Alice")
    token:      "abc123"
    completion: Caller@0x3a // → 最终结果通过 completion 返回给调用者
}

suspend fun process(): Int {
    val a = stepOne()       // suspend fun
    val b = stepTwo(a)      // suspend fun
    val c = stepThree(b)    // suspend fun
    return a + b + c
}

// kotlin.coroutines.Continuation.kt
// 这是 Kotlin 标准库中定义的接口，泛型 T 代表协程最终产出的结果类型
public interface Continuation<in T> {
 
    // 属性：该 Continuation 关联的协程上下文
    public val context: CoroutineContext
 
    // 方法：用执行结果（成功值或失败异常）恢复协程的执行
    public fun resumeWith(result: Result<T>)
}

// 参数 result 是一个 Result<T>，内部封装了 success value 或 failure exception
public fun resumeWith(result: Result<T>)

// kotlin.Result 的核心结构（简化）
@JvmInline
public value class Result<out T> @PublishedApi internal constructor(
    @PublishedApi internal val value: Any?   // 成功时存 T 类型的值；失败时存 Result.Failure(exception)
) {
    // 判断是否成功
    public val isSuccess: Boolean get() = value !is Failure
 
    // 判断是否失败
    public val isFailure: Boolean get() = value is Failure
 
    // 获取成功值，失败时返回 null
    public fun getOrNull(): T? = ...
 
    // 获取异常，成功时返回 null
    public fun exceptionOrNull(): Throwable? = ...
 
    // 内部类：包装异常
    internal class Failure(val exception: Throwable)
}

// 假设有一个 suspend 函数
suspend fun fetchUser(): User {
    // 这里会挂起
    val data = suspendCoroutine<String> { continuation ->
        // continuation 就是 Continuation<String> 的实例
        // 模拟异步网络请求
        networkClient.get("https://api.example.com/user") { response ->
            // 网络请求完成后，在回调线程中恢复协程
            if (response.isSuccess) {
                // 成功：传入 Result.success(...)
                continuation.resumeWith(Result.success(response.body))
            } else {
                // 失败：传入 Result.failure(...)
                continuation.resumeWith(Result.failure(response.exception))
            }
        }
        // suspendCoroutine lambda 结束后，函数返回 COROUTINE_SUSPENDED
    }
    // 恢复后，data 就是 response.body 的值
    return parseUser(data)
}

// kotlin.coroutines 包下的扩展函数
 
// 以成功值恢复协程
public inline fun <T> Continuation<T>.resume(value: T) {
    // 内部实际调用 resumeWith，传入 Result.success
    return resumeWith(Result.success(value))
}
 
// 以异常恢复协程（协程体内会抛出该异常）
public inline fun <T> Continuation<T>.resumeWithException(exception: Throwable) {
    // 内部实际调用 resumeWith，传入 Result.failure
    return resumeWith(Result.failure(exception))
}

// 对比两种写法
// 写法1：原始 API
continuation.resumeWith(Result.success("Hello"))
continuation.resumeWith(Result.failure(IOException("timeout")))
 
// 写法2：扩展函数（推荐）
continuation.resume("Hello")                          // 更简洁
continuation.resumeWithException(IOException("timeout")) // 语义更明确

// 编译器为 suspend lambda 生成的状态机（简化版）
class FetchUserContinuation(
    completion: Continuation<Any?>         // 外层的 Continuation（父协程）
) : ContinuationImpl(completion) {
 
    var result: Any? = null                // 存储 resumeWith 传入的结果
    var label: Int = 0                     // 状态标记
 
    override fun invokeSuspend(result: Result<Any?>): Any? {
        this.result = result               // 把恢复结果暂存到字段
 
        when (label) {
            0 -> {
                label = 1                  // 设置下一个状态
                // 调用第一个 suspend 函数，传入 this 作为 continuation
                val suspended = fetchData(this)
                if (suspended == COROUTINE_SUSPENDED) {
                    return COROUTINE_SUSPENDED  // 真正挂起，退出状态机
                }
                // 没有挂起（快速路径），直接 fall through
            }
            1 -> {
                // 从挂起中恢复，检查结果是否是异常
                result.getOrThrow()        // 如果 Result 是 failure，这里直接抛异常
                val data = result as String // 取出成功值
                // 继续执行后续逻辑...
                return parseUser(data)     // 最终返回结果
            }
            else -> throw IllegalStateException("call to 'resume' before 'invoke' with coroutine")
        }
    }
}

public interface Continuation<in T> {
    // 每个 Continuation 都绑定一个协程上下文
    public val context: CoroutineContext
    // ...
}

// 通过 Key 获取元素（类似 Map.get）
val dispatcher = context[ContinuationInterceptor]
 
// 用 + 运算符组合多个 Element
val combined = Dispatchers.IO + CoroutineName("my-coroutine") + SupervisorJob()
 
// fold 遍历所有元素
context.fold(initial) { acc, element -> ... }

// ContinuationInterceptor 的核心方法
public interface ContinuationInterceptor : CoroutineContext.Element {
 
    companion object Key : CoroutineContext.Key<ContinuationInterceptor>
 
    // 拦截（包装）原始 continuation，返回一个新的 continuation
    public fun <T> interceptContinuation(continuation: Continuation<T>): Continuation<T>
 
    // 释放被拦截的 continuation（可选）
    public fun releaseInterceptedContinuation(continuation: Continuation<*>) { }
}

// Continuation 的包装链（洋葱模型）
//
// ┌─────────────────────────────────────────────────┐
// │          DispatchedContinuation                  │
// │  ┌─────────────────────────────────────────┐    │
// │  │      原始 ContinuationImpl（状态机）       │    │
// │  │                                         │    │
// │  │  - label: Int                           │    │
// │  │  - invokeSuspend(result)                │    │
// │  │  - context: CoroutineContext            │    │
// │  └─────────────────────────────────────────┘    │
// │                                                 │
// │  + dispatcher: CoroutineDispatcher              │
// │  + resumeWith(): 先 dispatch，再调用内层 resume   │
// └─────────────────────────────────────────────────┘

// 示例：context 的继承与覆盖
val scope = CoroutineScope(Dispatchers.Main + CoroutineName("parent"))
 
scope.launch {
    // 这里的 coroutineContext 继承了 Dispatchers.Main + CoroutineName("parent")
    // 同时自动创建了一个新的子 Job
 
    launch(Dispatchers.IO) {
        // Dispatcher 被覆盖为 IO
        // CoroutineName 仍然继承 "parent"
        // Job 是新的子 Job，parent 指向外层 launch 的 Job
        println(coroutineContext[CoroutineName])  // CoroutineName(parent)
    }
}

// BaseContinuationImpl 中的抽象方法声明
// 参数 result: 上一次挂起点恢复时传回的结果（成功值或异常）
// 返回值: Any? —— 如果遇到新的挂起点则返回 COROUTINE_SUSPENDED，否则返回最终结果
protected abstract fun invokeSuspend(result: Result<Any?>): Any?

// 原始的 suspend 函数
suspend fun fetchAndProcess(): String {
    val data = fetchData()       // 挂起点 1
    val result = process(data)   // 挂起点 2
    return result
}

// 编译器生成的 invokeSuspend 方法（伪代码，简化展示）
override fun invokeSuspend(result: Result<Any?>): Any? {
    // 用于标记"协程已挂起"的哨兵值
    val SUSPENDED = COROUTINE_SUSPENDED
 
    // 根据当前 label 状态进入对应的代码块
    when (this.label) {
 
        0 -> {
            // ===== 状态 0：初始入口 =====
            result.throwOnFailure()          // 如果上一步有异常则抛出
            this.label = 1                   // 将 label 推进到下一个状态
            // 调用第一个 suspend 函数，传入 this 作为 Continuation
            val outcome = fetchData(this)    // this = 当前 Continuation
            if (outcome === SUSPENDED) {
                return SUSPENDED             // 真正挂起了，退出状态机，等待恢复
            }
            // 如果没有真正挂起（直接返回了结果），则 outcome 就是 data
            outcome                          // 继续往下走（fall-through 语义）
        }
 
        1 -> {
            // ===== 状态 1：fetchData 恢复后 =====
            result.throwOnFailure()          // 检查异常
            val data = result.getOrThrow()   // 拿到 fetchData 的返回值
            this.label = 2                   // 推进到状态 2
            val outcome = process(data, this)
            if (outcome === SUSPENDED) {
                return SUSPENDED             // 再次挂起
            }
            outcome
        }
 
        2 -> {
            // ===== 状态 2：process 恢复后 =====
            result.throwOnFailure()
            val finalResult = result.getOrThrow() as String
            return finalResult               // 返回最终结果，协程结束
        }
 
        else -> throw IllegalStateException("Unexpected label: ${this.label}")
    }
}

// BaseContinuationImpl 中 resumeWith 的实现（简化版）
public final override fun resumeWith(result: Result<Any?>) {
    // current 指向当前正在执行的 Continuation（状态机）
    var current = this
    // param 是要传递给 invokeSuspend 的结果
    var param = result
 
    // ★ 关键：这是一个循环！不是简单的单次调用
    while (true) {
        with(current) {
            // 拿到"完成后该通知谁"——即调用者的 Continuation
            val completion = completion!!  // 每个 Continuation 都持有其父级引用
 
            val outcome: Result<Any?> = try {
                // ★ 调用状态机主体
                val result = invokeSuspend(param)
 
                // 如果返回了 COROUTINE_SUSPENDED，说明又挂起了
                // 直接 return，退出整个 resumeWith，等待下次恢复
                if (result === COROUTINE_SUSPENDED) return
 
                // 没有挂起，说明协程（或这一层）执行完毕，包装为成功结果
                Result.success(result)
            } catch (e: Throwable) {
                // 如果 invokeSuspend 抛出了异常，包装为失败结果
                Result.failure(e)
            }
 
            // ★ 释放拦截器（避免内存泄漏）
            releaseIntercepted()
 
            // ★ 检查 completion 是否也是 BaseContinuationImpl
            if (completion is BaseContinuationImpl) {
                // 如果是，说明调用链上还有状态机要继续执行
                // 不递归调用 completion.resumeWith()
                // 而是把 current 指向 completion，继续循环
                // 这就是 ★★★ 尾调用优化（避免栈溢出）★★★
                current = completion
                param = outcome
            } else {
                // 如果不是 BaseContinuationImpl（比如是最外层的回调）
                // 则直接调用其 resumeWith，结束循环
                completion.resumeWith(outcome)
                return
            }
        }
    }
}

// 协程 A 调用 suspend 函数 B，B 又调用 suspend 函数 C
suspend fun A() {
    B()   // B 完成后恢复 A
}
suspend fun B() {
    C()   // C 完成后恢复 B
}
suspend fun C() {
    delay(1000)  // 真正挂起
}

// Trampoline 模式的栈帧变化（ASCII 示意）
// ❌ 递归方式：栈帧不断累积
// ┌─────────────────────┐
// │ A.resumeWith         │
// │  └─ B.resumeWith     │
// │      └─ C.resumeWith │  ← 栈越来越深
// └─────────────────────┘
 
// ✅ Trampoline 方式：始终单层
// 第1轮循环: current = C → invokeSuspend → C完成 → current = B
// 第2轮循环: current = B → invokeSuspend → B完成 → current = A
// 第3轮循环: current = A → invokeSuspend → A完成 → 调用最外层 completion
// ┌─────────────────────┐
// │ resumeWith (while)   │  ← 始终只有这一层
// └─────────────────────┘

// completion 链（协程调用栈的替代品）
// ┌──────────────┐   completion   ┌──────────────┐   completion   ┌──────────────┐
// │  C 的状态机   │ ────────────→ │  B 的状态机   │ ────────────→ │  A 的状态机   │
// │  (当前执行)   │               │  (等待 C)     │               │  (等待 B)     │
// └──────────────┘               └──────────────┘               └──────────────┘
//                                                                       │
//                                                                  completion
//                                                                       ↓
//                                                               ┌──────────────┐
//                                                               │ 最外层回调    │
//                                                               │ (Job/Deferred)│
//                                                               └──────────────┘

public final override fun resumeWith(result: Result<Any?>) {
    var current = this
    var param = result
    while (true) {
        with(current) {
            val completion = completion!!
            val outcome = try {
                val r = invokeSuspend(param)
                if (r === COROUTINE_SUSPENDED) return
                Result.success(r)
            } catch (e: Throwable) {
                Result.failure(e)
            }
            releaseIntercepted()
            if (completion is BaseContinuationImpl) {
                current = completion
                param = outcome
            } else {
                completion.resumeWith(outcome)
                return
            }
        }
    }
}

// 编译器为 suspend fun loadData() 生成的状态机（简化版）
fun invokeSuspend(result: Result<Any?>): Any? {
    val cont = this               // this 就是 Continuation 子类实例
    when (cont.label) {
        0 -> {
            cont.label = 1        // 推进到下一个状态
            val r = fetchFromNetwork(cont)  // 挂起点1
            if (r == COROUTINE_SUSPENDED) return r
            r                     // 未挂起则继续
        }
        1 -> {
            val networkResult = result.getOrThrow()
            cont.label = 2        // 推进到下一个状态
            val r = saveToDB(networkResult, cont)  // 挂起点2
            if (r == COROUTINE_SUSPENDED) return r
            r
        }
        2 -> {
            val dbResult = result.getOrThrow()
            return dbResult       // 最终返回
        }
        else -> throw IllegalStateException()
    }
}