协程取消与超时 ⭐⭐

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // launch 返回一个 Job 对象，它是协程的句柄（handle）
    val job: Job = launch {
        repeat(1000) { i ->
            println("协程工作中... $i")
            delay(500L) // 每次迭代挂起 500ms
        }
    }
 
    delay(1300L) // 主协程等待 1.3 秒，让子协程打印几轮
    println("主协程：我准备取消子协程了")
 
    job.cancel()  // 向子协程发送取消信号
    job.join()    // 等待子协程真正结束（完成取消流程）
 
    println("主协程：子协程已取消，继续执行")
}

协程工作中... 0
协程工作中... 1
协程工作中... 2
主协程：我准备取消子协程了
主协程：子协程已取消，继续执行

// cancelAndJoin() 等价于先 cancel() 再 join()
// 它确保调用方会挂起，直到被取消的协程完全结束
job.cancelAndJoin()

// 传入自定义取消原因，便于调试和日志追踪
job.cancel(CancellationException("用户离开了页面"))

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch(Dispatchers.Default) {
        var nextPrintTime = System.currentTimeMillis()
        var i = 0
 
        // 这是一个纯计算循环，没有任何挂起点！
        while (i < 5) {
            val currentTime = System.currentTimeMillis()
            if (currentTime >= nextPrintTime) {
                println("计算中... ${i++}")
                nextPrintTime = currentTime + 500L
            }
            // 这里在疯狂计算，没有 delay、yield 等挂起函数
        }
    }
 
    delay(1300L)
    println("主协程：取消子协程")
    job.cancelAndJoin() // 尝试取消
    println("主协程：完成")
}

计算中... 0
计算中... 1
计算中... 2
主协程：取消子协程
计算中... 3
计算中... 4
主协程：完成

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch(Dispatchers.Default) {
        var nextPrintTime = System.currentTimeMillis()
        var i = 0
 
        // ✅ 关键修复：用 isActive 替代固定条件
        while (isActive) {  // 每次循环都检查协程是否仍然活跃
            val currentTime = System.currentTimeMillis()
            if (currentTime >= nextPrintTime) {
                println("计算中... ${i++}")
                nextPrintTime = currentTime + 500L
            }
        }
        // 协程被取消后，循环退出，走到这里
        println("协程优雅退出，共完成 $i 次计算")
    }
 
    delay(1300L)  // 等待 1.3 秒
    println("主协程：取消子协程")
    job.cancelAndJoin()  // 这次能成功取消了！
    println("主协程：完成")
}

计算中... 0
计算中... 1
计算中... 2
主协程：取消子协程
协程优雅退出，共完成 3 次计算
主协程：完成

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch(Dispatchers.Default) {
        var i = 0
        while (true) {
            // ensureActive() 在协程已取消时会直接抛出 CancellationException
            // 而不是像 isActive 那样只返回 false
            ensureActive()
 
            // 模拟计算任务
            i++
            if (i % 100_000_000 == 0) {
                println("已完成 ${i / 100_000_000} 亿次运算")
            }
        }
    }
 
    delay(100L)
    job.cancelAndJoin()
    println("计算已取消")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch(Dispatchers.Default) {
        var sum = 0L
        for (i in 1..1_000_000) {
            sum += i
            if (i % 100_000 == 0) {
                yield()  // 每 10 万次计算让出一次执行权，同时检查取消
                println("累加到 $i，当前和 = $sum")
            }
        }
    }
 
    delay(5L)  // 短暂等待后取消
    job.cancelAndJoin()
    println("计算协程已取消")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            repeat(1000) { i ->
                println("工作中... $i")
                // delay 是挂起函数，在此处会自动检查取消状态
                // 如果协程已被取消，delay 不会等待，而是直接抛出 CancellationException
                delay(500L)
            }
        } catch (e: CancellationException) {
            // 捕获取消异常（通常不推荐捕获它，这里仅为演示）
            println("捕获到取消异常: ${e.message}")
        } finally {
            println("finally: 执行清理工作")
        }
    }
 
    delay(1300L)
    println("取消协程")
    job.cancelAndJoin()
    println("完成")
}

工作中... 0
工作中... 1
工作中... 2
取消协程
捕获到取消异常: StandaloneCoroutine was cancelled
finally: 执行清理工作
完成

import kotlinx.coroutines.*
 
fun main() = runBlocking {
 
    // === 场景1：有挂起函数，自动响应取消 ===
    val job1 = launch {
        repeat(100) { i ->
            println("[Job1] 网络请求 #$i")
            delay(200L) // ← 这里会自动检查取消
        }
    }
 
    // === 场景2：纯计算，用 isActive 手动检查 ===
    val job2 = launch(Dispatchers.Default) {
        var count = 0
        while (isActive) {  // ← 手动检查取消状态
            count++
            // 模拟 CPU 密集型运算（如加密/压缩）
            if (count % 5_000_000 == 0) {
                println("[Job2] 已处理 ${count / 1_000_000}M 条数据")
            }
        }
        println("[Job2] 退出前：共处理了 ${count} 条数据") // 可以做收尾
    }
 
    // === 场景3：纯计算，用 ensureActive() 快速失败 ===
    val job3 = launch(Dispatchers.Default) {
        var result = 0L
        for (i in 1..1_000_000_000) {
            ensureActive()  // ← 取消时直接抛 CancellationException
            result += i
        }
    }
 
    delay(300L) // 让各协程运行一会儿
    println("--- 取消所有协程 ---")
 
    // 同时取消三个协程
    job1.cancelAndJoin()  // job1 在下一个 delay() 处响应取消
    job2.cancelAndJoin()  // job2 在下一次 while(isActive) 判断时退出
    job3.cancelAndJoin()  // job3 在下一次 ensureActive() 处抛异常退出
 
    println("所有协程已取消")
}

