协程作用域与Job ⭐⭐⭐

// CoroutineScope 是一个接口，只有一个属性
public interface CoroutineScope {
    // 该作用域关联的协程上下文
    public val coroutineContext: CoroutineContext
}

// ❌ 假想：无作用域的世界
fun loadData() {
    // 启动协程，但没人管它
    launchGlobal {
        val data = fetchFromNetwork()  // 如果 Activity 已销毁，这里还在跑
        updateUI(data)                 // 崩溃！UI 已不存在
    }
}

// 使用 CoroutineScope() 工厂函数创建
// 注意：这里的 CoroutineScope() 是函数，不是构造函数（首字母大写的函数）
val myScope = CoroutineScope(Dispatchers.Default + Job())
//                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
//                           传入一个 CoroutineContext
//                           = 调度器 + Job 组合而成
 
// 在该作用域中启动协程
myScope.launch {
    println("运行在 myScope 管理下")
}

// 注意是小写 coroutineScope —— 这是一个挂起函数
// 它会创建一个新的作用域，并等待内部所有协程完成后才返回
suspend fun loadData() = coroutineScope {
    // 在这个 block 内启动的协程，都属于这个临时作用域
    val deferred1 = async { fetchUserProfile() }   // 子协程 1
    val deferred2 = async { fetchUserOrders() }     // 子协程 2
    // coroutineScope 会等 deferred1 和 deferred2 都完成
    // 然后才返回——这就是结构化并发的体现
    ProcessResult(deferred1.await(), deferred2.await())
}

// 让一个类实现 CoroutineScope 接口
// 常用于 Presenter、ViewModel 等有明确生命周期的组件
class MyPresenter : CoroutineScope {
 
    // 创建一个独立的 Job，用于控制该作用域的生命周期
    private val job = Job()
 
    // 实现接口唯一的属性：组合 Job + 调度器
    override val coroutineContext: CoroutineContext
        get() = Dispatchers.Main + job
 
    fun loadData() {
        // 因为 MyPresenter 本身就是 CoroutineScope
        // 所以可以直接调用 launch，无需 scope.launch
        launch {
            val data = fetchFromNetwork()
            updateUI(data)
        }
    }
 
    fun destroy() {
        // Presenter 销毁时，取消 Job → 取消所有子协程
        job.cancel()
    }
}

val scope = CoroutineScope(Dispatchers.IO + Job())
 
// 启动协程 —— Job 树新增一个子节点
val job1 = scope.launch {
    // 协程体：开始执行具体业务逻辑
    delay(1000L)
    println("Job1 完成")
}
 
// 再启动一个 —— Job 树再新增一个子节点
val job2 = scope.launch {
    delay(2000L)
    println("Job2 完成")
}

// 取消单个协程
job1.cancel()    // 仅取消 job1，job2 不受影响
 
// ⚡ 取消整个作用域 —— 核弹级操作
scope.cancel()   // scope 内所有协程（job1, job2 ...）全部取消
                 // 且该 scope 不可再用于启动新协程！

fun main() = runBlocking {
    val scope = CoroutineScope(Dispatchers.Default + Job())
 
    val job = scope.launch {
        delay(1000L)
        println("工作完成")
    }
 
    // join() 是挂起函数 —— 暂停当前协程，直到 job 执行完毕
    job.join()
    println("继续执行后续逻辑")
}
// 输出：
// 工作完成
// 继续执行后续逻辑

val scope = CoroutineScope(Dispatchers.Default + Job())
 
// 第一次：正常启动
scope.launch { println("第一次启动 ✅") }
 
// 取消作用域
scope.cancel()
 
// 第二次：尝试再次启动 —— 静默失败！不会执行，也不会报错！
scope.launch { println("第二次启动 ❓ 永远不会打印") }

class MyManager {
    // 使用 var 而非 val，以便重新赋值
    private var scope = createScope()
 
    private fun createScope() = CoroutineScope(Dispatchers.Default + Job())
 
    fun doWork() {
        scope.launch { /* ... */ }
    }
 
    fun stop() {
        scope.cancel()         // 取消当前 scope
    }
 
    fun restart() {
        scope.cancel()         // 先确保旧的已取消
        scope = createScope()  // 创建全新 scope
    }
}

suspend fun demonstrateScopes() {
    // coroutineScope：一个子协程失败 → 其他兄弟协程也被取消
    try {
        coroutineScope {
            launch { delay(Long.MAX_VALUE) }  // 子协程 A：一直等待
            launch { throw RuntimeException("Boom!") }  // 子协程 B：抛异常
            // → 子协程 A 也会被取消，因为 B 的异常会向上传播取消整个 scope
        }
    } catch (e: RuntimeException) {
        println("coroutineScope 捕获到异常: ${e.message}")
    }
 
    // supervisorScope：一个子协程失败 → 其他兄弟协程不受影响
    supervisorScope {
        launch { delay(1000); println("子协程 A 正常完成 ✅") }  // 不会被取消
        launch { throw RuntimeException("Boom!") }               // 独自失败
        // → 子协程 A 继续运行，不受 B 影响
    }
}

// 概念上等价于（实际实现更精巧）
// Map<Key<*>, Element>
 
// 常见的 Key-Element 对：
// Job.Key         → Job 实例（控制生命周期）
// ContinuationInterceptor.Key → Dispatcher 实例（决定线程调度）
// CoroutineName.Key → CoroutineName 实例（调试用名称）
// CoroutineExceptionHandler.Key → 异常处理器实例

val scope = CoroutineScope(Dispatchers.IO + CoroutineName("myCoroutine") + Job())
 
// 通过 Key 获取对应元素（类型安全，不需要强制转换）
val job: Job? = scope.coroutineContext[Job]
//                                     ^^^ 这是 Job.Key 的简写（companion object 实现了 Key 接口）
 
