suspend: functions that are state machines

The hidden Continuation

1suspend fun loadProfile(id: String): Profile {2    val user = api.user(id)          // suspension point 13    val avatar = api.avatar(user)    // suspension point 24    return Profile(user, avatar)5}

compiles to something shaped roughly like this (simplified):

1fun loadProfile(id: String, cont: Continuation<Profile>): Any? {2    val sm = cont as? LoadProfileSM ?: LoadProfileSM(cont)   // one state object per call3    when (sm.label) {4        0 -> { sm.label = 15               val r = api.user(id, sm); if (r === COROUTINE_SUSPENDED) return r6               sm.user = r as User }7        1 -> { sm.user = sm.result as User }8    }9    // ...the same again for label 2 and avatar...10    return Profile(sm.user, sm.avatar)11}

• An extra Continuation parameter is added: an object with a resumeWith(result) method, which is how the callee gets back to its caller. This is continuation-passing style.
• The body becomes a state machine. Each suspension point gets a label; locals that are needed after it are saved as fields of the state object.
• If a callee really pauses (say, waiting for the network), it returns the special value COROUTINE_SUSPENDED, and every caller up the chain returns it too. The thread is free.
• When the result arrives, someone calls resumeWith, which calls loadProfile again with the same state object; the when jumps to the saved label.

If a callee has the result ready (a cache hit), it just returns it and nothing is suspended, which is why suspend calls are cheap when they don't wait.

Building your own suspension point

At the bottom of every chain, something turns a callback into a suspension. You can do it yourself:

1import kotlinx.coroutines.*2import kotlin.coroutines.resume3 4fun fetchLater(callback: (String) -> Unit) {5    Thread { Thread.sleep(100); callback("data") }.start()6}7 8suspend fun fetch(): String = suspendCancellableCoroutine { cont ->9    fetchLater { value -> cont.resume(value) }10}11 12fun main() = runBlocking {13    println("before on ${Thread.currentThread().name}")14    println(fetch())15    println("after on ${Thread.currentThread().name}")16}

suspendCancellableCoroutine gives you the continuation; the coroutine stays paused until resume is called, from any thread. The dispatcher then decides where the rest runs, which is why after prints on the runBlocking thread again.

What this means in practice

• Stackless. Only the state of suspended functions is kept, a small object per call, not a thread stack. That is why a hundred thousand waiting coroutines fit in memory.
• suspend is not background. Code between suspension points runs on the current thread. A CPU loop or a blocking Thread.sleep in a suspend function blocks whatever thread the coroutine is on.
• Function colour. Suspend functions can be called only from suspend code or a coroutine builder (launch, async, runBlocking), because ordinary code has no continuation to pass.
• Inline lambdas can suspend. A lambda passed to an inline function like forEach is part of the enclosing suspend function, so you can call suspend functions inside it.

Where a coroutine runs, how it is cancelled and who waits for it are not the compiler's job: that's structured concurrency, next.