Coroutines

A program that calls a web API, a database and a file system spends most of its time waiting. The classic JVM answer is a thread per task: while one thread waits for the network, another runs. Threads work, but each one is an operating-system object with its own stack (around 1 MB reserved by default), and switching between them is done by the OS. A server with 10,000 open requests cannot comfortably hold 10,000 threads, and an Android app must never block its single UI thread at all.

Kotlin's standard library can start threads directly with thread { }. The program below is correct, but notice how much ceremony even four tasks need: create, start, remember, join. Printing only after every join() is what keeps the output deterministic.

import kotlin.concurrent.thread

fun main() {
    val results = IntArray(4)
    val workers = (0 until 4).map { i ->
        thread(name = "worker-$i") {
            results[i] = (1..1_000).sumOf { it * (i + 1) }
        }
    }
    workers.forEach { it.join() }      // wait for every thread before reading results
    println(results.toList())
    println("total = ${results.sum()}")
}

[500500, 1001000, 1501500, 2002000]
total = 5005000

A coroutine is a computation that can pause in the middle (suspend) without holding a thread, and resume later — possibly on a different thread. While it is paused it is just a small object on the heap holding its local variables. Thousands of coroutines share a handful of threads. The documentation's classic demonstration starts 50,000 of them:

import kotlinx.coroutines.*

fun main() = runBlocking {
    repeat(50_000) {           // 50,000 concurrent coroutines
        launch {
            delay(5_000L)       // suspends: the thread is free while this waits
            print(".")
        }
    }
}

Prints 50,000 dots after about five seconds, using one thread. The same program with thread { Thread.sleep(5000) } would create 50,000 OS threads and is likely to run out of memory.

Marking a function suspend means "this function may pause partway through". Inside, it reads like ordinary sequential code: call, get a result, use it. A suspend function can only be called from another suspend function or from a coroutine, because only those have somewhere to save their state while paused. The entry point can be suspend fun main() — that is plain Kotlin, no library needed.

suspend fun loadUser(id: Int): String {
    println("loading user $id")
    return "Asha"
}

suspend fun loadOrders(user: String): List<String> {
    println("loading orders for $user")
    return listOf("#101", "#102")
}

suspend fun main() {
    val user = loadUser(7)
    val orders = loadOrders(user)
    println("$user has ${orders.size} orders: $orders")
}