val name: CoroutineName? = scope.coroutineContext[CoroutineName]
println(name)  // CoroutineName(myCoroutine)
 
val dispatcher = scope.coroutineContext[ContinuationInterceptor]
println(dispatcher)  // Dispatchers.IO

// 基础上下文
val base = Dispatchers.Default + CoroutineName("base")
 
// 合并新元素 —— 右侧覆盖左侧同 Key 的值
val merged = base + Dispatchers.IO
// 结果：CoroutineName("base") + Dispatchers.IO
// Dispatchers.Default 被 Dispatchers.IO 覆盖了（同属 ContinuationInterceptor.Key）
 
// 多元素组合（实际开发中最常见的写法）
val fullContext = Job() +                             // 生命周期控制
                 Dispatchers.Main +                   // 线程调度
                 CoroutineName("fetchUser") +         // 调试名称
                 CoroutineExceptionHandler { _, e ->  // 异常处理
                     println("捕获异常: $e")
                 }

val ctx = Dispatchers.IO + CoroutineName("test") + Job()
 
// 移除 CoroutineName 元素
val reduced = ctx.minusKey(CoroutineName)
// 结果只剩 Dispatchers.IO + Job()

val ctx = Dispatchers.IO + CoroutineName("demo") + Job()
 
// fold 类似于集合的 fold，遍历上下文中的每个元素
val description = ctx.fold("Context 内容: ") { acc, element ->
    "$acc\n  - $element"
}
println(description)
// Context 内容:
//   - JobImpl{Active}
//   - CoroutineName(demo)
//   - Dispatchers.IO

val scope = CoroutineScope(Dispatchers.IO + CoroutineName("worker"))
 
scope.launch {
    // 在协程体内部，coroutineContext 是一个自动可用的属性
    println("名称: ${coroutineContext[CoroutineName]}")
    // 输出: 名称: CoroutineName(worker)
 
    println("调度器: ${coroutineContext[ContinuationInterceptor]}")
    // 输出: 调度器: Dispatchers.IO
 
    println("Job: ${coroutineContext[Job]}")
    // 输出: Job: StandaloneCoroutine{Active}@xxxx
    // 注意：这里的 Job 是 launch 创建的新子 Job，不是 scope 的根 Job
}

// 子协程上下文 = 父 coroutineContext + 子协程参数中的覆盖 + 新 Job()

val scope = CoroutineScope(
    Dispatchers.IO +                    // 父级调度器
    CoroutineName("parent") +           // 父级名称
    Job()                               // 父级 Job
)
 
scope.launch(Dispatchers.Main + CoroutineName("child")) {
    // 最终上下文：
    // Dispatcher  → Dispatchers.Main     (被子协程参数覆盖)
    // Name        → CoroutineName(child) (被子协程参数覆盖)
    // Job         → 新的子 Job           (每次 launch 都会创建新 Job)
    //               └── parent: scope 的根 Job
 
    println(coroutineContext[ContinuationInterceptor]) // Dispatchers.Main
    println(coroutineContext[CoroutineName])            // CoroutineName(child)
    println(coroutineContext[Job])                      // StandaloneCoroutine{Active}
}

// ❌ 错误理解：我传入 Job 就能脱离父 Scope 管控？
val myJob = Job()
scope.launch(myJob) {
    // 实际上：新创建的协程 Job 的 parent = myJob
    // myJob 与 scope 的根 Job 无关 → 断开了结构化并发链条！
    // 这是一个常见的反模式，会导致无法正常取消
}

fun main() = runBlocking {
    val scope = CoroutineScope(Dispatchers.Default + CoroutineName("root"))
    
    scope.launch(CoroutineName("child")) {
        println("A: ${coroutineContext[CoroutineName]}")
    }
    
    scope.cancel()
    
    scope.launch {
        println("B: ${coroutineContext[CoroutineName]}")
    }
    
    delay(1000L)
}

// kotlinx.coroutines 库中的定义
public object GlobalScope : CoroutineScope {
    // 它的上下文是空的 EmptyCoroutineContext
    // 这意味着：没有默认的 Job 父节点，没有指定调度器
    override val coroutineContext: CoroutineContext
        get() = EmptyCoroutineContext
}

import kotlinx.coroutines.*
 
fun main() {
    // 在 GlobalScope 中启动一个协程
    // 返回的 Job 是一个"孤儿"，没有父 Job 管理它
    val job = GlobalScope.launch {
        delay(1000L)                    // 非阻塞挂起 1 秒
        println("GlobalScope 协程执行完毕") // 1 秒后打印
    }
 
    // 因为 GlobalScope 协程是守护性质的，
    // 如果主线程结束了，协程也会随之消亡
    Thread.sleep(2000L) // 阻塞主线程 2 秒以等待协程完成
}

class MyActivity : AppCompatActivity() {
 
    fun fetchData() {
        // 在 GlobalScope 中启动的协程，与 Activity 无任何绑定
        GlobalScope.launch {
            val data = apiService.getData()  // 网络请求
            // ⚠️ 如果此时 Activity 已经被销毁(onDestroy)
            // 这行代码仍然会执行，尝试更新一个已销毁的 UI
            textView.text = data.toString()  // 💥 可能崩溃或内存泄漏
        }
    }
 
    // 即使在 onDestroy 中，你也无法轻松取消所有 GlobalScope 协程
    // 因为它们不属于任何可管理的 scope
}

// ❌ 反模式：GlobalScope 产生的协程是"孤儿"
GlobalScope.launch {
    // 这个协程没有父亲，不受任何 scope 管控
    // 出了异常也不会传播给任何"上级"
}
 
