Kotlin
Coroutines
Explained

Suspend Functions

A suspend function can pause execution without blocking the thread it runs on. The thread is released while waiting, then the function resumes — possibly on a different thread.

// what YOU write
suspend fun loadProfile(): Profile {
    val user  = fetchUser()    // ← suspension point
    val posts = fetchPosts()   // ← suspension point
    return Profile(user, posts)
}

Can a suspend function have NO suspension points?

Yes. It's valid Kotlin — it just never actually suspends. The compiler will warn you with "Redundant 'suspend' modifier". This is common when overriding an interface that declares suspend.

Identifying Suspension Points

suspend fun loadData() {
    println("start")        // regular fun  → NOT a suspension point
    val a = fetchUser()    // suspend fun  → SUSPENSION POINT
    println("got user")     // regular fun  → NOT a suspension point
    val b = fetchPosts()   // suspend fun  → SUSPENSION POINT
    println("done")         // regular fun  → NOT a suspension point
}

Built-in suspension points

The blocking trap — regular fun that takes time

If a regular (non-suspend) function takes time, the coroutine cannot suspend there. It holds the thread hostage.

// BAD — blocks the thread, defeats coroutines
suspend fun loadData() {
    val result = heavyCompute()   // regular fun — thread stuck!
}

// GOOD — offload to another thread
suspend fun loadData() {
    val result = withContext(Dispatchers.Default) {
        heavyCompute()   // same regular fun, but thread is released
    }
}

The State Machine

The Kotlin compiler transforms every suspend function into a state machine using Continuation Passing Style (CPS). Each suspension point becomes a numbered case label.

// What YOU write:
suspend fun loadData() {
    val a = fetchUser()    // suspension point #0
    val b = fetchPosts()   // suspension point #1
}

// What the COMPILER generates:
Object loadData(Continuation cont) {
    switch(cont.label) {
        case 0:
            cont.label = 1
            result = fetchUser(cont)
            if (result == SUSPENDED) return SUSPENDED  // pause
        case 1:
            cont.label = 2
            result = fetchPosts(cont)
            if (result == SUSPENDED) return SUSPENDED  // pause
        case 2:
            return  // done
    }
}

How the compiler decides

The compiler does not "decide" suspension points — you implicitly declare them. Every call to a suspend fun tells the compiler: cut here. Regular function calls are never cut.

The Continuation

A Continuation is the bookmark — it captures everything needed to resume a suspended coroutine. The compiler adds it as a hidden parameter to every suspend function.

// The actual Kotlin stdlib interface:
interface Continuation<in T> {
    val context: CoroutineContext          // which thread to resume on
    fun resumeWith(result: Result<T>)      // call this to wake the coroutine
}

// What YOU write:              What COMPILER generates:
suspend fun fetchUser(): User  →  fun fetchUser(cont: Continuation<User>): Any

The chain of continuations

Why regular functions can't pass a Continuation

A regular function was never transformed into a state machine, so it has no Continuation object. When you call a suspend function, the compiler looks for a Continuation to pass — there isn't one — compiler error.

Coroutine Builders

Builders are regular functions that create a root Continuation and start a coroutine. They bridge the gap between the regular world and the coroutine world.

Job & Cancellation

Job is the lifecycle handle to a coroutine. Without it you'd have no way to control, cancel, or wait for a coroutine.

cancel() is just a signal

job.cancel()
// coroutine might STILL be running here!
// cancel() sets isActive=false and throws CancellationException
// at the NEXT suspension point — not immediately

job.cancelAndJoin()   // ← this is cancel() + join() combined
proceedWithNextTask()  // guaranteed safe now

The blind spot — after the last suspension point

suspend fun load() {
    val result = api.fetch()   // suspension point — cancellation checked here

    // cancel() arrived AFTER network responded?
    // coroutine is past the last suspension point
    // it will run to completion unless you check manually:

    ensureActive()            // ← throws CancellationException if cancelled
    _state.value = result      // ← now safe
}

When does cancelAndJoin() matter?

Job lifecycle

Coroutine Context

CoroutineContext is a bag of configuration that every coroutine carries. It defines how and where the coroutine runs.

// combine with +
val ctx = Dispatchers.IO +
           CoroutineName("sync") +
           CoroutineExceptionHandler { _, e -> log(e) }

scope.launch(ctx) { ... }

// adding same type replaces the old one
Dispatchers.IO + Dispatchers.Main   // only Main survives

How context flows to children

scope.launch(Dispatchers.IO) {
    // context: IO + its own Job (child of scope's Job)

    launch {
        // inherits IO + its OWN new Job (linked to parent)
    }

    launch(Dispatchers.Main) {
        // overrides dispatcher: Main + its OWN new Job
    }
}

Coroutine Scope

CoroutineScope is a wrapper around a CoroutineContext. It's the container that owns coroutines — when the scope is cancelled, all its coroutines are cancelled.

// this is literally all CoroutineScope is:
interface CoroutineScope {
    val coroutineContext: CoroutineContext
}

CoroutineScope vs coroutineScope

// CoroutineScope — you build it, you cancel it
class UserRepository {
    private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())

    fun fetch() = scope.launch { api.getUser() }
    fun destroy() = scope.cancel()   // must call this!
}

// coroutineScope — parallel work, waits for all
suspend fun loadDashboard(): Dashboard = coroutineScope {
    val user  = async { fetchUser() }
    val posts = async { fetchPosts() }
    Dashboard(user.await(), posts.await())
}

Job vs SupervisorJob

Built-in scopes in Android

Wrapping Callbacks

Old callback-based APIs can be wrapped into suspend functions using suspendCancellableCoroutine. The caller sees a clean suspend function — no callbacks visible.

suspend fun fetchUser(id: String): User =
    suspendCancellableCoroutine { cont ->

        val call = api.fetchUser(id,
            onSuccess = { user ->
                cont.resume(user)                  // success
            },
            onError = { e ->
                cont.resumeWithException(e)          // failure
            }
        )

        cont.invokeOnCancellation {
            call.cancel()                          // cleanup on cancel
        }
    }

Three scenarios

Key safety guarantee

Real example — OkHttp

suspend fun get(url: String): String =
    suspendCancellableCoroutine { cont ->
        val call = client.newCall(Request.Builder().url(url).build())

        call.enqueue(object : Callback {
            override fun onResponse(call: Call, response: Response) =
                cont.resume(response.body!!.string())
            override fun onFailure(call: Call, e: IOException) =
                cont.resumeWithException(e)
        })

        cont.invokeOnCancellation { call.cancel() }
    }

The Mental Model