Kuikly Coroutine and Multithreading Programming

Core Rules

Kuikly Thread Constraint: All Kuikly UI operations (View, Attr, Event, observable, Module methods, setTimeout, etc.) can only be called in the Kuikly thread. Kuikly UI-related classes are not thread-safe.
Must return to Kuikly thread after asynchronous task completion to update UI or access reactive properties.
Dynamic scenarios do not support kotlinx coroutines (JS target platform does not support multithreading), only Module mechanism or Kuikly built-in coroutines can be used.

Comparison of Coroutine Implementation Methods

Feature	Callback (No Coroutine)	Kuikly Built-in Coroutine	kotlinx Coroutine
Dynamic support	✅ Supported	✅ Supported	❌ Not supported
Dependency package size increase	None	None	kotlinx coroutine library
Thread safety	Not involved	Automatically guaranteed	Need to consider

Three Coroutine APIs

1. Kuikly Built-in Coroutines (Recommended for Simple Asynchronous Tasks)

Built into the framework, always executed in the Kuikly thread, no thread switching overhead, supports dynamic scenarios.

API Entries:

```
GlobalScope.launch { ... }
```
— Global scope
```
lifecycleScope.launch { ... }
```
— Bound to Pager lifecycle (Recommended)
```
async { ... }
```
/
```
await()
```
— Concurrent result acquisition

import:

kotlin

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

Note: Kuikly built-in coroutine APIs are not thread-safe themselves and cannot be called outside the Kuikly thread.

2. kotlinx.coroutines Library

Official Kotlin coroutine library, supports multi-thread dispatchers (Dispatchers.Default/IO/Main, etc.), does not support dynamic scenarios.

Integration Method:

gradle

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

3. kuiklyx.coroutines Library (Switch to Kuikly Thread)

Provides

Dispatchers.Kuikly

dispatcher and

KuiklyContextScheduler

callback API, used to switch back to Kuikly thread from non-Kuikly threads.

Integration Method:

gradle

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

Coroutine-style API:

kotlin

// Launch coroutine, execute in Kuikly thread
GlobalScope.launch(Dispatchers.Kuikly[ctx]) { ... }
// Switch to Kuikly thread in coroutine
withContext(Dispatchers.Kuikly[ctx]) { ... }

Callback-style API:

kotlin

KuiklyContextScheduler.runOnKuiklyThread(pagerId) { cancel ->
    if (cancel) return  // Pager has been destroyed
    // Execute in Kuikly thread
}

Scenario Selection Decision Tree

Choose the appropriate asynchronous programming method based on requirements:

Need asynchronous programming?
├── Only need to simplify callbacks, no multi-threading requirements?
│   └── → Option 1: Kuikly Built-in Coroutines
├── Need to execute time-consuming tasks + support dynamic scenarios?
│   └── → Option 2: Module Mechanism (can be used with built-in coroutines)
├── Need multi-threading + no dynamic scenario support required?
│   └── → Option 3: kotlinx coroutines + kuiklyx coroutines
└── Compose DSL page?
    └── → Option 4: LaunchedEffect + withContext

⚠️ Consistency Principle: When selecting a solution, you should also pay attention to the existing asynchronous programming methods in the current project or module, and prioritize consistency to avoid mixing multiple sets of asynchronous solutions in the same module.

Detailed scenario examples and code: See SCENARIOS.md

Coroutines in Compose DSL

Compose DSL pages (inheriting

ComposeContainer

) use the kotlinx coroutine system:

kotlin

@Composable
fun MyContent() {
    var data by remember { mutableStateOf("") }
    LaunchedEffect(Unit) {
        // Default execution in Kuikly thread (via ComposeDispatcher)
        val result = withContext(Dispatchers.IO) {
            // Execute time-consuming task in IO thread
            fetchData()
        }
        // Automatically return to Kuikly thread
        data = result
    }
    Text(text = data)
}

Key Points:

```
LaunchedEffect
```
runs in Kuikly thread by default (scheduled via
```
ComposeDispatcher
```
)
Use
```
withContext(Dispatchers.IO)
```
to switch to IO thread for time-consuming tasks
Automatically return to Kuikly thread after
```
withContext
```
returns
```
viewModelScope
```
is also bound to Kuikly thread, and automatically canceled when ViewModel is destroyed

Cross-platform definition of Dispatchers.IO:

kotlin

// Declare expect in commonMain
internal expect val Dispatchers.IO: CoroutineDispatcher

// androidMain / appleMain / ohosArm64Main
internal actual val Dispatchers.IO: CoroutineDispatcher
    get() = Dispatchers.IO  // Use platform-native IO dispatcher

// jsMain (does not support multi-threading)
internal actual val Dispatchers.IO: CoroutineDispatcher
    get() = Dispatchers.Default

Thread Safety

Thread Safety Rules

Kuikly UI-related classes (View, Attr, Event, ObservableProperties, GlobalFunctions, Module methods, Layout, etc.) are not thread-safe and can only be accessed in the Kuikly thread

Thread Safety Verification Mechanism

Detailed usage and examples: See THREAD_SAFETY.md

kotlin

override fun willInit() {
    super.willInit()
    Pager.VERIFY_THREAD = true              // Enable thread verification
    Pager.VERIFY_REACTIVE_OBSERVER = true   // Enable observable verification
    Pager.verifyFailed { exception ->       // Custom verification failure handling
        println("Thread safety verification failed: ${exception.message}")
        throw exception
    }
}

Common Pitfalls and Correct Practices

❌ Wrong Practice	✅ Correct Practice
Directly update observable in non-Kuikly thread	Switch back to Kuikly thread via `Dispatchers.Kuikly` or `KuiklyContextScheduler`
Call Module methods in non-Kuikly thread	Module methods like acquireModule / toNative must be called in Kuikly thread
Use kotlinx coroutines in dynamic scenarios	Use Kuikly built-in coroutines or Module mechanism
Call built-in coroutine APIs outside Kuikly thread	Built-in coroutine APIs can only be called in Kuikly thread
Forget to handle callbacks after Pager destruction	Check `cancel` parameter in `KuiklyContextScheduler` callback
Operate UI in `verifyFailed` callback	Verification failures usually occur in non-Kuikly threads, cannot call UI APIs
Update State in IO thread in Compose	Update State after returning to default dispatcher via `withContext`

kuikly-coroutines-threading

NPX Install

Tags

SKILL.md Content (Chinese)

Kuikly Coroutine and Multithreading Programming

Core Rules

Comparison of Coroutine Implementation Methods

Three Coroutine APIs

1. Kuikly Built-in Coroutines (Recommended for Simple Asynchronous Tasks)

2. kotlinx.coroutines Library

3. kuiklyx.coroutines Library (Switch to Kuikly Thread)

Scenario Selection Decision Tree

Coroutines in Compose DSL

Thread Safety

Thread Safety Rules

Thread Safety Verification Mechanism

Common Pitfalls and Correct Practices