// ✅ 正确做法：在一个有明确生命周期的 scope 中启动
viewModelScope.launch {
    // 这个协程属于 ViewModel 的作用域
    // ViewModel 被清除时，协程自动取消
}

// 场景：应用级别的、需要伴随整个进程生命周期的后台任务
// 例如：全局的日志上报、应用级别的缓存预热
// 即使如此，更推荐自定义一个带 SupervisorJob 的 Application 级 scope
val appScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)

// kotlinx.coroutines 库中的定义
public fun MainScope(): CoroutineScope =
    // SupervisorJob：子协程失败不会牵连其他兄弟协程
    // Dispatchers.Main：所有协程默认在主线程上调度
    CoroutineScope(SupervisorJob() + Dispatchers.Main)

class MyActivity : AppCompatActivity() {
 
    // 创建一个与 Activity 关联的主线程作用域
    private val scope = MainScope()
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
 
        // 在 MainScope 中启动协程
        scope.launch {
            // 默认运行在 Dispatchers.Main（主线程）
            val data = withContext(Dispatchers.IO) {
                // 切到 IO 线程执行网络请求
                apiService.fetchData()
            }
            // 自动回到主线程更新 UI
            textView.text = data.toString()
        }
 
        // 可以同时启动多个协程，它们都受同一个 scope 管理
        scope.launch {
            delay(5000L)
            showToast("5秒提醒")
        }
    }
 
    override fun onDestroy() {
        super.onDestroy()
        // ⚡ 关键：手动取消作用域，所有子协程一并取消
        // 如果忘记这一步 → 内存泄漏！
        scope.cancel()
    }
}

scope.launch { loadUserProfile() }   // 协程 A：加载用户资料
scope.launch { loadRecommendation() } // 协程 B：加载推荐内容
scope.launch { loadNotifications() }  // 协程 C：加载通知

// build.gradle.kts
dependencies {
    // viewModelScope 所在的库
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7")
}

// androidx.lifecycle.ViewModel 的扩展属性
public val ViewModel.viewModelScope: CoroutineScope
    get() {
        // 先尝试从缓存中获取
        val scope: CoroutineScope? = this.getTag(JOB_KEY)
        if (scope != null) {
            return scope  // 如果已创建，直接复用
        }
        // 首次访问时创建：SupervisorJob + Dispatchers.Main.immediate
        return setTagIfAbsent(
            JOB_KEY,
            CloseableCoroutineScope(
                SupervisorJob() + Dispatchers.Main.immediate
            )
        )
    }

class UserViewModel(
    private val userRepository: UserRepository
) : ViewModel() {
 
    // LiveData 暴露给 UI 层
    private val _user = MutableLiveData<User>()
    val user: LiveData<User> = _user
 
    private val _error = MutableLiveData<String>()
    val error: LiveData<String> = _error
 
    fun loadUser(userId: String) {
        // 使用 viewModelScope 启动协程
        // 当 ViewModel 被回收时，这个协程会自动取消
        viewModelScope.launch {
            try {
                // withContext 切换到 IO 调度器执行耗时操作
                val result = withContext(Dispatchers.IO) {
                    userRepository.fetchUser(userId) // 网络/数据库请求
                }
                // 自动回到 Main 线程，安全更新 LiveData
                _user.value = result
            } catch (e: CancellationException) {
                // 协程取消异常需要重新抛出，不能吞掉！
                // 这是 Kotlin 协程的重要约定
                throw e
            } catch (e: Exception) {
                // 业务异常处理
                _error.value = "加载失败: ${e.message}"
            }
        }
    }
 
    // ❌ 不需要手动重写 onCleared() 来取消协程
    // viewModelScope 已经帮你处理好了！
}

// build.gradle.kts
dependencies {
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")
}

// LifecycleOwner 的扩展属性
public val LifecycleOwner.lifecycleScope: LifecycleCoroutineScope
    get() = lifecycle.coroutineScope
 
// Lifecycle 的扩展属性
public val Lifecycle.coroutineScope: LifecycleCoroutineScope
    get() {
        // ... 缓存逻辑省略 ...
        // 核心：SupervisorJob() + Dispatchers.Main.immediate
        // 并注册 LifecycleObserver，在 ON_DESTROY 时自动 cancel
        val newScope = LifecycleCoroutineScope(this,
            SupervisorJob() + Dispatchers.Main.immediate
        )
        return newScope
    }

class MyFragment : Fragment() {
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // lifecycleScope 绑定到 Fragment 的生命周期
        // Fragment onDestroy 时自动取消
        lifecycleScope.launch {
            val data = withContext(Dispatchers.IO) {
                repository.loadData() // IO 线程加载数据
            }
            // 回到主线程更新 UI
            binding.textView.text = data
        }
    }
}

// 只在 Lifecycle 至少处于 STARTED 状态时执行
// 当 Lifecycle 降到 STARTED 以下（如进入后台），协程自动挂起
// 当 Lifecycle 回到 STARTED 以上（如回到前台），协程自动恢复
lifecycleScope.launch {
    // repeatOnLifecycle 是最推荐的 API
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        // 这个 block 在每次进入 STARTED 时启动
        // 在每次降到 STARTED 以下时取消
        viewModel.uiState.collect { state ->
            // 安全地更新 UI，保证只在可见时执行
            updateUI(state)
        }
    }
}

// ⚠️ 已标记为 @Deprecated，不推荐使用
lifecycleScope.launchWhenStarted {
    // 当 lifecycle 低于 STARTED 时，协程只是 "挂起"(suspend)
    // 但并没有取消！上游 Flow 仍在产生数据，只是没人消费
    viewModel.uiState.collect { state ->
        updateUI(state)
    }
}