loading user 7
loading orders for Asha
Asha has 2 orders: [#101, #102]

suspend fun fetchUser(id: Int): String = "user-$id"

fun main() {
    println(fetchUser(1))
}

Main.kt:4:13: error: suspend function 'suspend fun fetchUser(id: Int): String' can only be called from a coroutine or another suspend function.
    println(fetchUser(1))
            ^^^^^^^^^

suspend fun fetchUser(id: Int): String = "user-$id"

suspend fun main() {
    println(fetchUser(1))
}

What the compiler does with suspend

The compiler rewrites every suspend function to take one extra hidden parameter, a Continuation: an object that holds "the rest of the function" plus its local variables. To suspend, a function stores that continuation somewhere and returns. To resume, someone calls continuation.resume(value), and the function continues from the line after the suspension point. The standard library exposes this directly through suspendCoroutine and startCoroutine, so you can watch it happen with no threads at all:

import kotlin.coroutines.*

var saved: Continuation<String>? = null

suspend fun waitForReply(): String = suspendCoroutine { cont ->
    println("  suspending, continuation saved")
    saved = cont
}

fun main() {
    val body: suspend () -> Unit = {
        println("coroutine: start")
        val reply = waitForReply()
        println("coroutine: resumed with $reply")
    }
    body.startCoroutine(Continuation(EmptyCoroutineContext) { result ->
        println("coroutine: finished ok=${result.isSuccess}")
    })
    println("main: the coroutine is paused, main keeps going")
    saved?.resume("pong")
    println("main: done")
}

coroutine: start
  suspending, continuation saved
main: the coroutine is paused, main keeps going
coroutine: resumed with pong
coroutine: finished ok=true
main: done

The easiest place to watch a coroutine suspend is the standard library's sequence { } builder (you met sequences as lazy collections in Collections). The block is a coroutine. Each yield(value) hands one value to the consumer and suspends the block right there; the block resumes only when the consumer asks for the next value. Two pieces of code take turns on one thread, with no callbacks.

fun main() {
    val tickets = sequence {
        println("  [builder] preparing ticket 1")
        yield("T-1")
        println("  [builder] preparing ticket 2")
        yield("T-2")
        println("  [builder] preparing ticket 3")
        yield("T-3")
        println("  [builder] done")
    }

    for (t in tickets.take(2)) {
        println("consumer got $t")
    }
}

  [builder] preparing ticket 1
consumer got T-1
  [builder] preparing ticket 2
consumer got T-2

Because a suspended builder costs nothing, it can describe an infinite stream: the loop only runs as far as the consumer pulls. yieldAll yields every element of a collection or another sequence. iterator { } is the same builder when you need an Iterator rather than a Sequence.

fun fibonacci(): Sequence<Long> = sequence {
    var a = 0L
    var b = 1L
    while (true) {          // infinite, but only runs as far as someone pulls
        yield(a)
        val next = a + b
        a = b
        b = next
    }
}

fun countdown(from: Int): Iterator<Int> = iterator {
    yieldAll(from downTo 1)
    yield(0)
}

fun main() {
    println(fibonacci().take(10).toList())
    println(fibonacci().first { it > 1000 })
    println(countdown(3).asSequence().toList())
}

[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
1597
[3, 2, 1, 0]

suspend fun pause() {}

val numbers = sequence {
    yield(1)
    pause()
    yield(2)
}

fun main() {
    println(numbers.toList())
}

Main.kt:5:5: error: restricted suspending functions can invoke member or extension suspending functions only on their restricted coroutine scope.
    pause()
    ^^^^^

fun pause() {}   // a regular function is fine

val numbers = sequence {
    yield(1)
    pause()
    yield(2)
}

fun main() {
    println(numbers.toList())
}

fun main() {
    val letters = iterator {
        yield("a")
    }
    println(letters.next())
    println(letters.next())
}

a
Exception in thread "main" java.util.NoSuchElementException
	at kotlin.sequences.SequenceBuilderIterator.nextNotReady(SequenceBuilder.kt:188)
	at kotlin.sequences.SequenceBuilderIterator.next(SequenceBuilder.kt:171)
	at MainKt.main(Main.kt:6)
	at MainKt.main(Main.kt)

fun main() {
    val letters = iterator {
        yield("a")
    }
    while (letters.hasNext()) println(letters.next())
}

kotlinx.coroutines gives you coroutine builders — functions that start a coroutine. runBlocking { } blocks the current thread until everything inside finishes; it bridges normal code to coroutines and belongs in main and tests, not in production request handlers. launch { } starts a fire-and-forget coroutine and returns a Job. async { } starts one that computes a value and returns a Deferred<T>; await() suspends until the value is ready.

import kotlinx.coroutines.*

fun main() = runBlocking {
    launch {
        delay(100L)
        println("World")
    }
    println("Hello")
}

Prints Hello then World. launch returns immediately, so "Hello" prints first; the launched coroutine suspends in delay and resumes 100 ms later. runBlocking does not return until its child finishes.

import kotlinx.coroutines.*
import kotlin.system.measureTimeMillis

suspend fun loadPrice(): Int { delay(300L); return 40 }
suspend fun loadTax(): Int { delay(300L); return 2 }

fun main() = runBlocking {
    val ms = measureTimeMillis {
        val price = async { loadPrice() }   // starts now
        val tax = async { loadTax() }       // also starts now
        println("total = ${price.await() + tax.await()}")
    }
    println("took about $ms ms")
}

Prints total = 42, then a time of roughly 300 ms — not 600 — because both calls wait at the same time. Calling loadPrice() and loadTax() directly, without async, would run them one after the other.

Structured concurrency: every coroutine has a parent

Every coroutine is started inside a CoroutineScope, and the scope is its parent. That gives three guarantees: a parent waits for all its children before it completes; cancelling a parent cancels all its children; and a child that fails cancels its parent and siblings, so an error is never silently lost. Inside a suspend function, coroutineScope { } creates a child scope and returns only when everything launched in it is done.

import kotlinx.coroutines.*

suspend fun loadDashboard() = coroutineScope {
    launch { delay(200L); println("orders loaded") }
    launch { delay(100L); println("profile loaded") }
    println("requests started")
}   // does not return until both launches finish

fun main() = runBlocking {
    loadDashboard()
    println("dashboard ready")
}

Prints requests started, profile loaded, orders loaded, dashboard ready. "dashboard ready" is guaranteed to be last because coroutineScope waits for its children.

A dispatcher decides which thread or threads a coroutine runs on. You choose it when you launch, or switch it for a block with withContext(dispatcher) { }, which suspends the caller and returns the block's result. The rule most teams follow: the function that does blocking or heavy work switches dispatcher itself, so callers can call it from anywhere ("main-safe").

import kotlinx.coroutines.*
import java.io.File

// main-safe: callers do not need to know this blocks
suspend fun readConfig(path: String): String = withContext(Dispatchers.IO) {
    File(path).readText()
}

suspend fun checksum(data: ByteArray): Long = withContext(Dispatchers.Default) {
    data.fold(0L) { acc, b -> acc * 31 + b }
}

No output on its own: these are library functions. Thread names printed from inside coroutines (DefaultDispatcher-worker-1 and so on) vary from run to run, so never rely on them in tests.

Cancellation is cooperative

job.cancel() asks a coroutine to stop. It actually stops at the next suspension point: every suspending function in kotlinx.coroutines (delay, await, withContext, channel operations) checks for cancellation and throws CancellationException. A tight CPU loop with no suspension point never checks, so it keeps running — call ensureActive() or check isActive inside long loops.

import kotlinx.coroutines.*

fun main() = runBlocking {
    val job = launch {
        repeat(1_000) { i ->
            println("job: working $i")
            delay(500L)
        }
    }
    delay(1_300L)
    println("main: cancelling")
    job.cancelAndJoin()        // cancel, then wait until it has really stopped
    println("main: done")
}

Prints job: working 0, job: working 1, job: working 2, main: cancelling, main: done. The job was sitting in delay when the cancel arrived, so it stopped there.

A timeout is cancellation on a timer. withTimeout(ms) { } throws TimeoutCancellationException when time runs out; withTimeoutOrNull(ms) { } returns null instead, which is usually what you want for "try this, fall back otherwise".

import kotlinx.coroutines.*

fun main() = runBlocking {
    val result = withTimeoutOrNull(1_300L) {
        repeat(1_000) { i ->
            println("fetching page $i")
            delay(500L)
        }
        "all pages"
    }
    println("result = $result")
}

Prints fetching page 0, 1 and 2, then result = null: the block was cancelled at 1,300 ms, before it could return "all pages".

Exceptions follow the parent-child tree. When a child fails, it cancels its parent, the parent cancels the other children, and the exception is rethrown where the scope was entered. That means an ordinary try/catch around coroutineScope { } (or around await()) catches a failure from any child inside it.

import kotlinx.coroutines.*

fun main() = runBlocking {
    val total = try {
        coroutineScope {
            val price = async { 40 }
            val tax = async<Int> { throw IllegalStateException("tax service down") }
            price.await() + tax.await()
        }
    } catch (e: IllegalStateException) {
        println("caught: ${e.message}")
        -1
    }
    println("total = $total")
}

Prints caught: tax service down, then total = -1. The failure of one async cancelled the whole coroutineScope, and the exception surfaced at its boundary.

Sometimes one child failing should not cancel the others — loading three independent widgets on a screen, for example. supervisorScope { } (or a SupervisorJob) makes failures one-way: a failed child does not cancel its siblings or parent. An uncaught exception in a launch then goes to a CoroutineExceptionHandler, the last-resort handler for fire-and-forget coroutines.

import kotlinx.coroutines.*

fun main() = runBlocking {
    val handler = CoroutineExceptionHandler { _, e -> println("handled: ${e.message}") }
    supervisorScope {
        launch(handler) { throw RuntimeException("widget A failed") }
        launch { delay(100L); println("widget B loaded") }
    }
    println("screen done")
}

Prints handled: widget A failed, widget B loaded, screen done. With coroutineScope instead of supervisorScope, widget B would have been cancelled and the exception would have crashed main.

A suspend function returns one value. A Flow<T> emits many values over time — search results as the user types, a price that updates, rows streamed from a database. It is the suspending cousin of a sequence: the flow { } builder calls emit(value) instead of yield, and, unlike a sequence, it may call any suspend function in between. A flow is cold: nothing runs until a terminal operator such as collect is called, and each collector gets its own run.

import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*

fun readings(): Flow<Int> = flow {
    for (i in 1..4) {
        delay(100L)          // allowed here, unlike inside sequence { }
        emit(i)
    }
}

fun main() = runBlocking {
    readings()
        .map { it * it }
        .filter { it % 2 == 0 }
        .collect { println("got $it") }
    println("done")
}

Prints got 4, got 16, done. The operators (map, filter, take, debounce, combine…) read like collection functions and run lazily as values arrive.

Two hot flows hold state for UI and events. StateFlow<T> always has a current value and replays it to new collectors — the standard way to expose screen state from a ViewModel. SharedFlow<T> broadcasts events to every current collector. Use flowOn(Dispatchers.IO) to run the upstream part of a flow on another dispatcher.

A Channel is a queue between coroutines: one side calls send, the other receive, and each suspends when it has to wait. Each value is delivered to exactly one receiver, which makes channels a fit for worker pools and producer-consumer pipelines. In application code you will use Flow far more often; channels are the lower-level tool Flow is partly built on.

import kotlinx.coroutines.*
import kotlinx.coroutines.channels.*

fun main() = runBlocking {
    val jobs = Channel<Int>()
    launch {
        for (id in 1..3) jobs.send(id * 10)   // suspends until someone receives
        jobs.close()                          // no more values: ends the for loop below
    }
    for (id in jobs) println("processing $id")
    println("queue drained")
}

Prints processing 10, processing 20, processing 30, queue drained. Forgetting close() leaves the receiving loop suspended forever, and runBlocking never returns.

Android is where most Kotlin developers meet coroutines, and it shows why structured concurrency matters. A ViewModel has viewModelScope, a scope that runs on Dispatchers.Main.immediate and is cancelled automatically when the ViewModel is cleared (the user leaves the screen for good). Work started there cannot outlive the screen or leak. Activities and fragments have lifecycleScope for the same reason.

sealed interface OrdersUiState {
    data object Loading : OrdersUiState
    data class Loaded(val orders: List<Order>) : OrdersUiState
    data class Error(val message: String) : OrdersUiState
}

class OrdersViewModel(private val repo: OrdersRepository) : ViewModel() {
    private val _state = MutableStateFlow<OrdersUiState>(OrdersUiState.Loading)
    val state: StateFlow<OrdersUiState> = _state.asStateFlow()

    init { refresh() }

    fun refresh() {
        viewModelScope.launch {                   // cancelled in onCleared()
            _state.value = OrdersUiState.Loading
            _state.value = try {
                OrdersUiState.Loaded(repo.fetchOrders())   // main-safe suspend fun
            } catch (e: IOException) {
                OrdersUiState.Error("Check your connection")
            }
        }
    }
}

class OrdersRepository(private val api: OrdersApi) {
    suspend fun fetchOrders(): List<Order> = withContext(Dispatchers.IO) {
        api.getOrders()
    }
}

The shape of almost every modern Android screen: a sealed UI state (Module 08), a StateFlow the UI collects, and viewModelScope.launch for the work. Only IOException is caught, so cancellation still propagates.

In Jetpack Compose the screen reads that state with val state by viewModel.state.collectAsStateWithLifecycle(), which stops collecting while the app is in the background. With classic views, collect inside lifecycleScope.launch { repeatOnLifecycle(Lifecycle.State.STARTED) { … } }. Libraries you will use alongside — Retrofit, Room, DataStore, Ktor client — all expose suspend functions or Flows directly.

Coroutine

A computation that can suspend and later resume without blocking a thread.

suspend

A modifier marking a function that may pause; callable only from a coroutine or another suspend function.

Continuation

The compiler-generated object holding the rest of a suspended function and its local variables.

Suspension point

A call where a coroutine may pause, such as yield, delay or await; also where cancellation is checked.

CoroutineScope

The owner of a set of coroutines; it waits for them, cancels them, and receives their failures.

Structured concurrency

The rule that every coroutine has a parent scope, so none can leak or fail silently.

launch / Job

Starts a coroutine that returns no value; the Job lets you cancel or join it.

async / Deferred

Starts a coroutine that computes a value; await() suspends until it is ready.

Dispatcher

Decides which thread(s) a coroutine runs on: Main, IO, Default or Unconfined.

withContext

Runs a block on another dispatcher and returns its result, suspending the caller meanwhile.

Flow

A cold stream of values produced by suspending code and consumed with collect.

StateFlow

A hot flow that always holds a current value; used to expose UI state.

Channel

A suspending queue that hands each value from a sender to exactly one receiver.

viewModelScope

An Android ViewModel's scope, cancelled automatically when the ViewModel is cleared.