fun main() = runBlocking {
    val job = launch {
        var i = 0
        while (i < 5) {
            println("i = $i")
            i++
            delay(100)
        }
        println("循环完成")
    }
    delay(250)
    job.cancelAndJoin()
    println("结束")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // 启动一个子协程
    val job = launch {
        try {
            println("协程开始执行...")
            // repeat 是一个普通的循环辅助函数，执行 1000 次
            repeat(1000) { i ->
                println("正在工作中... 第 $i 次迭代")
                // delay 是挂起函数，也是取消检查点
                delay(200L)
            }
        } catch (e: CancellationException) {
            // 捕获取消异常，观察它的真面目
            println("捕获到异常: ${e::class.simpleName}")  // CancellationException
            println("异常消息: ${e.message}")               // StandaloneCoroutine was cancelled
            // ⚠️ 重要：捕获后必须重新抛出，否则协程无法正常完成取消流程
            throw e
        } finally {
            // 无论正常结束还是取消，finally 块都会执行
            println("finally: 执行清理工作")
        }
    }
 
    // 主协程等待 500ms，让子协程运行一会儿
    delay(500L)
    println("主协程: 准备取消子协程")
 
    // 取消子协程，可以传入自定义的取消原因
    job.cancel(CancellationException("不再需要这个任务了"))
 
    // 等待子协程完全结束（包括 finally 块的执行）
    job.join()
    println("主协程: 子协程已完全结束")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            delay(Long.MAX_VALUE) // 模拟长时间挂起
        } catch (e: CancellationException) {
            println("捕获到取消异常")
            // ❌ 错误做法：吞掉异常，协程将不会正确取消！
            // 如果不重新 throw，协程会认为异常被"处理"了，继续往下执行
        }
        // 如果上面吞掉了异常，这行代码会被执行——这通常不是你期望的行为
        println("这行不应该在取消后执行，但由于异常被吞掉了，它执行了！")
    }
 
    delay(100L)
    job.cancel()  // 发出取消信号
    job.join()    // 等待协程结束
    println("结束")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            delay(Long.MAX_VALUE)
        } catch (e: Exception) {
            // ⚠️ 这里会同时捕获 CancellationException 和其他异常
            println("捕获到: ${e::class.simpleName}")
            // ✅ 正确做法：判断类型，将 CancellationException 重新抛出
            if (e is CancellationException) throw e
            // 处理其他业务异常...
            println("处理业务异常: ${e.message}")
        }
    }
 
    delay(100L)
    job.cancel()
    job.join()
    println("协程已正确取消")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        var nextPrintTime = System.currentTimeMillis()
        var i = 0
        while (i < 1000) {
            // ensureActive() 内部检查 isActive
            // 如果协程已被取消，会自动抛出 CancellationException
            ensureActive()
 
            if (System.currentTimeMillis() >= nextPrintTime) {
                println("工作中... ${i++}")
                nextPrintTime += 200L
            }
        }
    }
 
    delay(500L)
    job.cancel()  // ensureActive() 将在下次调用时抛出 CancellationException
    job.join()
    println("已取消")
}

// ensureActive 的简化等价实现
public fun Job.ensureActive() {
    // 如果协程不再处于 Active 状态
    if (!isActive) {
        // 抛出取消异常，getCancellationException() 会获取取消原因
        throw getCancellationException()
    }
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            delay(Long.MAX_VALUE) // 长时间挂起
        } catch (e: CancellationException) {
            // 打印取消原因——对调试和日志记录非常有用
            println("取消原因: ${e.message}")
            println("内部原因: ${e.cause}")
            throw e // 重新抛出以确保正常取消
        }
    }
 
    delay(100L)
    // 传入自定义原因和内部 cause
    job.cancel(CancellationException(
        message = "用户离开了页面",       // 取消消息
        cause = RuntimeException("页面被销毁") // 可选的内部原因
    ))
    job.join()
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // 使用 supervisorScope 外面包一层，防止 runBlocking 本身崩溃
    // 这里故意用普通 coroutineScope 来演示异常传播
    try {
        coroutineScope {
            // 子协程 A：会抛出普通异常
            val childA = launch {
                delay(200L)
                println("子协程 A: 即将抛出 IOException")
                throw java.io.IOException("网络连接失败") // 普通异常
            }
 
            // 子协程 B：正常工作
            val childB = launch {
                repeat(10) { i ->
                    println("子协程 B: 正常工作中... 第 $i 次")
                    delay(100L)
                }
            }
        }
    } catch (e: Exception) {
        // coroutineScope 会将子协程的异常重新抛出
        println("捕获到异常: ${e::class.simpleName} - ${e.message}")
    }
    println("runBlocking: 继续执行")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // 子协程 A：稍后会被主动取消
    val childA = launch {
        try {
            repeat(10) { i ->
                println("子协程 A: 工作中... 第 $i 次")
                delay(100L) // 挂起点，取消检查点
            }
        } catch (e: CancellationException) {
            println("子协程 A: 被取消了 - ${e.message}")
            throw e // 重新抛出，保持取消语义
        }
    }
 
    // 子协程 B：全程正常运行
    val childB = launch {
        repeat(6) { i ->
            println("子协程 B: 正常工作中... 第 $i 次")
            delay(100L)
        }
        println("子协程 B: ✅ 全部完成！") // 这行会正常执行
    }
 
    // 等 250ms 后只取消子协程 A
    delay(250L)
    println("--- 主协程: 取消子协程 A ---")
    childA.cancel(CancellationException("A 不再需要了"))
 
    // 等待两个子协程都结束
    childA.join()
    childB.join()
    println("主协程（父协程）: ✅ 一切正常，继续运行")
}