// ViewModel 层：用 viewModelScope 处理业务
class WeatherViewModel(
    private val weatherRepo: WeatherRepository
) : ViewModel() {
 
    // StateFlow 持有 UI 状态
    private val _uiState = MutableStateFlow<WeatherUiState>(WeatherUiState.Loading)
    val uiState: StateFlow<WeatherUiState> = _uiState.asStateFlow()
 
    init {
        // viewModelScope：屏幕旋转时协程不中断
        viewModelScope.launch {
            try {
                val weather = withContext(Dispatchers.IO) {
                    weatherRepo.getCurrentWeather()  // 网络请求
                }
                _uiState.value = WeatherUiState.Success(weather) // 更新状态
            } catch (e: Exception) {
                _uiState.value = WeatherUiState.Error(e.message ?: "Unknown")
            }
        }
    }
}
 
// UI 层（Fragment）：用 lifecycleScope 收集状态
class WeatherFragment : Fragment() {
 
    private val viewModel: WeatherViewModel by viewModels()
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
 
        // viewLifecycleOwner.lifecycleScope：绑定到 Fragment View 的生命周期
        // 比 this.lifecycleScope 更精确，避免 View 销毁后仍更新 UI
        viewLifecycleOwner.lifecycleScope.launch {
            // repeatOnLifecycle 确保只在 STARTED 以上状态收集
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.uiState.collect { state ->
                    // 根据状态更新 UI
                    when (state) {
                        is WeatherUiState.Loading -> showLoading()   // 显示加载
                        is WeatherUiState.Success -> showWeather(state.data) // 显示数据
                        is WeatherUiState.Error -> showError(state.msg)  // 显示错误
                    }
                }
            }
        }
    }
}

// Job 接口的核心签名（简化版）
public interface Job : CoroutineContext.Element {
    // 伴生对象作为 CoroutineContext.Key，用于从上下文中检索 Job
    public companion object Key : CoroutineContext.Key<Job>
 
    // 三个核心状态查询属性
    public val isActive: Boolean       // 是否处于活跃状态
    public val isCompleted: Boolean    // 是否已完成（成功或失败）
    public val isCancelled: Boolean    // 是否已取消
 
    // 核心操作方法
    public fun cancel(cause: CancellationException? = null)  // 取消协程
    public suspend fun join()                                  // 挂起等待完成
    public val children: Sequence<Job>                         // 所有子 Job
    public fun start(): Boolean                                // 手动启动（用于懒启动）
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // launch 返回一个 Job 对象，它就是这个协程的"句柄"
    val job: Job = launch {
        // 协程体：具体的业务逻辑
        println("协程正在执行...")
        delay(1000L)
        println("协程执行完毕")
    }
 
    // 通过句柄，我们可以：
    println("Job 是否活跃: ${job.isActive}")       // 查询状态
    job.join()                                       // 等待完成
    println("Job 是否已完成: ${job.isCompleted}")    // 再次查询
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    launch {
        // 在协程内部，通过 coroutineContext[Job] 获取自身的 Job 引用
        val myJob = coroutineContext[Job]
        println("我自己的 Job: $myJob")
        println("我是否活跃: ${myJob?.isActive}")  // true，因为正在执行中
    }
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // 使用 LAZY 模式创建协程，不会自动启动
    val lazyJob = launch(start = CoroutineStart.LAZY) {
        println("我被启动了！")
    }
 
    // 此时 Job 处于 New 状态
    println("isActive: ${lazyJob.isActive}")       // false
    println("isCompleted: ${lazyJob.isCompleted}")  // false
    println("isCancelled: ${lazyJob.isCancelled}")  // false
 
    // 手动启动
    lazyJob.start()   // New → Active
    lazyJob.join()     // 等待完成
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        // 进入 Active 状态
        println("isActive 内部: ${coroutineContext[Job]?.isActive}")  // true
        delay(500L)  // 挂起期间仍然是 Active
        println("delay 后仍然 Active")
    }
 
    println("isActive 外部: ${job.isActive}")  // true
    job.join()
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val parentJob = launch {
        // 启动一个子协程
        launch {
            delay(2000L)  // 子协程需要 2 秒
            println("子协程完成")
        }
        // 父协程体本身很快就执行完了
        println("父协程体代码执行完毕")
        // ➡️ 此时 parentJob 进入 Completing 状态
        // 但 isActive 仍然是 true（外部无法区分 Active 和 Completing）
    }
 
    delay(500L)  // 等 500ms，此时父协程体已执行完，但子协程还在跑
    println("parentJob.isActive: ${parentJob.isActive}")       // true (Completing)
    println("parentJob.isCompleted: ${parentJob.isCompleted}") // false
 
    parentJob.join()  // 等待全部结束
    println("parentJob.isCompleted: ${parentJob.isCompleted}") // true
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            println("开始工作...")
            delay(5000L)  // 模拟长时间任务
            println("工作完成")  // 不会执行到这里
        } finally {
            // Cancelling 状态期间，finally 块会被执行
            println("进入 finally 清理资源")
            println("isCancelled: ${coroutineContext[Job]?.isCancelled}")  // true
            // ⚠️ 在 Cancelling 状态下，普通的挂起函数会直接抛出 CancellationException
            // 如需在 finally 中执行挂起操作，需使用 withContext(NonCancellable)
        }
    }
 
    delay(500L)         // 等协程启动并运行一会儿
    job.cancel()        // Active → Cancelling
    println("取消后 isCancelled: ${job.isCancelled}")  // true
    job.join()          // 等待 Cancelling → Cancelled
    println("最终 isCompleted: ${job.isCompleted}")     // true（Cancelled 也算 Completed）
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // ============= 场景 1: 正常完成的生命周期 =============
    println("===== 正常完成 =====")
    val normalJob = launch(start = CoroutineStart.LAZY) {
        delay(100L)  // 模拟简短任务
    }
 
    // New 状态
    printJobState("New", normalJob)          // isActive=false, isCompleted=false, isCancelled=false
 
    normalJob.start()  // New → Active
    printJobState("Active", normalJob)       // isActive=true, isCompleted=false, isCancelled=false
 
    normalJob.join()   // Active → Completing → Completed
    printJobState("Completed", normalJob)    // isActive=false, isCompleted=true, isCancelled=false
 
    // ============= 场景 2: 取消的生命周期 =============
    println("\n===== 取消流程 =====")
    val cancelJob = launch {
        delay(10000L)  // 长时间任务
    }
 
    delay(50L)  // 确保进入 Active
    printJobState("Active", cancelJob)       // isActive=true, isCompleted=false, isCancelled=false
 
    cancelJob.cancel()  // Active → Cancelling → Cancelled
    printJobState("Cancelled", cancelJob)    // isActive=false, isCompleted=false, isCancelled=true
 
    cancelJob.join()    // 等待彻底完成
    printJobState("Final", cancelJob)        // isActive=false, isCompleted=true, isCancelled=true
}
 
