Structured concurrency, cancellation, dispatchers

Scopes and Jobs

Every coroutine has a Job in its context. Starting a coroutine inside a scope makes its Job a child of the scope's Job, so you get a tree. coroutineScope { } creates a scope inside a suspend function and suspends until every child is done:

1import kotlinx.coroutines.*2 3suspend fun price(id: Int): Int { delay(100L * id); return id * 10 }4 5suspend fun total(ids: List<Int>): Int = coroutineScope {6    ids.map { id -> async { price(id) } }     // all run concurrently7        .awaitAll()8        .sum()9}10 11fun main() = runBlocking {12    println(total(listOf(1, 2, 3)))            // 60, after about 300 ms, not 60013    val failing = runCatching {14        coroutineScope {15            launch { delay(1_000); println("never printed") }16            launch { delay(50); error("boom") }17        }18    }19    println(failing.exceptionOrNull()?.message)  // boom: the slow sibling was cancelled20}

By default a child that fails with an exception cancels its parent, which cancels all the other children; then the exception surfaces from coroutineScope (or reaches the scope's CoroutineExceptionHandler, for a top-level launch). Where siblings should be independent, use supervisorScope { } or a scope built with SupervisorJob(): a failing child then fails alone. async keeps its exception until await() is called, but in a normal scope the failure still cancels the parent immediately.

Cancellation is cooperative

job.cancel() doesn't stop a thread. It marks the Job cancelled, and the next suspending call that checks (delay, yield, withContext, most kotlinx.coroutines functions) throws CancellationException. Code that never suspends has to check for itself:

1import kotlinx.coroutines.*2 3fun main() = runBlocking {4    val job = launch(Dispatchers.Default) {5        var n = 0L6        try {7            while (true) { ensureActive(); n++ }          // without ensureActive this never stops8        } finally {9            withContext(NonCancellable) { println("cleanup after $n iterations") }10        }11    }12    delay(50)13    job.cancelAndJoin()14    println("cancelled: ${job.isCancelled}")15}

• CancellationException is how cancellation travels, so don't swallow it with a broad catch (e: Exception); rethrow it.
• finally blocks run on cancellation. Suspending inside them needs withContext(NonCancellable), because the coroutine is already cancelled.
• withTimeout(ms) { } cancels its block when time runs out and throws TimeoutCancellationException; withTimeoutOrNull returns null instead.

Dispatchers

The dispatcher in a coroutine's context decides which thread runs it between suspensions:

• Dispatchers.Default: a pool sized to the CPU cores, for computation.
• Dispatchers.IO: an elastic pool (64 threads by default, or more on large machines) for blocking calls. It shares threads with Default.
• Dispatchers.Main: the UI thread on Android, Swing or JavaFX; it needs the platform artifact.
• dispatcher.limitedParallelism(n): a view of a pool that runs at most n coroutines at once, useful to protect a resource.

withContext(Dispatchers.IO) { ... } runs a block on another dispatcher and returns its result to the original one. Avoid GlobalScope and runBlocking in production code paths: the first escapes structured concurrency, the second blocks a thread to wait.