// AbstractCoroutine 中的简化逻辑（伪代码）
// 当子协程因为异常而完成时，父协程会调用此方法
internal open fun childCancelled(cause: Throwable): Boolean {
    // 关键判断：如果子协程的异常是 CancellationException
    if (cause is CancellationException) {
        return true  // 返回 true 表示"已处理"，父协程不需要做任何事
    }
    // 其他异常：走异常传播流程，可能导致父协程也被取消
    return cancelImpl(cause)
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // supervisorScope 内部使用 SupervisorJob
    supervisorScope {
        // 子协程 A：抛出普通异常
        val childA = launch(CoroutineExceptionHandler { _, e ->
            // SupervisorJob 下需要自行处理异常
            println("异常处理器: ${e.message}")
        }) {
            delay(100L)
            throw RuntimeException("普通异常")  // 非 CancellationException
        }
 
        // 子协程 B：不受影响（因为 SupervisorJob 隔离了异常传播）
        val childB = launch {
            delay(200L)
            println("子协程 B: ✅ 正常完成") // 即使 A 抛了普通异常，B 也不受影响
        }
    }
}

import kotlinx.coroutines.*
 
// 模拟 Android ViewModel 中的使用场景
class MyViewModel {
    // viewModelScope 会在 ViewModel 销毁时自动取消
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
 
    fun loadDashboard() {
        // 同时发起多个网络请求
        val userJob = scope.launch {
            // 加载用户信息
            val user = fetchUser()         // 挂起函数
            updateUserUI(user)             // 更新 UI
        }
 
        val newsJob = scope.launch {
            // 加载新闻列表
            val news = fetchNews()         // 挂起函数
            updateNewsUI(news)             // 更新 UI
        }
 
        // 假设用户快速切换了 Tab，不再需要新闻数据
        // 只取消新闻加载，用户信息加载不受影响
        newsJob.cancel()  // CancellationException 不传播，userJob 安然无恙
    }
 
    // 模拟挂起函数
    private suspend fun fetchUser(): String { delay(1000); return "User" }
    private suspend fun fetchNews(): String { delay(2000); return "News" }
    private fun updateUserUI(user: String) { println("显示用户: $user") }
    private fun updateNewsUI(news: String) { println("显示新闻: $news") }
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val parent = launch {
        val childA = launch {
            delay(100)
            println("A done")
        }
        val childB = launch {
            delay(50)
            throw CancellationException("B cancelled")
        }
        childA.join()
        childB.join()
        println("Parent done")
    }
    parent.join()
    println("Main done")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            repeat(1000) { i ->
                println("任务执行中: $i ...")  // 打印当前迭代索引
                delay(500L)                     // 每次迭代挂起 500ms，这是一个「取消检查点」
            }
        } finally {
            // ⚠️ 协程被取消后会进入 finally 块
            println("进入 finally，准备清理资源...")
 
            // 🔴 问题来了：这里调用了一个挂起函数
            delay(1000L)  // 模拟耗时的清理操作（如网络请求、数据库写入）
            println("清理完成！")  // ← 这一行永远不会执行！
        }
    }
 
    delay(1300L)       // 主协程等待 1.3 秒
    println("准备取消子协程...")
    job.cancelAndJoin() // 取消并等待子协程结束
    println("主协程结束")
}