// 辅助函数：打印 Job 的三个核心状态属性
fun printJobState(label: String, job: Job) {
    println("[$label] isActive=${job.isActive}, isCompleted=${job.isCompleted}, isCancelled=${job.isCancelled}")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch(Dispatchers.Default) {
        var count = 0L
        // ❌ 纯计算循环，没有挂起点 → 无法自动响应取消
        while (count < 1_000_000_000L) {
            count++
        }
        println("循环结束，count = $count")  // 即使被取消，仍会执行到这里
    }
 
    delay(100L)
    println("准备取消...")
    job.cancel()   // 发出取消信号
    job.join()     // 等待（但协程根本不理会取消）
    println("结束")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // ===== 方式 1: 手动检查 isActive =====
    val job1 = launch(Dispatchers.Default) {
        var count = 0L
        // 在循环条件中检查 isActive（CoroutineScope 的扩展属性）
        while (isActive && count < 1_000_000_000L) {
            count++
        }
        println("方式1: count = $count, isActive = $isActive")
    }
 
    // ===== 方式 2: 使用 ensureActive() 或 yield() =====
    val job2 = launch(Dispatchers.Default) {
        var count = 0L
        while (count < 1_000_000_000L) {
            count++
            if (count % 100_000 == 0L) {
                ensureActive()  // 如果已取消，直接抛出 CancellationException
                // 或者使用 yield()，还能让出线程给其他协程
            }
        }
    }
 
    delay(100L)
    job1.cancel()
    job2.cancel()
    job1.join()
    job2.join()
    println("两个协程都已取消")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            delay(5000L)
        } catch (e: CancellationException) {
            // 取消时，挂起函数会抛出 CancellationException
            println("被取消了，原因: ${e.message}")
        }
    }
 
    delay(200L)
    // 可以传入自定义的取消原因
    job.cancel(CancellationException("用户手动取消了操作"))
    job.join()
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        try {
            repeat(1000) { i ->
                println("工作中: $i")
                delay(100L)
            }
        } finally {
            println("清理资源...")
            // 如果需要在 finally 中调用挂起函数
            withContext(NonCancellable) {
                delay(200L)  // 在 NonCancellable 上下文中，挂起函数不会因取消而失败
                println("清理完成！")
            }
        }
    }
 
    delay(350L)
    println("准备取消...")
    // cancelAndJoin() = cancel() + join()，是推荐的惯用写法
    job.cancelAndJoin()
    println("协程已彻底结束")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job = launch {
        println("Step 1: 开始下载...")
        delay(1000L)  // 模拟网络下载
        println("Step 2: 下载完成")
    }
 
    println("主协程：等待下载完成...")
    job.join()  // ← 挂起，直到 job 完成
    // join() 返回后，可以确保 job 已经结束
    println("主协程：下载已完成，继续处理...")
}
// 输出顺序：
// 主协程：等待下载完成...
// Step 1: 开始下载...
// Step 2: 下载完成
// 主协程：下载已完成，继续处理...

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val job1 = launch {
        delay(1000L)
        println("任务1完成")
    }
 
    val job2 = launch {
        delay(2000L)
        println("任务2完成")
    }
 
    val job3 = launch {
        delay(1500L)
        println("任务3完成")
    }
 
    // 按顺序等待每个 Job
    // 注意：三个协程是并发执行的，join 只是等待点
    job1.join()
    println("--- job1 已确认完成 ---")
    job2.join()
    println("--- job2 已确认完成 ---")
    job3.join()
    println("--- job3 已确认完成 ---")
}
// 输出：
// 任务1完成（~1s）
// --- job1 已确认完成 ---
// 任务3完成（~1.5s）
// 任务2完成（~2s）
// --- job2 已确认完成 ---
// --- job3 已确认完成 ---   ← job3 其实在 job2 之前就完成了

// 伪代码：三个属性与六种状态的映射关系
// State        | isActive | isCompleted | isCancelled
// -------------|----------|-------------|------------
// New          |  false   |   false     |   false
// Active       |  true    |   false     |   false
// Completing   |  true    |   false     |   false    ← 与 Active 无法区分
// Completed    |  false   |   true      |   false
// Cancelling   |  false   |   false     |   true
// Cancelled    |  false   |   true      |   true     ← isCompleted 也为 true！

import kotlinx.coroutines.*
 
// 封装一个状态判断辅助函数
fun diagnoseJob(job: Job): String = when {
    job.isActive                          -> "运行中 (Active/Completing)"
    job.isCancelled && job.isCompleted    -> "已取消 (Cancelled)"
    job.isCancelled && !job.isCompleted   -> "取消中 (Cancelling)"
    job.isCompleted                       -> "已完成 (Completed)"
    else                                  -> "新建未启动 (New)"
}
 
