kuikly-coroutines-threading

name	kuikly-coroutines-threading
description	Kuikly 协程与多线程编程助手。指导如何在 Kuikly 中进行异步编程，包括 Kuikly 内建协程、kotlinx 协程、kuiklyx 协程库。当用户在 Kuikly 中需要执行异步任务、切换线程、使用协程、回到 Kuikly 线程更新 UI、排查线程安全问题时使用。

Kuikly 协程与多线程编程

核心规则

• Kuikly 线程约束：所有 Kuikly UI 操作（View、Attr、Event、observable、Module 方法、setTimeout 等）只能在 Kuikly 线程调用，Kuikly UI 相关类非线程安全。
• 异步任务完成后必须回到 Kuikly 线程才能更新 UI 或访问响应式属性。
• 动态化场景不支持 kotlinx 协程（js 目标平台不支持多线程），只能使用 Module 机制或 Kuikly 内建协程。

协程实现方式对比

特性	回调（无协程）	Kuikly 内建协程	kotlinx 协程
动态化支持	✅ 支持	✅ 支持	❌ 不支持
依赖库包增量	无	无	kotlinx 协程库
线程安全	不涉及	自动保障	需要考虑

---

三种协程 API

1. Kuikly 内建协程（推荐用于简单异步）

框架自带，始终在 Kuikly 线程执行，无线程切换开销，支持动态化。

API 入口：

• GlobalScope.launch { ... } — 全局作用域
• lifecycleScope.launch { ... } — 绑定 Pager 生命周期（推荐）
• async { ... } / await() — 并发获取结果

import：

import com.tencent.kuikly.core.coroutines.GlobalScope
import com.tencent.kuikly.core.coroutines.launch
import com.tencent.kuikly.core.coroutines.async
import com.tencent.kuikly.core.coroutines.delay

注意： Kuikly 内建协程 API 本身非线程安全，不能在 Kuikly 线程外调用。

2. kotlinx.coroutines 库

Kotlin 官方协程库，支持多线程调度器（Dispatchers.Default/IO/Main 等），不支持动态化。

接入方式：

// iOS & Android
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$KOTLINX_COROUTINES_VERSION")
// 鸿蒙
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$KOTLINX_COROUTINES_OHOS_VERSION")

3. kuiklyx.coroutines 库（切换到 Kuikly 线程）

提供 Dispatchers.Kuikly 调度器和 KuiklyContextScheduler 回调 API，用于从非 Kuikly 线程切回 Kuikly 线程。

接入方式：

// iOS & Android
implementation("com.tencent.kuiklyx:coroutines:$KUIKLYX_COROUTINES_VERSION")
// 鸿蒙
implementation("com.tencent.kuiklyx:coroutines:$KUIKLYX_COROUTINES_OHOS_VERSION")

协程方式 API：

// 启动协程，在 Kuikly 线程执行
GlobalScope.launch(Dispatchers.Kuikly[ctx]) { ... }
// 在协程中切换到 Kuikly 线程
withContext(Dispatchers.Kuikly[ctx]) { ... }

回调方式 API：

KuiklyContextScheduler.runOnKuiklyThread(pagerId) { cancel ->
    if (cancel) return  // pager 已销毁
    // 在 Kuikly 线程执行
}

---

场景选择决策树

根据需求选择合适的异步编程方式：

需要异步编程？
├── 只需简化回调，无多线程诉求？
│   └── → 方式1：Kuikly 内建协程
├── 需要执行耗时任务 + 支持动态化？
│   └── → 方式2：Module 机制（可配合内建协程）
├── 需要多线程 + 不需要动态化？
│   └── → 方式3：kotlinx 协程 + kuiklyx 协程
└── Compose DSL 页面？
    └── → 方式4：LaunchedEffect + withContext

⚠️ 一致性原则：选择方案时，还需关注当前项目或模块中已有的异步编程方式，应优先保持一致，避免在同一模块中混用多套异步方案。

详细场景示例和代码：见 SCENARIOS.md

---

Compose DSL 中的协程

Compose DSL 页面（继承 ComposeContainer）使用 kotlinx 协程体系：

@Composable
fun MyContent() {
    var data by remember { mutableStateOf("") }
    LaunchedEffect(Unit) {
        // 默认在 Kuikly 线程执行（ComposeDispatcher）
        val result = withContext(Dispatchers.IO) {
            // 在 IO 线程执行耗时任务
            fetchData()
        }
        // 自动回到 Kuikly 线程
        data = result
    }
    Text(text = data)
}

关键点：

• LaunchedEffect 默认运行在 Kuikly 线程（通过 ComposeDispatcher 调度）
• 使用 withContext(Dispatchers.IO) 切换到 IO 线程执行耗时任务
• withContext 返回后自动回到 Kuikly 线程
• viewModelScope 也绑定到 Kuikly 线程，ViewModel 销毁时自动取消

Dispatchers.IO 跨平台定义：

// commonMain 中声明 expect
internal expect val Dispatchers.IO: CoroutineDispatcher

// androidMain / appleMain / ohosArm64Main
internal actual val Dispatchers.IO: CoroutineDispatcher
    get() = Dispatchers.IO  // 使用平台原生 IO 调度器

// jsMain（不支持多线程）
internal actual val Dispatchers.IO: CoroutineDispatcher
    get() = Dispatchers.Default

---

线程安全

线程安全规则

• Kuikly UI 相关类（View、Attr、Event、ObservableProperties、GlobalFunctions、Module 方法、Layout 等）非线程安全，只能在 Kuikly 线程访问

线程安全验证机制

详细用法和示例：见 THREAD_SAFETY.md

override fun willInit() {
    super.willInit()
    Pager.VERIFY_THREAD = true              // 开启线程校验
    Pager.VERIFY_REACTIVE_OBSERVER = true   // 开启 observable 校验
    Pager.verifyFailed { exception ->       // 自定义验证失败处理
        println("线程安全验证失败: ${exception.message}")
        throw exception
    }
}

---

常见陷阱与正确做法

❌ 错误做法	✅ 正确做法
在非 Kuikly 线程直接更新 observable	通过 Dispatchers.Kuikly 或 KuiklyContextScheduler 切回 Kuikly 线程
在非 Kuikly 线程调用 Module 方法	Module 的 acquireModule / toNative 等方法需在 Kuikly 线程调用
在动态化场景使用 kotlinx 协程	使用 Kuikly 内建协程或 Module 机制
在 Kuikly 线程外调用内建协程 API	内建协程 API 只能在 Kuikly 线程调用
忘记处理 Pager 销毁后的回调	KuiklyContextScheduler 回调检查 cancel 参数
在 verifyFailed 回调中操作 UI	验证失败通常发生在非 Kuikly 线程，不能调用 UI API
Compose 中在 IO 线程更新 State	使用 withContext 回到默认调度器后再更新 State

---