任务执行中: 0 ...
任务执行中: 1 ...
任务执行中: 2 ...
准备取消子协程...
进入 finally，准备清理资源...
主协程结束

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            repeat(1000) { i ->
                println("任务执行中: $i ...")  // 打印当前迭代索引
                delay(500L)                     // 挂起点，取消时会抛出 CancellationException
            }
        } finally {
            // ✅ 使用 withContext(NonCancellable) 创建一个「不可取消」的安全区域
            withContext(NonCancellable) {
                println("进入 NonCancellable 块，开始清理...")
 
                delay(1000L)  // 模拟耗时的清理操作——现在可以正常执行了！
                println("清理完成！✅")  // ← 这一行现在会被正常执行
            }
            // 注意：withContext 外面的代码仍然处于「已取消」状态
            println("withContext 之后的代码")  // 这一行也能执行（非挂起，不检查取消）
        }
    }
 
    delay(1300L)            // 让子协程运行 1.3 秒
    println("准备取消子协程...")
    job.cancelAndJoin()     // 取消并等待子协程完全结束（包括 finally 中的清理）
    println("主协程结束")
}

任务执行中: 0 ...
任务执行中: 1 ...
任务执行中: 2 ...
准备取消子协程...
进入 NonCancellable 块，开始清理...
清理完成！✅
withContext 之后的代码
主协程结束

// 伪代码展示 withContext(NonCancellable) 的上下文变化
 
// finally 块入口时的上下文：
// CoroutineContext = [Job(已取消), Dispatchers.Default, ...]
//                      ↑ isActive=false, isCancelled=true
 
withContext(NonCancellable) {
    // withContext 内部的上下文：
    // CoroutineContext = [NonCancellable, Dispatchers.Default, ...]
    //                      ↑ isActive=true, isCancelled=false（永远如此）
 
    delay(1000L)  // delay 检查的是 NonCancellable 的状态 → 未取消 → 正常挂起
}

import kotlinx.coroutines.*
 
// 模拟一个数据库操作类
class DatabaseHelper {
    // 挂起函数：模拟插入数据（耗时操作）
    suspend fun insertRecord(data: String) {
        delay(200L)                           // 模拟 IO 耗时
        println("  📝 数据已写入: $data")
    }
 
    // 挂起函数：模拟提交事务
    suspend fun commitTransaction() {
        delay(100L)                           // 模拟提交耗时
        println("  ✅ 事务已提交")
    }
 
    // 挂起函数：模拟回滚事务
    suspend fun rollbackTransaction() {
        delay(100L)                           // 模拟回滚耗时
        println("  ⚠️ 事务已回滚")
    }
}
 
suspend fun performDatabaseWork(db: DatabaseHelper) {
    try {
        db.insertRecord("用户订单 #1001")     // 第一条插入
        db.insertRecord("库存扣减 #1001")     // 第二条插入
        delay(5000L)                           // 模拟后续长时间操作（可能在此处被取消）
        db.insertRecord("物流单 #1001")        // 如果被取消，这一行不会执行
    } finally {
        // 🛡️ 无论协程是否被取消，都必须保证事务完整性
        withContext(NonCancellable) {
            try {
                db.commitTransaction()         // 尝试提交（这里是挂起函数，需要 NonCancellable 保护）
            } catch (e: Exception) {
                db.rollbackTransaction()       // 提交失败则回滚（同样是挂起函数）
            }
        }
    }
}

import kotlinx.coroutines.*
 
// 模拟 Android ViewModel 中的协程使用
class MyViewModel {
    // 模拟挂起函数：将状态持久化到 DataStore
    private suspend fun saveStateToDataStore(state: String) {
        delay(300L)                                  // 模拟磁盘写入耗时
        println("  💾 状态已保存: $state")
    }
 
    // 当页面关闭时（ViewModel.onCleared），viewModelScope 会被取消
    // 但我们仍然需要保存最后的状态
    suspend fun onPageClosing(currentState: String) {
        // 使用 NonCancellable 确保即使 scope 被取消，状态也能保存
        withContext(NonCancellable) {
            saveStateToDataStore(currentState)        // 在不可取消的上下文中执行保存
            println("  ✅ 页面关闭前状态已安全持久化")
        }
    }
}

import kotlinx.coroutines.*
 
// 模拟 WebSocket 连接
class WebSocketConnection {
    // 挂起函数：发送关闭帧（Close Frame）
    suspend fun sendCloseFrame(code: Int, reason: String) {
        delay(200L)                                       // 模拟网络 IO
        println("  📡 已发送 Close Frame: code=$code, reason=$reason")
    }
 
    // 挂起函数：等待服务端确认
    suspend fun awaitCloseAck() {
        delay(500L)                                       // 模拟等待 ACK
        println("  🤝 收到服务端关闭确认")
    }
 
    // 关闭底层 Socket
    fun closeSocket() {
        println("  🔌 Socket 已关闭")
    }
}
 
suspend fun manageConnection(ws: WebSocketConnection) {
    try {
        // 正常的数据通信...
        delay(10_000L)                                    // 模拟长时间通信
    } finally {
        // 🛡️ 即使协程被取消，也要按协议完成 WebSocket 关闭握手
        withContext(NonCancellable) {
            ws.sendCloseFrame(1000, "Normal closure")     // 必须发送关闭帧
            ws.awaitCloseAck()                            // 必须等待确认
        }
        // 非挂起操作可以直接放在 withContext 外面
        ws.closeSocket()                                  // 关闭底层连接
    }
}

finally {
    withContext(NonCancellable) {
        // ✅ 好：关闭资源、保存状态、发送确认等短暂操作
        saveProgress()       // 保存进度
        closeConnection()    // 关闭连接
        flushLogs()          // 刷写日志
    }
}