fun main() = runBlocking {
    // New 状态
    val lazyJob = launch(start = CoroutineStart.LAZY) { delay(100L) }
    println(diagnoseJob(lazyJob))  // 新建未启动 (New)
 
    // Active 状态
    val activeJob = launch { delay(5000L) }
    delay(50L)
    println(diagnoseJob(activeJob))  // 运行中 (Active/Completing)
 
    // Completed 状态
    val doneJob = launch { delay(50L) }
    doneJob.join()
    println(diagnoseJob(doneJob))  // 已完成 (Completed)
 
    // Cancelled 状态
    activeJob.cancelAndJoin()
    println(diagnoseJob(activeJob))  // 已取消 (Cancelled)
 
    lazyJob.cancelAndJoin()  // 清理
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val processingJob = launch(Dispatchers.Default) {
        var processedItems = 0
 
        // isActive 是 CoroutineScope 的扩展属性
        // 本质上等价于 coroutineContext[Job]?.isActive == true
        while (isActive) {
            // 模拟处理数据
            processedItems++
 
            // 每处理 1000 条打印一次进度
            if (processedItems % 1000 == 0) {
                println("已处理 $processedItems 条数据")
            }
 
            // 这里没有挂起点，所以 isActive 检查是唯一的取消响应机制
        }
 
        // while 循环因 isActive == false 退出后，可以做清理
        println("循环结束，共处理 $processedItems 条")
    }
 
    delay(50L)             // 让协程运行一会儿
    processingJob.cancelAndJoin()  // 取消并等待
    println("处理任务已取消")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // 风格 1: isActive —— 温和退出
    launch(Dispatchers.Default) {
        while (isActive) { /* work */ }
        println("温和退出，可以在这里做善后")
    }
 
    // 风格 2: ensureActive —— 直接抛异常
    launch(Dispatchers.Default) {
        while (true) {
            ensureActive()  // 取消时直接抛 CancellationException，跳到 catch/finally
            /* work */
        }
    }
 
    // 风格 3: yield —— 让出线程 + 取消检查
    launch(Dispatchers.Default) {
        while (true) {
            yield()  // 让其他协程有机会执行，同时检查取消
            /* work */
        }
    }
 
    delay(50L)
    coroutineContext.cancelChildren()  // 取消所有子协程
}

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

// 演示父子 Job 关系的建立
fun main() = runBlocking {
    // runBlocking 创建了一个顶层协程，拥有自己的 Job
    val parentJob = coroutineContext[Job]  // 获取当前协程（父）的 Job
    println("父 Job: $parentJob")
 
    val childJob = launch {
        // 这个 launch 在 runBlocking 的 scope 内启动
        // 所以它的 Job 自动成为 parentJob 的子 Job
        println("子 Job: ${coroutineContext[Job]}")
        delay(1000)
    }
 
    // 验证父子关系
    println("childJob 的父亲是 parentJob? ${childJob.parent == parentJob}")  // true
    println("parentJob 的 children 包含 childJob? ${parentJob?.children?.toList()?.contains(childJob)}")  // true
}

// 演示上下文继承与覆盖
fun main() = runBlocking(CoroutineName("父协程")) {
    // 父协程上下文包含: Job(runBlocking 的) + CoroutineName("父协程") + BlockingEventLoop(调度器)
 
    println("父协程上下文: $coroutineContext")
    println("父协程名称: ${coroutineContext[CoroutineName]}")        // CoroutineName("父协程")
    println("父协程调度器: ${coroutineContext[ContinuationInterceptor]}")  // BlockingEventLoop
 
    // 子协程 A：不传任何参数 → 完全继承父上下文（除了 Job）
    launch {
        println("\n子协程 A 名称: ${coroutineContext[CoroutineName]}")        // CoroutineName("父协程") ← 继承
        println("子协程 A 调度器: ${coroutineContext[ContinuationInterceptor]}")  // BlockingEventLoop ← 继承
        println("子协程 A 的 Job 与父相同? ${coroutineContext[Job] == this@runBlocking.coroutineContext[Job]}")  // false ← 新 Job
    }
 
    // 子协程 B：显式传入 CoroutineName → 覆盖父协程的 CoroutineName
    launch(CoroutineName("子协程B") + Dispatchers.IO) {
        println("\n子协程 B 名称: ${coroutineContext[CoroutineName]}")        // CoroutineName("子协程B") ← 覆盖
        println("子协程 B 调度器: ${coroutineContext[ContinuationInterceptor]}")  // Dispatchers.IO ← 覆盖
    }
}

// ⚠️ 危险示例：手动传入 Job 打破父子关系
fun main() = runBlocking {
    val externalJob = Job()  // 一个独立的、无父的 Job
 
    // 虽然在 runBlocking 的 scope 内启动，但传入了外部 Job
    // 这会导致新协程的 parent 变成 externalJob，而非 runBlocking 的 Job
    launch(externalJob) {
        println("我的 parent 是 externalJob，而非 runBlocking 的 Job")
        println("parent: ${coroutineContext[Job]?.parent}")  // 指向 externalJob
        delay(5000)
        println("这行可能永远不会执行")
    }
 
    delay(100)
    println("runBlocking 即将结束，但上面的子协程不受其管控了！")
    // runBlocking 结束时不会等待那个协程，因为父子关系被打破了
    // 同时 externalJob 永远不会 complete（没人调用 externalJob.complete()），可能导致泄漏
}

