article banner

How does suspension work in Kotlin coroutines?

This is a chapter from the book Kotlin Coroutines. You can find it on LeanPub or Amazon.

As we mentioned already, coroutines are components that can be suspended and resumed. It might sound like threads, but this is far from that. Threads cannot be suspended, only blocked. When a thread is blocked, it is still alive and consumes resources, it still needs to be managed by the operating system, and it still needs to be scheduled. When a coroutine is suspended, the only thing that remains is an object, that keeps references to local variables and the place where it was suspended. Coroutines are lightweight abstractions that run on top of threads, and they are managed by the coroutine library, not by the operating system.

There is a metaphor I like using to explain the difference between threads and coroutines. Imagine a game. A thread is like this old-school game that you can't save or pause. If you want to take a break for a while, you need to leave the game running. A coroutine is like a modern game that you can save and pause. There are three main benefits of this capability:

  • If you need to take a break from the game, you can save it and turn off the computer. The game will not consume any resources. That is why coroutines do not need to waste resources when they need to wait for something, like a network response.
  • You can play multiple games concurrently. You can save one game, play another, and then resume the first game. Thanks to that, you can run multiple coroutines concurrently on a single thread, what is especially important on Android, where the Main Thread is the most important thread.
  • When you save a game, you can resume it on a different computer. Just imagine that you play games on internet cafes. It is much better resources management if you can take any available computer and resume your game from the point where you left off. This is similar to coroutines, which can be resumed on different threads.

This is an analogy to coroutines. When they are suspended, they return a Continuation. It is like a save in a game: we can use it to continue from the point where we stopped.

Suspending functions

When we transform an application from blocking threads to suspending coroutines, the single most important change is using suspend modifier in front of many functions. Such functions are called suspending functions, and they are the hallmark of Kotlin coroutines. Here is a simple example of a backend application using coroutines. Notice that the only difference between using coroutines and blocking threads is the suspend modifier.

class GithubApi { @GET("orgs/{organization}/repos?per_page=100") suspend fun getOrganizationRepos( @Path("organization") organization: String ): List<Repo> } class GithubConnectorService( private val githubApi: GithubApi ) { suspend fun getKotlinRepos() = githubApi.getOrganizationRepos("kotlin") .map { it.toDomain() } } @Controller class UserController( private val githubConnectorService: GithubConnectorService, ) { @GetMapping("/kotlin/repos") suspend fun findUser(): GithubReposResponseJson = githubConnectorService.getKotlinRepos().toJson() }

So what are suspending functions? Do they start coroutines? No, they don't! Suspending functions are just functions that can suspend a coroutine. That means that a suspending function must be called on a coroutine (because it needs a coroutine to suspend). In practice, suspend functions must be called by other suspending functions or by coroutine builders that start coroutines. Of course, a suspending function can also call regular functions.

Suspending functions are not coroutines, but they require coroutines. That is why a framework like Spring reacts to the suspend modifier in controller mapping functions and calls such functions on a coroutine. On the other hand suspending functions allow suspension, so network libraries like Retrofit reacts to suspend modifier and suspend coroutines (instead of blocking threads) when they need to wait for a network response.

So let's see it in action. For this, we need a coroutine. The simplest way to start it is to use a suspending main function. Such a function is wrapped by the Kotlin compiler and started in a coroutine. However, if we call another suspending function from main, this function will be called on the same coroutine. You can say that suspend functions are synchronized, but the simplest explanations are that they are not coroutines themselves.

import kotlinx.coroutines.* // Suspending function can suspend a coroutine suspend fun a() { // Suspends the coroutine for 1 second delay(1000) println("A") } // Suspending main is started by Kotlin in a coroutine suspend fun main() { println("Before") a() println("After") } // Before // (1 second delay) // A // After

Notice that in JavaScript, if we had a similar code, but using async functions instead of suspending functions, the result would be "Before". "After", 1-second delay and "A". This is because async functions in JavaScript are coroutines, and they always start asynchronous processes. Suspending functions are not coroutines, only functions that can suspend coroutines. Those two concepts should not be confused.

How suspension works?

Let's dive deeper into how suspension works.

This is a simple program that will print "Before" and "After". What will happen if we suspend in between these two prints? For that, we can use the suspendCoroutine function provided by the standard Kotlin library1.

import kotlin.coroutines.* //sampleStart suspend fun main() { println("Before") suspendCoroutine<Unit> { } println("After") } // Before //sampleEnd

If you call the above code, you will not see the "After", and the code will not stop running (as our main function never finished). The coroutine is suspended after "Before". Our game was stopped and never resumed. So, how can we resume? Where is this aforementioned Continuation?

Take a look again at the suspendCoroutine invocation and notice that it ends with a lambda expression ({ }). The function passed as an argument will be invoked before the suspension. This function gets a continuation as an argument.

import kotlin.coroutines.* //sampleStart suspend fun main() { println("Before") suspendCoroutine<Unit> { continuation -> println("Before too") } println("After") } // Before // Before too //sampleEnd