finally {
    withContext(NonCancellable) {
        // ❌ 极其错误！不要在里面启动长时间运行的新任务
        while (true) {
            pollServer()     // 无限轮询 → 协程永远不会结束！
            delay(1000L)     // 调用者的 cancelAndJoin() 会永远阻塞
        }
    }
}

// ❌ 错误：不应该用 NonCancellable 包裹你的核心业务逻辑
withContext(NonCancellable) {
    // 如果把所有代码都放在这里，那协程的「可取消」优势就完全丧失了
    performLongRunningTask()    // 你永远无法取消这个任务了！
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            delay(3000L)
        } finally {
            println("A")
            withContext(NonCancellable) {
                println("B")
                delay(500L)
                println("C")
            }
            println("D")
        }
    }
    delay(100L)
    job.cancelAndJoin()
    println("E")
}

// timeMillis: 超时时间，单位毫秒
// block: 在超时时间内需要执行完毕的挂起代码块
// 返回值: block 的最后一行表达式的值（如果在超时前完成）
public suspend fun <T> withTimeout(timeMillis: Long, block: suspend CoroutineScope.() -> T): T

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    try {
        // withTimeout 创建一个 3 秒的时间窗口
        val result = withTimeout(3000L) {
            // 模拟一个需要 5 秒才能完成的耗时任务
            repeat(5) { i ->
                println("正在处理第 ${i + 1} 个任务片段...")  // 打印当前进度
                delay(1000L)  // 每个片段耗时 1 秒（挂起点，可被取消）
            }
            "任务完成"  // block 的返回值（本例中永远到达不了）
        }
        println(result)  // 如果在 3 秒内完成，才会执行到这里
    } catch (e: TimeoutCancellationException) {
        // 超时后会捕获到 TimeoutCancellationException
        println("操作超时！: ${e.message}")
    }
}

fun main() = runBlocking {
    try {
        withTimeout(1000L) {
            // 纯计算，没有挂起点 → 不会响应取消！
            var sum = 0L
            // 这个循环会完整执行完毕，withTimeout 形同虚设
            for (i in 1..1_000_000_000L) {
                sum += i  // 没有挂起点，定时器到期也无法中断
            }
            println("计算结果: $sum")
        }
    } catch (e: TimeoutCancellationException) {
        println("超时了")  // 会在循环结束后才进入这里
    }
}

fun main() = runBlocking {
    try {
        withTimeout(1000L) {
            var sum = 0L
            for (i in 1..1_000_000_000L) {
                sum += i
                // 每 100 万次迭代检查一次，避免性能损耗过大
                if (i % 1_000_000 == 0L) {
                    yield()  // 挂起点：让出执行权，同时检查取消状态
                }
            }
            println("计算结果: $sum")
        }
    } catch (e: TimeoutCancellationException) {
        println("超时了，计算被中断")  // 现在超时能正常触发了
    }
}

fun main() = runBlocking {  // 父协程
    // 场景 A：withTimeout 在当前协程作用域内直接调用
    // TimeoutCancellationException 会被当作当前协程的取消
    // 它不会导致父协程（runBlocking）失败
    withTimeout(1000L) {
        delay(2000L)
    }
    // ↑ 这个异常如果未被 try-catch，会取消 runBlocking
    // 但这是 CancellationException，所以是"正常结束"语义
    
    println("这行不会打印")
}

fun main() = runBlocking {
    try {
        withTimeout(1000L) {
            delay(2000L)  // 会超时
        }
    } catch (e: TimeoutCancellationException) {
        println("捕获超时，程序继续运行")  // ✅ 正确做法
    }
 
    println("后续逻辑正常执行")  // ✅ 会打印
}

import kotlinx.coroutines.*
 
// 模拟一个不稳定的网络请求
suspend fun fetchFromNetwork(): String {
    val responseTime = (500L..3000L).random()  // 随机响应时间：500ms ~ 3000ms
    delay(responseTime)                         // 模拟网络延迟
    return "服务器数据 (耗时 ${responseTime}ms)"  // 返回结果
}
 
// 带超时 + 重试的请求封装
suspend fun fetchWithRetry(
    maxRetries: Int = 3,          // 最大重试次数
    timeoutMs: Long = 1500L       // 每次请求的超时时间
): String {
    repeat(maxRetries) { attempt ->
        try {
            // 每次尝试都有独立的超时窗口
            return withTimeout(timeoutMs) {
                println("第 ${attempt + 1} 次尝试...")
                fetchFromNetwork()  // 执行实际请求
            }
        } catch (e: TimeoutCancellationException) {
            // 超时了，打印日志后进入下一次重试
            println("第 ${attempt + 1} 次尝试超时")
            if (attempt == maxRetries - 1) {
                throw Exception("全部 $maxRetries 次尝试均超时")  // 全部重试耗尽
            }
        }
    }
    throw IllegalStateException("不可达代码")  // 编译器要求的返回保障
}
 