// 演示父协程等待子协程完成
fun main() = runBlocking {
    println("[${currentTime()}] 父协程开始")
 
    launch {
        println("[${currentTime()}] 子协程 A 开始")
        delay(1000)  // 模拟耗时 1 秒
        println("[${currentTime()}] 子协程 A 结束")
    }
 
    launch {
        println("[${currentTime()}] 子协程 B 开始")
        delay(2000)  // 模拟耗时 2 秒
        println("[${currentTime()}] 子协程 B 结束")
    }
 
    println("[${currentTime()}] 父协程自身代码执行完毕，但还不会结束...")
    // 父协程会自动等待子协程 A 和 B 都完成后才 Completed
}
 
// 辅助函数：获取相对时间
private val startTime = System.currentTimeMillis()
fun currentTime() = "${System.currentTimeMillis() - startTime}ms"

// 在 ViewModel 中使用 viewModelScope
class MyViewModel : ViewModel() {
 
    fun loadDashboard() {
        viewModelScope.launch {
            // 父协程：加载仪表盘
 
            // 子协程 1：加载用户信息
            val userDeferred = async { userRepository.getUser() }
 
            // 子协程 2：加载订单列表
            val ordersDeferred = async { orderRepository.getOrders() }
 
            // 子协程 3：加载推荐内容
            val recommendDeferred = async { recommendRepository.getRecommendations() }
 
            // 父协程等待所有子协程完成后，才组装最终数据
            val dashboard = Dashboard(
                user = userDeferred.await(),
                orders = ordersDeferred.await(),
                recommendations = recommendDeferred.await()
            )
 
            _uiState.value = UiState.Success(dashboard)
        }
        // 当 ViewModel 被清除时，viewModelScope 取消
        // → 父协程取消 → 三个 async 子协程全部取消
        // 没有任何网络请求会被遗忘！
    }
}

// 演示取消的向下传播
fun main() = runBlocking {
    val parentJob = launch {
        println("父协程启动")
 
        // 子协程 A
        val childA = launch {
            try {
                println("  子协程 A 启动")
                delay(5000)  // 模拟长时间任务
                println("  子协程 A 完成")  // 永远不会执行
            } catch (e: CancellationException) {
                println("  子协程 A 被取消: ${e.message}")
            } finally {
                println("  子协程 A 清理资源")
            }
        }
 
        // 子协程 B，它内部还有孙协程
        val childB = launch {
            println("  子协程 B 启动")
 
            // 孙协程
            launch {
                try {
                    println("    孙协程启动")
                    delay(5000)
                    println("    孙协程完成")  // 永远不会执行
                } catch (e: CancellationException) {
                    println("    孙协程被取消: ${e.message}")
                }
            }
 
            delay(5000)
            println("  子协程 B 完成")  // 永远不会执行
        }
 
        delay(5000)
        println("父协程完成")  // 永远不会执行
    }
 
    delay(500)  // 等 500ms 让所有协程都启动
    println("\n--- 取消父协程 ---\n")
    parentJob.cancel(CancellationException("用户关闭了页面"))  // 取消父协程
 
    parentJob.join()  // 等待取消完成
    println("\n所有协程已取消")
}

class MyActivity : AppCompatActivity() {
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
 
        // lifecycleScope 绑定到 Activity 的 Lifecycle
        lifecycleScope.launch {
            // 父协程
 
            launch {
                // 子协程：持续轮询数据
                while (isActive) {  // 协作式检查取消
                    val data = api.poll()
                    updateUI(data)
                    delay(5000)
                }
            }
 
            launch {
                // 子协程：监听 WebSocket
                webSocket.connect()
                try {
                    webSocket.receiveMessages()  // 挂起直到连接关闭或取消
                } finally {
                    webSocket.disconnect()  // 取消时清理连接
                }
            }
        }
        // 当 Activity onDestroy 时:
        // lifecycleScope 取消 → 父协程取消 → 两个子协程全部取消
        // 轮询停止，WebSocket 断开连接。零泄漏！
    }
}

// 演示异常的向上传播
fun main() = runBlocking {
    try {
        coroutineScope {
            // 使用 coroutineScope 而非直接在 runBlocking 中演示
            // 因为 coroutineScope 会重新抛出子协程异常
 
            // 子协程 A：正常工作
            launch {
                try {
                    println("子协程 A: 开始执行长任务")
                    delay(5000)  // 模拟耗时任务
                    println("子协程 A: 完成")  // 永远不会执行
                } catch (e: CancellationException) {
                    println("子协程 A: 被取消了！（因为兄弟 B 出了异常）")
                }
            }
 
            // 子协程 B：500ms 后抛出异常
            launch {
                delay(500)
                println("子协程 B: 即将抛出异常！")
                throw RuntimeException("子协程 B 发生了网络错误")
                // 异常传播路径：子B → 父 coroutineScope → 取消子A → 向上抛出
            }
 
            // 子协程 C：也会被连带取消
            launch {
                try {
                    delay(5000)
                } catch (e: CancellationException) {
                    println("子协程 C: 被取消了！（同样因为兄弟 B）")
                }
            }
        }
    } catch (e: RuntimeException) {
        println("\n捕获到从 coroutineScope 传播出的异常: ${e.message}")
    }
}

// CancellationException vs 普通异常的区别
fun main() = runBlocking {
    val parent = launch {
        val childA = launch {
            delay(3000)
            println("子协程 A 完成")  // 是否执行取决于 B 抛的异常类型
        }
 
        val childB = launch {
            delay(500)
            // 场景一：抛 CancellationException → 只有 B 自己取消，A 不受影响
            // throw CancellationException("B 自行退出")
 
            // 场景二：抛普通异常 → B 失败，A 也被取消，父也取消
            throw RuntimeException("B 出了 bug")
        }
    }
    parent.join()
}