Such a function calling another function in place is nothing new. This is similar to let, apply, or useLines. The suspendCoroutine function is designed in the same way, which makes it possible to use the continuation just before the suspension. After the suspendCoroutine call, it would be too late. So, the lambda expression passed as a parameter to the suspendCoroutine function is invoked just before the suspension. This lambda is used to store this continuation somewhere or to plan whether to resume it.

We could use it to resume immediately:

import kotlin.coroutines.* //sampleStart suspend fun main() { println("Before") suspendCoroutine<Unit> { continuation -> continuation.resume(Unit) } println("After") } // Before // After //sampleEnd

Notice that “After” in the example above is printed because we call resume in suspendCoroutine2.

Since Kotlin 1.3, the definition of Continuation has been changed. Instead of resume and resumeWithException, there is one resumeWith function that expects Result. The resume and resumeWithException functions we are using are extension functions from the standard library that use resumeWith.

inline fun <T> Continuation<T>.resume(value: T): Unit = resumeWith(Result.success(value)) inline fun <T> Continuation<T>.resumeWithException( exception: Throwable ): Unit = resumeWith(Result.failure(exception))

We could also start a different thread that will sleep for a set duration and resume after that time:

import kotlin.concurrent.thread import kotlin.coroutines.* //sampleStart suspend fun main() { println("Before") suspendCoroutine<Unit> { continuation -> thread { println("Suspended") Thread.sleep(1000) continuation.resume(Unit) println("Resumed") } } println("After") } // Before // Suspended // (1 second delay) // After // Resumed //sampleEnd

This is an important observation. Notice that we can make a function that will resume our continuation after a defined period. In such a case, the continuation is captured by the lambda expression, as shown in the code snippet below.

import kotlin.concurrent.thread import kotlin.coroutines.* //sampleStart fun continueAfterSecond(continuation: Continuation<Unit>) { thread { Thread.sleep(1000) continuation.resume(Unit) } } suspend fun main() { println("Before") suspendCoroutine<Unit> { continuation -> continueAfterSecond(continuation) } println("After") } // Before // (1 sec) // After //sampleEnd

Such a mechanism works, but it unnecessarily creates threads only to end them after just a second of inactivity. Threads are not cheap, so why waste them? A better way would be to set up an "alarm clock". In JVM, we can use ScheduledExecutorService for that. We can set it to call some continuation.resume(Unit) after a defined amount of time.

import java.util.concurrent.* import kotlin.coroutines.* //sampleStart private val executor = Executors.newSingleThreadScheduledExecutor { Thread(it, "scheduler").apply { isDaemon = true } } suspend fun main() { println("Before") suspendCoroutine<Unit> { continuation -> executor.schedule({ continuation.resume(Unit) }, 1000, TimeUnit.MILLISECONDS) } println("After") } // Before // (1 second delay) // After //sampleEnd

Suspending for a set amount of time seems like a useful feature. Let's extract it into a function. We will name it delay.

import java.util.concurrent.* import kotlin.coroutines.* //sampleStart private val executor = Executors.newSingleThreadScheduledExecutor { Thread(it, "scheduler").apply { isDaemon = true } } suspend fun delay(timeMillis: Long): Unit = suspendCoroutine { cont -> executor.schedule({ cont.resume(Unit) }, timeMillis, TimeUnit.MILLISECONDS) } suspend fun main() { println("Before") delay(1000) println("After") } // Before // (1 second delay) // After //sampleEnd

The executor still uses a thread, but it is one thread for all coroutines using the delay function. This is much better than blocking one thread every time we need to wait for some time.

This is exactly how delay from the Kotlin Coroutines library used to be implemented. The current implementation is more complicated, mainly so as to support testing, but the essential idea remains the same.

Resuming with a value

One thing that might concern you is why we passed Unit to the resume function. You might also be wondering why we used Unit as a type argument for the suspendCoroutine. The fact that these two are the same is no coincidence. Unit is also returned from the function and is the generic type of the Continuation parameter.

val ret: Unit = suspendCoroutine<Unit> { cont: Continuation<Unit> -> cont.resume(Unit) }

When we call suspendCoroutine, we can specify which type will be returned in its continuation. The same type needs to be used when we call resume.

import kotlin.coroutines.* //sampleStart suspend fun main() { val i: Int = suspendCoroutine<Int> { cont -> cont.resume(42) } println(i) // 42 val str: String = suspendCoroutine<String> { cont -> cont.resume("Some text") } println(str) // Some text val b: Boolean = suspendCoroutine<Boolean> { cont -> cont.resume(true) } println(b) // true } //sampleEnd

This does not fit well with the game analogy. I don't know of any game in which you can put something inside the game when resuming a save3 (unless you cheated and googled how to solve the next challenge). However, it makes perfect sense with coroutines. Often we are suspended because we are waiting for some data, such as a network response from an API. This is a common scenario. Your thread is running business logic until it reaches a point where it needs some data. So, it asks your network library to deliver it. Without coroutines, this thread would then need to sit and wait. This would be a huge waste as threads are expensive, especially if this is an important thread, like the Main Thread on Android. With coroutines, it just suspends and gives the library a continuation with the instruction "Once you’ve got this data, just send it to the resume function". Then the thread can go do other things. Once the data is there, the thread will be used to resume from the point where the coroutine was suspended.