fun main() = runBlocking {
    try {
        val data = fetchWithRetry()  // 调用带重试的请求
        println("成功获取: $data")
    } catch (e: Exception) {
        println("最终失败: ${e.message}")
    }
}

// 唯一的区别：返回值是 T?（可空类型）
// 超时时不抛异常，而是返回 null
public suspend fun <T> withTimeoutOrNull(timeMillis: Long, block: suspend CoroutineScope.() -> T): T?

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // 场景 1：任务在超时前完成 → 返回正常结果
    val result1 = withTimeoutOrNull(3000L) {
        delay(1000L)         // 只需 1 秒
        "任务完成 ✅"        // 返回这个字符串
    }
    println("场景1: $result1")  // 输出: 场景1: 任务完成 ✅
 
    // 场景 2：任务超时 → 返回 null
    val result2 = withTimeoutOrNull(1000L) {
        delay(3000L)         // 需要 3 秒，但只有 1 秒的窗口
        "任务完成 ✅"        // 永远执行不到
    }
    println("场景2: $result2")  // 输出: 场景2: null
}

fun main() = runBlocking {
    // 使用 Elvis 操作符 (?:) 提供超时降级值
    val data = withTimeoutOrNull(2000L) {
        delay(3000L)                  // 模拟慢请求
        fetchExpensiveData()          // 耗时操作
    } ?: "使用本地缓存数据"            // 超时时的降级方案
 
    println(data)  // 输出: 使用本地缓存数据
}
 
suspend fun fetchExpensiveData(): String {
    // 模拟远程数据获取
    return "远程服务器的新鲜数据"
}

import kotlinx.coroutines.*
 
// 模拟数据层
object DataSource {
    // 模拟远程 API 调用（可能很慢）
    suspend fun fetchRemote(): String {
        delay(5000L)  // 模拟 5 秒网络延迟
        return "最新远程数据 v2.0"
    }
 
    // 本地缓存（立即可用）
    fun getLocalCache(): String {
        return "本地缓存数据 v1.0"
    }
}
 
// 使用 withTimeoutOrNull 实现降级策略
suspend fun loadDataWithFallback(): String {
    // 给远程请求 2 秒的时间窗口
    val remoteData = withTimeoutOrNull(2000L) {
        println("[网络层] 开始请求远程数据...")
        DataSource.fetchRemote()  // 尝试远程获取
    }
 
    // 根据结果判断走哪条路径
    return if (remoteData != null) {
        println("[策略] 使用远程数据")
        remoteData                     // 远程数据获取成功
    } else {
        println("[策略] 远程超时，降级到本地缓存")
        DataSource.getLocalCache()     // 降级到本地缓存
    }
}
 
fun main() = runBlocking {
    val result = loadDataWithFallback()
    println("最终展示: $result")
}

fun main() = runBlocking {
    // 🔴 这里的异常不会变成 null，而是直接传播！
    val result = withTimeoutOrNull(5000L) {
        delay(100L)
        throw IllegalStateException("业务逻辑错误")  // 非取消异常
        "永远到不了"
    }
    // ↑ IllegalStateException 会穿透 withTimeoutOrNull
    //   根本不会走到这里
    println(result)
}

fun main() = runBlocking {
    val result = withTimeoutOrNull(1500L) {
        repeat(3) { i ->
            println("工作中 $i")
            delay(1000L)
        }
        "完成"
    }
    println("结果: $result")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // 启动一个子协程
    val job = launch {
        try {
            println("协程开始工作...")
            // 模拟一个长耗时的挂起操作
            repeat(1000) { i ->
                println("正在处理第 $i 个任务...")
                delay(500L) // 挂起点：取消信号会在此处被检测到
            }
        } finally {
            // ✅ 无论协程是正常结束还是被取消，这里都会执行
            println("[finally] 执行资源清理...")
            println("[finally] 释放数据库连接")
            println("[finally] 关闭文件句柄")
        }
    }
 
    delay(1300L) // 让协程运行一段时间
    println("主协程：准备取消子协程")
    job.cancelAndJoin() // 取消并等待子协程完成
    println("主协程：子协程已完全结束")
}

协程开始工作...
正在处理第 0 个任务...
正在处理第 1 个任务...
正在处理第 2 个任务...
主协程：准备取消子协程
[finally] 执行资源清理...
[finally] 释放数据库连接
[finally] 关闭文件句柄
主协程：子协程已完全结束

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            repeat(1000) { i ->
                println("工作中: $i")
                delay(500L)
            }
        } finally {
            println("[finally] 开始清理...")
 
            // ❌ 危险！在已取消的协程中调用挂起函数
            // 这行 delay 会立即抛出 CancellationException
            try {
                delay(1000L) // 模拟"需要时间的清理操作"
                println("[finally] 这行永远不会打印！")
            } catch (e: CancellationException) {
                println("[finally] delay 被取消了: ${e.message}")
            }
 
            println("[finally] 清理结束")
        }
    }
 
    delay(1300L)
    println("取消协程...")
    job.cancelAndJoin()
    println("协程已结束")
}

