/kotlin-coroutines

name: kotlin-coroutines
description: Coroutines/Flow in Amethyst: picking IO vs Default, scopes and cancellation (CancellationException, withTimeout), StateFlow/SharedFlow/Channel and stateIn choices, runTest. Use when writing or reviewing async Kotlin code.

Kotlin coroutines in Amethyst

Repo-specific rules only. Textbook coroutines/Flow knowledge is assumed.

Dispatchers

**`Dispatchers.IO` is the default; `Default` only for provably lock-free CPU work.** The full rule, with the reasons and examples (`ParallelEventVerifier`, `PoWMiner.MiningDispatcher`, `BagSweep`, `NostrSignerExternal`), is `commons/ARCHITECTURE.md` › "Choosing a dispatcher". Read it before writing `flowOn`/`withContext`. In `commonMain`, `Dispatchers.IO` needs `import kotlinx.coroutines.IO`.

Relay work: reuse, don't hand-roll

Never write your own `callbackFlow { openReqSubscription(...); awaitClose { ... } }` REQ loop. One-shot and paged fetches, publish-and-confirm, COUNT and negentropy sync already exist as `INostrClient` extensions in `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/client/accessories/` (catalog: its `README.md`; flow helpers in `../reqs/`). Their timeouts are idle windows (`idleTimeoutMs`), not deadlines. For loads tied to a composable's lifetime, see the `relay-client` skill.

`callbackFlow` is still the right bridge for platform callbacks; copy `amethyst/.../service/connectivity/ConnectivityFlow.kt` (initial emit, `awaitClose` unregister, `distinctUntilChanged().debounce(200).flowOn(Dispatchers.IO)`).

Scopes

• **Stored scopes are fine for lifecycle owners.** `Account` takes

`scope: CoroutineScope`; Android services build `CoroutineScope(Dispatchers.IO + SupervisorJob() + exceptionHandler)` and `cancel()` it in `onDestroy` (`PushNotificationReceiverService`). Hundreds of such fields are legitimate; don't flag them on sight.

• **New non-owner classes** (helpers, repositories, parsers) expose `suspend` APIs

and do not `launch` from `init`. Let the owner pick the scope.

• **No `runBlocking`** outside tests, previews and the CLI entry point. No

`GlobalScope`.

Cancellation and timeouts

• A broad `catch (e: Exception)` / `runCatching` around a suspend call must rethrow

`CancellationException`.

• **`TimeoutCancellationException` IS a `CancellationException`.** A blanket

rethrow turns one slow RPC into a dead loop: rethrowing it ended the cordn sync loop for the whole session. Either catch the timeout narrowly, right at the `withTimeout`, or rethrow only when the coroutine itself is cancelled (`if (!isActive) throw e`). See cordn-kmp's `cordn/client/CordnSyncLoop.kt` for both.

State and events

• `MutableStateFlow.update { }` instead of `_s.value = _s.value.copy(...)`. Keep the

block pure and cheap (it can retry); build expensive values before it.

• `stateIn`/`shareIn` belong on a `val`, never inside a function (each call starts a

new sharing coroutine).

• `WhileSubscribed` stops upstream with no collectors, so `.value` goes stale or

stays at the initial value. If code reads `.value` synchronously, use `Eagerly`.

• `stateFlow.map { }` is a plain `Flow`; terminate with `stateIn` if consumers

need `.value`.

• One-shot events for a single consumer (navigation, a toast): a

`Channel(Channel.BUFFERED).receiveAsFlow()`, not a no-replay `MutableSharedFlow` that drops emissions with no collector. A `Channel` delivers each item to ONE collector; if every observer must see it, model it as state.

• Don't invent fake domain sentinels as the initial value; use `null` or a sealed

loading state.

Tests

• `runTest` from `kotlinx-coroutines-test`, not `runBlocking`. Turbine is not a

dependency; collect into a list in `backgroundScope.launch { flow.collect { } }` and drive time with `advanceUntilIdle()`, `runCurrent()`, `advanceTimeBy()`.

• Inject the dispatcher/scope under test (`StandardTestDispatcher(testScheduler)`

or `UnconfinedTestDispatcher`) so delays run on virtual time.

• Never wait on wall-clock time (`delay(350)` racing a 200 ms timeout flaked on

loaded CI). Wait on the test scheduler or a condition.