To see this in action, let's see how we might suspend until we receive some data. In the example below, we use a callback function requestUser that is implemented externally.

import kotlin.concurrent.thread import kotlin.coroutines.* data class User(val name: String) fun requestUser(callback: (User) -> Unit) { thread { Thread.sleep(1000) callback.invoke(User("Test")) } } //sampleStart suspend fun main() { println("Before") val user = suspendCoroutine<User> { cont -> requestUser { user -> cont.resume(user) } } println(user) println("After") } // Before // (1 second delay) // User(name=Test) // After //sampleEnd

Calling suspendCoroutine directly is not convenient. We would prefer to have a suspending function instead. We can extract it ourselves.

import kotlin.concurrent.thread import kotlin.coroutines.* data class User(val name: String) fun requestUser(callback: (User) -> Unit) { thread { Thread.sleep(1000) callback.invoke(User("Test")) } } //sampleStart suspend fun requestUser(): User { return suspendCoroutine<User> { cont -> requestUser { user -> cont.resume(user) } } } suspend fun main() { println("Before") val user = requestUser() println(user) println("After") } //sampleEnd

Currently, suspending functions are already supported by many popular libraries, such as Retrofit and Room. This is why we rarely need to use callback functions in suspending functions. However, if you have such a need, I recommend using suspendCancellableCoroutine (instead of suspendCoroutine), which will be explained in the Cancellation chapter.

suspend fun requestUser(): User { return suspendCancellableCoroutine<User> { cont -> requestUser { user -> cont.resume(user) } } }

You might wonder what happens if the API gives us not data but some kind of problem. What if the service is dead or responds with an error? In such a case, we cannot return data; instead, we should throw an exception from the place where the coroutine was suspended. This is where we need to resume with an exception.

Resume with an exception

Every function we call might return some value or throw an exception. The same is true for suspendCoroutine. When resume is called, it returns data passed as an argument. When resumeWithException is called, the exception that is passed as an argument is conceptually thrown from the suspension point.

import kotlin.coroutines.* //sampleStart class MyException : Throwable("Just an exception") suspend fun main() { try { suspendCoroutine<Unit> { cont -> cont.resumeWithException(MyException()) } } catch (e: MyException) { println("Caught!") } } // Caught! //sampleEnd

This mechanism is used for different kinds of problems. For instance, to signal network exceptions.

suspend fun requestUser(): User { return suspendCancellableCoroutine<User> { cont -> requestUser { resp -> if (resp.isSuccessful) { cont.resume(resp.data) } else { val e = ApiException( resp.code, resp.message ) cont.resumeWithException(e) } } } } suspend fun requestNews(): News { return suspendCancellableCoroutine<News> { cont -> requestNews( onSuccess = { news -> cont.resume(news) }, onError = { e -> cont.resumeWithException(e) } ) } }

Suspending a coroutine, not a function

One thing that needs to be emphasized here is that we suspend a coroutine, not a function. Suspending functions are not coroutines, just functions that can suspend a coroutine4. Imagine that we store a function in some variable and try to resume it after the function call.

import kotlin.coroutines.* //sampleStart // Do not do this var continuation: Continuation<Unit>? = null suspend fun suspendAndSetContinuation() { suspendCoroutine<Unit> { cont -> continuation = cont } } suspend fun main() { println("Before") suspendAndSetContinuation() continuation?.resume(Unit) println("After") } // Before //sampleEnd

This makes no sense. It is equivalent to stopping a game and planning to resume it at a later point in the game. resume will never be called. You will only see "Before", and your program will never end unless we resume on another thread or another coroutine. To show this, we can set another coroutine to resume after a second.

import kotlinx.coroutines.* import kotlin.coroutines.* //sampleStart // Do not do this, potential memory leak var continuation: Continuation<Unit>? = null suspend fun suspendAndSetContinuation() { suspendCoroutine<Unit> { cont -> continuation = cont } } suspend fun main() = coroutineScope { println("Before") launch { delay(1000) continuation?.resume(Unit) } suspendAndSetContinuation() println("After") } // Before // (1 second delay) // After //sampleEnd

Summary

I hope now you have a clear picture of how suspension works from the user’s point of view. It is important, and we will see it throughout the book. It is also practical, as now you can take callback functions and make them suspending functions. If you are like me and like to know exactly how things work, you are likely still wondering about how it is implemented. If you're curious about this, it will be covered in the next chapter. If you don't feel you need to know, just skip it. It is not very practical, it just reveals the magic of Kotlin coroutines.

1:

It directly calls suspendCoroutineUninterceptedOrReturn, which is a primitive function, that means a function with intrinsic implementation.

2:

This statement is true, but I need to clarify. You might imagine that here we suspend and immediately resume. This is a good intuition, but the truth is that there is an optimization that prevents a suspension if resuming is immediate.

3:

During a workshop discussion it turned out there is such a game: in Don't Starve Together, when you resume, you can change players. I haven’t played it myself, but this sounds like a nice metaphor for resuming with a value.

4:

Suspending main function is a special case. Kotlin compiler starts it in a coroutine.