工作中: 0
工作中: 1
工作中: 2
取消协程...
[finally] 开始清理...
[finally] delay 被取消了: StandaloneCoroutine was cancelled
[finally] 清理结束
协程已结束

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            repeat(1000) { i ->
                println("工作中: $i")
                delay(500L)
            }
        } finally {
            // ✅ 使用 NonCancellable 上下文包裹，使挂起函数不受取消影响
            withContext(NonCancellable) {
                println("[finally] 开始异步清理...")
                delay(1000L) // 现在可以安全地执行挂起操作了
                println("[finally] 异步清理完成 ✅")
            }
        }
    }
 
    delay(1300L)
    println("取消协程...")
    job.cancelAndJoin()
    println("协程已结束")
}

工作中: 0
工作中: 1
工作中: 2
取消协程...
[finally] 开始异步清理...
[finally] 异步清理完成 ✅
协程已结束

import kotlinx.coroutines.*
 
// 模拟一个"数据库连接"资源
class DatabaseConnection(val name: String) {
    // 打开连接
    fun open() = println("  📂 数据库连接 [$name] 已打开")
    // 查询数据（同步模拟）
    fun query(sql: String) = println("  🔍 执行查询: $sql")
    // 关闭连接
    fun close() = println("  📁 数据库连接 [$name] 已关闭")
}
 
fun main() = runBlocking {
    val job = launch {
        // 在 try 外部声明资源引用
        val db = DatabaseConnection("UserDB")
        try {
            // ---------- 资源获取阶段 ----------
            db.open()
 
            // ---------- 业务逻辑阶段 ----------
            repeat(5) { i ->
                db.query("SELECT * FROM users LIMIT ${i * 10}, 10")
                delay(500L) // 挂起点，取消信号在此检测
            }
 
        } catch (e: CancellationException) {
            // ---------- 取消感知阶段（可选）----------
            // 记录取消日志，但必须重新抛出！
            println("  ⚠️ 协程被取消: ${e.message}")
            throw e // ❗ 关键：不能吞掉 CancellationException
 
        } catch (e: Exception) {
            // ---------- 业务异常处理阶段 ----------
            println("  ❌ 业务异常: ${e.message}")
 
        } finally {
            // ---------- 资源释放阶段（始终执行）----------
            db.close() // ✅ 同步操作，无需 NonCancellable
 
            // 如果需要异步清理：
            withContext(NonCancellable) {
                delay(100L) // 模拟异步日志写入
                println("  📝 清理日志已异步写入")
            }
        }
    }
 
    delay(1200L)
    println(">>> 发送取消信号")
    job.cancelAndJoin()
    println(">>> 一切已安全结束")
}

  📂 数据库连接 [UserDB] 已打开
  🔍 执行查询: SELECT * FROM users LIMIT 0, 10
  🔍 执行查询: SELECT * FROM users LIMIT 10, 10
  🔍 执行查询: SELECT * FROM users LIMIT 20, 10
>>> 发送取消信号
  ⚠️ 协程被取消: StandaloneCoroutine was cancelled
  📁 数据库连接 [UserDB] 已关闭
  📝 清理日志已异步写入
>>> 一切已安全结束

// Java 的 try-with-resources
try (BufferedReader reader = new BufferedReader(new FileReader("data.txt"))) {
    String line = reader.readLine();
    System.out.println(line);
}
// reader 在此处自动关闭，即使发生异常也一样

// Kotlin 标准库中 use 函数的简化版本
public inline fun <T : Closeable?, R> T.use(block: (T) -> R): R {
    var exception: Throwable? = null // 用于记录 block 中的异常
    try {
        return block(this) // 执行用户传入的 lambda，this 就是资源本身
    } catch (e: Throwable) {
        exception = e // 记录异常
        throw e       // 重新抛出
    } finally {
        // 根据资源是否为 null 以及是否有异常来决定关闭策略
        when {
            this == null -> {} // 资源为 null，什么都不做
            exception == null -> close() // 没有异常，正常关闭
            else -> {
                try {
                    close() // 有异常时也尝试关闭
                } catch (closeException: Throwable) {
                    // close() 抛出的异常作为 suppressed 异常附加
                    exception.addSuppressed(closeException)
                }
            }
        }
    }
}

import java.io.File
import java.io.BufferedReader
import java.io.FileReader
import java.io.PrintWriter
 
fun main() {
    // ========== 示例 1：读取文件 ==========
    // BufferedReader 实现了 Closeable 接口
    // use 会在 lambda 结束后自动调用 reader.close()
    val content = BufferedReader(FileReader("input.txt")).use { reader ->
        reader.readText() // 读取全部内容，作为 lambda 返回值
    }
    println("文件内容: $content")
 
    // ========== 示例 2：Kotlin 更简洁的写法 ==========
    // File 的 bufferedReader() 返回 BufferedReader
    val lines = File("input.txt").bufferedReader().use { it.readLines() }
    lines.forEach { println(it) }
 
    // ========== 示例 3：写入文件 ==========
    PrintWriter("output.txt").use { writer ->
        writer.println("第一行数据") // 写入数据
        writer.println("第二行数据") // 继续写入
        // 离开 use 块后，writer 自动 flush 并 close
    }
}

import kotlinx.coroutines.*
import java.io.BufferedReader
import java.io.FileReader
 
