Coroutines Introduction

The Problem with Threads

Traditional multithreading uses one thread per concurrent task. Threads are expensive: each thread consumes ~1MB of stack memory, and switching between threads has significant CPU overhead. On Android, you cannot block the main thread (it handles UI), so async work requires callbacks, which leads to callback hell.

// Java callback hell
fetchUser(userId, new Callback<User>() {
    @Override
    public void onSuccess(User user) {
        fetchOrders(user.id, new Callback<List<Order>>() {
            @Override
            public void onSuccess(List<Order> orders) {
                // Nested callbacks become unreadable
            }
        });
    }
});

Coroutines as Lightweight Alternatives

Coroutines are functions that can suspend execution and resume later. They run on threads but are not tied to them. A single thread can run thousands of coroutines because coroutines use ~few hundred bytes of memory each and switching between them is cheap.

// Kotlin coroutines - flat, readable
suspend fun fetchUserData(userId: String) {
    val user = fetchUser(userId)        // Suspends, not blocks
    val orders = fetchOrders(user.id)   // Resumes when ready
    displayOrders(orders)
}

The code reads like sequential blocking code, but it does not block the thread. When a coroutine reaches a suspension point (a suspend function call), it releases the thread so other coroutines can run. When the suspended work completes, the coroutine resumes from where it left off.

How Suspension Works

When you call a suspend function, the compiler transforms it into a state machine. Each suspension point is a state. The coroutine saves its local variables and resumes from the saved state when the suspended operation completes.

// Pseudocode of what the compiler generates
fun fetchUserData(state: Continuation<User>) {
    when (state.label) {
        0 -> {
            state.label = 1
            val user = fetchUser(userId, state)  // Suspends here
            return
        }
        1 -> {
            val user = state.result as User
            state.label = 2
            val orders = fetchOrders(user.id, state)  // Suspends here
            return
        }
        2 -> {
            val orders = state.result as List<Order>
            displayOrders(orders)
        }
    }
}

This transformation is invisible to the programmer. You write sequential code; the compiler handles the state management.

Coroutine Builders

Kotlin provides functions to create coroutines. The most common are launch and async:

import kotlinx.coroutines.*

fun main() = runBlocking {
    // launch: fire-and-forget
    launch {
        delay(1000)
        println("World")
    }
    println("Hello")
}
// Output:
// Hello
// (1 second later)
// World

launch starts a new coroutine and returns a Job. The coroutine runs concurrently with the calling code.

delay vs Thread.sleep

delay is a suspend function that pauses the coroutine without blocking the thread. Thread.sleep blocks the thread entirely:

launch {
    delay(1000)  // Coroutine suspends; thread is free
    println("Done")
}

// Thread.sleep(1000)  // Blocks the thread entirely; avoid in coroutines

async and await

async starts a coroutine that returns a result. Use await() to retrieve it:

fun main() = runBlocking {
    val deferred1 = async { fetchUser(1) }
    val deferred2 = async { fetchUser(2) }

    // Both run concurrently
    val user1 = deferred1.await()
    val user2 = deferred2.await()
    println("Fetched: $user1, $user2")
}

Without async/await, sequential calls would take the sum of both durations. With concurrent execution, they take the max.

runBlocking

runBlocking bridges blocking and non-blocking worlds. It blocks the current thread until all its coroutines complete. Use it only in main() functions and tests, never in library code:

fun main() = runBlocking {
    launch { delay(1000); println("Done") }
}
// main() blocks here until the coroutine completes

Structured Concurrency

Every coroutine must run inside a scope. The scope manages the coroutine lifecycle. When the scope is canceled, all its children are canceled:

fun main() = runBlocking {
    launch {
        delay(1000)
        println("Child 1")
    }
    launch {
        delay(500)
        println("Child 2")
    }
    println("Parent")
}
// Parent
// (500ms) Child 2
// (1000ms) Child 1

If a child coroutine fails, the parent is notified. If the parent is canceled, all children are canceled. This prevents resource leaks.

Exception Handling

Use CoroutineExceptionHandler to handle uncaught exceptions in coroutines:

val handler = CoroutineExceptionHandler { _, exception ->
    println("Caught: $exception")
}

fun main() = runBlocking(handler) {
    launch {
        throw RuntimeException("Boom")
    }
}
// Caught: java.lang.RuntimeException: Boom