// 使用 supervisorScope 隔离子协程异常
fun main() = runBlocking {
    supervisorScope {
        // 在 supervisorScope 内，子协程的异常不会传播给父协程
 
        val childA = launch {
            delay(3000)
            println("子协程 A 完成 ✅")  // 会执行！不受 B 影响
        }
 
        val childB = launch {
            delay(500)
            throw RuntimeException("子协程 B 失败")
            // 异常不会传播给 supervisorScope
            // 但需要通过 CoroutineExceptionHandler 处理，否则会崩溃
        }
 
        val childC = launch {
            delay(2000)
            println("子协程 C 完成 ✅")  // 也会执行！
        }
    }
}

fun main() = runBlocking {
    val scope = CoroutineScope(Job() + Dispatchers.Default)
 
    val parent = scope.launch {
        launch {
            delay(1000)
            println("A")
        }
        launch {
            delay(500)
            throw RuntimeException("Boom")
        }
        launch {
            delay(1500)
            println("C")
        }
    }
 
    delay(2000)
    println("isActive=${parent.isActive}, isCancelled=${parent.isCancelled}, isCompleted=${parent.isCompleted}")
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // launch 返回 Job，不携带结果
    val job: Job = launch {
        delay(100L)
        println("launch 完成，但没有返回值")
    }
 
    // async 返回 Deferred<Int>，携带一个 Int 类型的结果
    val deferred: Deferred<Int> = async {
        delay(200L)       // 模拟耗时计算
        42                // lambda 最后一行就是返回值
    }
 
    job.join()            // 等待 launch 完成，无法获取结果
    val result: Int = deferred.await()  // 挂起等待 async 完成，并取出结果
    println("async 的结果: $result")     // 输出: async 的结果: 42
}

// CoroutineScope 的扩展函数
// block 的返回值类型 T 决定了 Deferred<T> 的泛型参数
public fun <T> CoroutineScope.async(
    context: CoroutineContext = EmptyCoroutineContext,  // 可选的上下文覆盖
    start: CoroutineStart = CoroutineStart.DEFAULT,     // 启动模式，默认立即调度
    block: suspend CoroutineScope.() -> T               // 协程体，返回值类型为 T
): Deferred<T>

import kotlinx.coroutines.*
import kotlin.system.measureTimeMillis
 
fun main() = runBlocking {
    val time = measureTimeMillis {
        // 两个 async 同时启动，并发执行
        val deferredA: Deferred<String> = async {
            delay(1000L)          // 模拟网络请求 A，耗时 1 秒
            "Response A"          // 返回结果
        }
        val deferredB: Deferred<String> = async {
            delay(1500L)          // 模拟网络请求 B，耗时 1.5 秒
            "Response B"          // 返回结果
        }
 
        // 两个 await 依次挂起等待，但因为协程已经在并发执行
        // 所以总耗时约 1.5 秒（取决于最慢的那个），而非 2.5 秒
        val resultA = deferredA.await()
        val resultB = deferredB.await()
        println("$resultA + $resultB")  // 输出: Response A + Response B
    }
    println("总耗时: ${time}ms")         // 输出: 总耗时: ~1500ms（而非 2500ms）
}

// ❌ 反模式：串行 await，总耗时 2.5 秒
val resultA = async { delay(1000L); "A" }.await()  // 先等 A 完成
val resultB = async { delay(1500L); "B" }.await()  // 再等 B 完成

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // LAZY 模式：创建后不会立即执行
    val lazyDeferred: Deferred<Int> = async(start = CoroutineStart.LAZY) {
        println("开始计算...")  // 只有在 start() 或 await() 后才会打印
        delay(500L)
        100
    }
 
    println("Deferred 已创建，但尚未开始执行")
    delay(1000L)                       // 即使等了 1 秒，协程体也没有执行
 
    // 方式一：显式调用 start() 启动，但不等待结果
    lazyDeferred.start()
 
    // 方式二：调用 await() 也会自动触发启动（如果还没 start 的话）
    val result = lazyDeferred.await()  // 挂起等待结果
    println("结果: $result")            // 输出: 结果: 100
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    // 验证类型关系：Deferred 是 Job 的子类型
    val deferred: Deferred<String> = async {
        delay(100L)
        "Hello"
    }
 
    // Deferred 可以赋值给 Job 类型变量（向上转型）
    val job: Job = deferred    // ✅ 合法，因为 Deferred 继承 Job
    println("deferred is Job: ${deferred is Job}")    // 输出: true
 
    // Job 拥有的属性和方法，Deferred 全都有
    println("isActive: ${deferred.isActive}")          // 输出: true（正在执行）
    println("isCompleted: ${deferred.isCompleted}")    // 输出: false（尚未完成）
    println("isCancelled: ${deferred.isCancelled}")    // 输出: false（未被取消）
 
    val result = deferred.await()                      // 挂起等待并获取结果
    println("isCompleted: ${deferred.isCompleted}")    // 输出: true（已完成）
    println("结果: $result")                            // 输出: 结果: Hello
}

import kotlinx.coroutines.*
 
fun main() = runBlocking {
    val parentJob = launch {
        // 在父协程内部启动 async 子协程
        val deferred = async {
            repeat(100) { i ->
                println("async 子协程: 计算第 $i 步")
                delay(200L)      // 每 200ms 执行一步
            }
            "最终结果"             // 这行永远不会执行到
        }
 
        // 父协程自己也在做事
        delay(500L)
        println("父协程即将完成 launch 块")
    }
 
    delay(300L)                  // 让协程运行 300ms
    parentJob.cancel()           // 取消父协程
    parentJob.join()             // 等待取消完成
 
    // 此时 async 子协程也已被取消
    println("父协程和所有子协程均已取消")
}
// 输出:
// async 子协程: 计算第 0 步
// async 子协程: 计算第 1 步
// 父协程和所有子协程均已取消