fun main() = runBlocking {
    val job = launch {
        // use 确保 reader 一定会被关闭
        BufferedReader(FileReader("large_file.txt")).use { reader ->
            var lineNum = 0
            // 逐行读取大文件
            reader.forEachLine { line ->
                lineNum++
                println("读取第 $lineNum 行: ${line.take(20)}...") // 只打印前20字符
                // ❗ 关键：在循环中手动插入挂起点
                // 因为 forEachLine 本身不是挂起函数
                // 需要用 ensureActive() 或 yield() 让协程有机会响应取消
                ensureActive()
            }
        }
        // 如果协程在读取过程中被取消：
        // 1. ensureActive() 抛出 CancellationException
        // 2. use 捕获异常 → 调用 reader.close() → 重新抛出异常
        // 3. 文件句柄被安全释放 ✅
    }
 
    delay(100L) // 让协程读一小会儿
    job.cancelAndJoin() // 取消协程
    println("文件资源已安全释放")
}

// ===== 协程运行中 =====
// ┌──────────────┐     ┌────────────────┐     ┌──────────────┐
// │  Coroutine   │────▶│ BufferedReader │────▶│  FileHandle  │
// │  (Active)    │     │  (resource)    │     │  (OS 资源)   │
// └──────────────┘     └────────────────┘     └──────────────┘
//
// ===== 取消后 use 执行 close() =====
// ┌──────────────┐     ┌────────────────┐     ┌──────────────┐
// │  Coroutine   │  ✕  │ BufferedReader │  ✕  │  FileHandle  │
// │ (Cancelled)  │     │  (closed)      │     │  (released)  │
// └──────────────┘     └────────────────┘     └──────────────┘

import java.io.File
 
fun copyFile(src: String, dst: String) {
    // 外层 use 管理输入流
    File(src).inputStream().use { input ->
        // 内层 use 管理输出流
        File(dst).outputStream().use { output ->
            // 执行复制操作
            input.copyTo(output) // Kotlin 标准库的便捷方法
            println("复制完成: $src → $dst")
        }
        // ← output 在此处关闭（内层 use 结束）
    }
    // ← input 在此处关闭（外层 use 结束）
}
 
fun main() {
    copyFile("source.txt", "destination.txt")
}

import kotlinx.coroutines.*
import java.io.File
 
fun main() = runBlocking {
    val job = launch {
        try {
            // use 负责管理文件资源的自动关闭
            File("data.txt").bufferedReader().use { reader ->
                reader.forEachLine { line ->
                    println("处理: $line")
                    ensureActive() // 协程取消检查点
                }
            }
        } finally {
            // finally 负责额外的清理逻辑（非 Closeable 资源）
            println("重置全局状态标志...")
            withContext(NonCancellable) {
                delay(50)
                println("发送清理完成通知 ✅")
            }
        }
    }
 
    delay(100L)
    job.cancelAndJoin()
}

fun main() = runBlocking {
    val job = launch {
        try {
            println("A")
            delay(5000L)
            println("B")
        } finally {
            println("C")
            delay(1000L)
            println("D")
        }
    }
    delay(100L)
    job.cancelAndJoin()
    println("E")
}

// 父协程不会因为子协程取消而崩溃
val parent = launch {
    val child = launch {
        delay(Long.MAX_VALUE) // 挂起，等待取消
    }
    child.cancel()           // 取消子协程 —— CancellationException
    child.join()             // 等待子协程完成
    println("父协程继续运行") // ✅ 正常执行到这里
}

finally {
    withContext(NonCancellable) {
        // 在此块内，即使协程已取消，挂起函数仍可正常执行
        database.saveCleanupLog()  // 挂起操作，正常执行
    }
}

suspend fun processFile(path: String) {
    // use 自动关闭文件流
    File(path).bufferedReader().use { reader ->
        // 业务逻辑...
    }
    // 如果协程被取消，use 会在内部 finally 中调用 reader.close()
}

┌─────────────────────────────────────────────────────────────────┐
│                  协程取消与超时 · 五条黄金法则                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ① 取消是协作式的 —— 协程必须主动检查才能响应取消                    │
│                                                                 │
│  ② CancellationException ≠ 错误 —— 它是正常的取消信号              │
│                                                                 │
│  ③ finally 中需要挂起 → 用 withContext(NonCancellable)            │
│                                                                 │
│  ④ 超时用 withTimeout / withTimeoutOrNull 按需选择                │
│                                                                 │
│  ⑤ 善用 finally + use 确保资源零泄漏                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

val job = launch {
    var count = 0
    while (count < 1_000_000) {   // 纯计算，无挂起点
        count++
    }
    println("Done: $count")
}
delay(1)       // 给协程一点启动时间
job.cancel()   // 取消协程
job.join()     // 等待完成

fun main() = runBlocking {
    val result = withTimeoutOrNull(200L) {
        try {
            delay(500L)           // 超时会在此处取消
            "Success"
        } finally {
            println("Cleanup")
            delay(100L)           // finally 中的挂起调用
            println("Cleanup Done")
        }
    }
    println("Result: $result")
}