Kotlin Coroutines skill for Codex

Done well means: every coroutine runs in a scope that is cancelled with its owner (screen, request, service), no code catches CancellationException without rethrowing, blocking work runs on Dispatchers.IO or a dedicated dispatcher, and tests run on virtual time with no real sleeps.

Before writing code

• Check kotlinx-coroutines-* versions in libs.versions.toml or build files; keep core, android and test artifacts on the same version.
• Identify the owner of each coroutine: viewModelScope, lifecycleScope, a Ktor call/application scope, or a class-owned CoroutineScope(SupervisorJob() + dispatcher) with a close() that cancels it.
• Read AGENTS.md for the project’s dispatcher injection and testing conventions.

Scopes and builders

Need	Use
Run children in parallel, fail together	coroutineScope { } with async/launch
Children independent; one failing must not cancel siblings	supervisorScope { } or a SupervisorJob
Switch thread for a block and return a value	withContext(Dispatchers.IO) { }
UI-bound work in Android	viewModelScope.launch
Collect a Flow in an Activity/Fragment	lifecycleScope.launch { repeatOnLifecycle(Lifecycle.State.STARTED) { flow.collect { } } }
Collect in Compose	flow.collectAsStateWithLifecycle()
App-wide background work that outlives screens	An injected application CoroutineScope, or WorkManager for guaranteed work
Fire-and-forget from anywhere	Never GlobalScope; find the owner

suspend fun loadDashboard(userId: String): Dashboard = coroutineScope {
    val profile = async { api.profile(userId) }
    val orders = async { api.orders(userId) }
    Dashboard(profile.await(), orders.await())   // if one fails, the other is cancelled
}

Dispatchers

• Dispatchers.Main: UI only. Dispatchers.Default: CPU work (parsing, sorting, diffing). Dispatchers.IO: blocking I/O (JDBC, files, legacy SDKs).
• Suspend functions should be main-safe: the function that performs blocking work switches context itself, callers do not.
• Limit concurrency against a constrained resource with Dispatchers.IO.limitedParallelism(4) or a Semaphore, not a custom thread pool.
• Inject dispatchers (constructor parameter) so tests can substitute a test dispatcher.

Cancellation

Cancellation is cooperative and signalled with CancellationException.

// Bad: swallows cancellation, coroutine keeps running after its scope is gone
try { repo.sync() } catch (e: Exception) { log(e) }
val r = runCatching { repo.sync() }          // same problem

// Good
try {
    repo.sync()
} catch (e: CancellationException) {
    throw e
} catch (e: IOException) {
    log(e)
}

• Long CPU loops call ensureActive() (or yield()) each iteration.
• Cleanup that must suspend goes in finally { withContext(NonCancellable) { ... } }.
• withTimeout throws TimeoutCancellationException (a CancellationException), which can be mistaken for parent cancellation; prefer withTimeoutOrNull and handle null.
• Blocking Java calls do not observe cancellation; wrap with runInterruptible(Dispatchers.IO) { } when the call responds to thread interrupts.

Exceptions

• In launch, an uncaught exception cancels the parent scope (unless supervised) and goes to the CoroutineExceptionHandler of the root coroutine.
• In async, the exception is thrown at await() and also cancels the parent in a regular scope. Wrapping await() in try/catch does not stop the parent being cancelled; use supervisorScope when failures should be isolated.
• CoroutineExceptionHandler only works on root coroutines (direct children of the scope); installing it on a nested launch has no effect.

Flow

class SearchViewModel(private val repo: Repo) : ViewModel() {
    private val query = MutableStateFlow("")

    val results: StateFlow<UiState> = query
        .debounce(300)
        .distinctUntilChanged()
        .flatMapLatest { q -> if (q.isBlank()) flowOf(UiState.Empty) else repo.search(q).map(UiState::Data) }
        .catch { emit(UiState.Error(it)) }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), UiState.Empty)

    fun onQuery(q: String) { query.value = q }
}

Need	Operator
Cancel previous work when a new value arrives	flatMapLatest, collectLatest, mapLatest
Move upstream work off the main thread	flowOn(Dispatchers.IO) (affects upstream only)
Combine latest values of several flows	combine
Drop intermediate values under backpressure	conflate()
Share one upstream among many collectors	stateIn (has a current value) / shareIn (events, replay n)
Wrap a callback API	callbackFlow { ...; awaitClose { unregister() } }
Retry with backoff	retryWhen { cause, attempt -> cause is IOException && attempt < 3 && run { delay(1000L shl attempt.toInt()); true } }

• StateFlow conflates and skips equal values (uses equals); emitting the same data class twice does nothing. Use SharedFlow or a Channel for one-off events (navigation, snackbars), or model them as state the UI consumes and clears.
• Update MutableStateFlow atomically with state.update { it.copy(loading = false) }, not state.value = state.value.copy(...) from several coroutines.
• catch only handles upstream exceptions; an exception in collect {} is not caught by it.
• Cold flows restart on every collection; repeated network calls usually mean a missing stateIn/shareIn.

Testing

@OptIn(ExperimentalCoroutinesApi::class)
class SearchViewModelTest {
    private val dispatcher = StandardTestDispatcher()

    @BeforeTest fun setUp() { Dispatchers.setMain(dispatcher) }
    @AfterTest fun tearDown() { Dispatchers.resetMain() }

    @Test fun `debounces queries`() = runTest(dispatcher) {
        val vm = SearchViewModel(FakeRepo())
        vm.results.test {                        // Turbine
            assertEquals(UiState.Empty, awaitItem())
            vm.onQuery("ko"); vm.onQuery("kotlin")
            advanceTimeBy(301)
            assertEquals(UiState.Data(listOf("kotlin")), awaitItem())
            cancelAndIgnoreRemainingEvents()
        }
    }
}

• runTest skips delay using virtual time; never use Thread.sleep or real timeouts.
• Pass the same scheduler to injected dispatchers (StandardTestDispatcher(testScheduler)) so all coroutines share virtual time.
• UnconfinedTestDispatcher runs eagerly; good for simple collectors, but it hides ordering bugs. Default to StandardTestDispatcher and advanceUntilIdle().

Gotchas

• GlobalScope.launch and CoroutineScope(Dispatchers.IO).launch in a function create orphan coroutines that leak and are untestable.
• Collecting a Flow with lifecycleScope.launch without repeatOnLifecycle keeps collecting while the app is in the background.
• runBlocking on the Android main thread or in a Ktor handler blocks a thread the system needs; only use it in main functions and legacy bridges.
• A Mutex from kotlinx.coroutines is not reentrant; locking it again in the same coroutine deadlocks.
• async whose result is never awaited still cancels its parent on failure, but under a supervisor its exception is silently lost; use launch when there is no result.

Verification

./gradlew test                              # or :module:testDebugUnitTest on Android
./gradlew detekt lint                       # if configured

Check that every new launch has an owning scope, every catch (e: Exception) in suspend code rethrows CancellationException, and tests use runTest.

Report template

**Scope fixes:** 3 GlobalScope launches -> injected appScope / viewModelScope
**Cancellation:** 2 runCatching blocks around suspend calls rewritten to rethrow
**Flow:** search results now stateIn(WhileSubscribed(5s)); duplicate network calls removed
**Tests:** 7 runTest + Turbine tests, all virtual time; ./gradlew test green