Whenever we need to write asynchronous code we tend to use callbacks which allow us to trigger an action and, instead of waiting for it to finish, get notified through the callback for the action’s completion. Coroutines change that and help us write asynchronous code but in a sequential way.

This means that instead of writing code like this:

	fun main() {
	downloadTasks(
	object : DownloadCallback {
	override fun onDownloaded(tasks: List<Task>) {
	printTasks(tasks)
	}
	}
	)
	}
	interface DownloadCallback {
	fun onDownloaded(tasks: List<Task>)
	}
	private fun downloadTasks(callback: DownloadCallback) {
	println("Downloading…")
	// code that makes a network call and returns the list of tasks
	callback.onDownloaded(listOf(Task(1), Task(2), Task(3)))
	}
	private fun printTasks(tasks: List<Task>) {
	tasks.forEach { task -> println(task.id) }
	}

view raw suspend_coroutine__callbacks.kt hosted with ❤ by GitHub

we can write it like this:

	fun main(): Unit = runBlocking {
	launch {
	val tasks = downloadTasks()
	printTasks(tasks)
	}
	}
	private suspend fun downloadTasks() {
	println("Downloading…")
	// code that makes a network call and returns the list of tasks
	return listOf(Task(1), Task(2), Task(3))
	}
	private fun printTasks(tasks: List<Task>) {
	tasks.forEach { task -> println(task.id) }
	}

view raw suspend_coroutine__coroutines.kt hosted with ❤ by GitHub

But what do we do when there is no easy way to remove callbacks from existing code or when we use a third party library that is not coroutines ready? This is where suspendCoroutine comes to save the day.

suspendCoroutine

suspendCoroutine is a function that does exactly what is says. It suspends the coroutine that it was called from and provides a way to resume it.

Lets have an example. The code here:

	fun main(): Unit = runBlocking {
	launch {
	print("1 ")
	print("2 ")
	print("3 ")
	print("4 ")
	println("Done!")
	}
	}

view raw suspend_coroutine__example_init.kt hosted with ❤ by GitHub

simply prints 1 2 3 4 Done!. If we change it to:

	fun main(): Unit = runBlocking {
	launch {
	print("1 ")
	print("2 ")
	print("3 ")
	suspendCoroutine<Unit> { }
	print("4 ")
	println("Done!")
	}
	}

view raw suspend_coroutine__example_suspend.kt hosted with ❤ by GitHub

it will print 1 2 3 and then it will just wait. We suspended the coroutine but we did not resume it. To do so we will use the continuation instance that suspendCoroutine provides:

	fun main(): Unit = runBlocking {
	launch {
	print("1 ")
	print("2 ")
	print("3 ")
	suspendCoroutine<Unit> { continuation ->
	print("… ")
	continuation.resume(Unit)
	}
	print("4 ")
	println("Done!")
	}
	}

view raw suspend_coroutine__example_resume.kt hosted with ❤ by GitHub

now it prints 1 2 3 … 4 Done!. The coroutine printed the first three numbers, got suspended, while being suspended another block of code got executed and printed the dots and then resumed the coroutine allowing it to print the final number and done.

Continuation adapter

Back to our first example. Lets say that downloadTasks cannot be changed. We still need to call it and provide a callback for its results.

What we need to do is to suspend the coroutine, call downloadTasks to.. well.. download the tasks and provide a callback that upon completion it will resume the coroutine with the tasks at hand.

To achieve that we first need to create an adapter that will connect the callback with a continuation:

	private class ContinuationAdapter(
	private val continuation: Continuation<List<Task>>
	) : DownloadCallback {
	override fun onDownloaded(tasks: List<Task>) {
	continuation.resume(tasks)
	}
	}

view raw suspend_coroutine__continuation.kt hosted with ❤ by GitHub

and then call suspendCoroutine:

	fun main(): Unit = runBlocking {
	launch {
	val tasks = suspendCoroutine<List<Task>> { continuation -> downloadTasks(ContinuationAdapter(continuation)) }
	printTasks(tasks)
	}
	}

view raw suspend_coroutine__direct_suspendcoroutine.kt hosted with ❤ by GitHub

That’s it. The adapter resumes the coroutine by providing the tasks that are then returned to the suspension point.

One more thing

Along side suspendCoroutine there is also suspendCancellableCoroutine which provides a cancellable continuation. That means that in addition of resuming we can also execute code upon cancellation:

	fun main(): Unit = runBlocking {
	val job = launch(Dispatchers.IO) {
	val tasks = downloadAllTasks()
	printTasks(tasks)
	}
	delay(100)
	job.cancel()
	}
	private suspend fun downloadAllTasks(): List<Task> {
	return suspendCancellableCoroutine { continuation ->
	continuation.invokeOnCancellation { print("Cancelled…") }
	downloadTasks(ContinuationAdapter(continuation))
	}
	}
	private class ContinuationAdapter(
	private val continuation: Continuation<List<Task>>
	) : DownloadCallback {
	override fun onDownloaded(tasks: List<Task>) {
	continuation.resume(tasks)
	}
	}
	interface DownloadCallback {
	fun onDownloaded(tasks: List<Task>)
	}
	private fun downloadTasks(callback: DownloadCallback) {
	println("Downloading…")
	sleep(150) // simulate network latency
	val tasks = listOf(Task(1), Task(2), Task(3))
	callback.onDownloaded(tasks)
	}
	private fun printTasks(tasks: List<Task>) {
	tasks.forEach { task -> println(task.id) }
	}

view raw suspend_coroutine__suspendcoroutine.kt hosted with ❤ by GitHub

this will print Downloading… and then Cancelled…

Ever since Kotlin introduced coroutines there has been a plethora of posts that showcased their usage in networking or multi threading scenarios. Inevitably many developers when asked what a coroutine is their first answer was “a lightweight thread” or “a way to write clean asynchronous code”. Unfortunately this is not the definition of a coroutine but rather a couple of things that a coroutine can help us with.

Routine (aka Subroutine)

So what is a coroutine? To answer that we must first understand what a routine is.

A routine is nothing more than the common function that we all use every day. Its main characteristic is that its execution must come to a completion before returning to the caller. It does not hold any state and calling it multiple times is like calling it for the first time.

An example:

	// a routine:
	fun saveUserTasks(userId: Int) {
	val user = loadUser(userId)
	println("user loaded")
	val tasks = loadTasks(user)
	println("tasks loaded")
	saveTasks(tasks)
	}
	// when called multiple times:
	fun main() {
	println("Call #1:")
	saveUserTasks(7)
	println("Call #2:")
	saveUserTasks(7)
	println("Call #3:")
	saveUserTasks(7)
	println("done!")
	}
	// its like calling it for the first time:
	/*
	Call #1:
	loading a user…
	user loaded
	loading tasks for provided user…
	tasks loaded
	saving provided tasks…
	Call #2:
	loading a user…
	user loaded
	loading tasks for provided user…
	tasks loaded
	saving provided tasks…
	Call #3:
	loading a user…
	user loaded
	loading tasks for provided user…
	tasks loaded
	saving provided tasks…
	done!
	*/

view raw lets_build_a_coroutine__subroutine.kt hosted with ❤ by GitHub

Coroutine

On the other hand a coroutine (a concept that is way older than Kotlin) is a function that can hold its current state allowing us to pause and resume its execution at certain suspension points. This can be of great help when we need to write concurrent code, meaning, when we need to run two tasks at the same time by executing small parts of those tasks one at a time.

For example, if we have task A broken in two parts (A1, A2) and task B broken in two parts as well (B1, B2), we can write code that executes first A1, then B1, then A2 and finally B2.

Building a coroutine

Our goal is to convert the above routine into a coroutine and to do so we need to have a blueprint:

	fun saveUserTasks(userId: Int) {
	val user = loadUser(userId)
	println("user loaded")
	// save loaded user
	// pause execution
	// resume execution
	// restore saved user
	val tasks = loadTasks(user)
	println("tasks loaded")
	// save loaded tasks
	// pause execution
	// resume execution
	// restore saved tasks
	saveTasks(tasks)
	}

view raw lets_build_a_coroutine__goald.kt hosted with ❤ by GitHub

So, step #1 is to separate the states into blocks of code and to do that we are going to use the when statement:

	fun saveUserTasks(userId: Int, state: Int) {
	when (state) {
	0 -> {
	val user = loadUser(userId)
	println("user loaded")
	// save loaded user
	// pause execution
	}
	1 -> {
	// resume execution
	// restore saved user
	val tasks = loadTasks(user) // ERROR: unknown user
	println("tasks loaded")
	// save loaded tasks
	// pause execution
	}
	2 -> {
	// resume execution
	// restore saved tasks
	saveTasks(tasks) // ERROR: unknown tasks
	}
	}
	}

view raw lets_build_a_coroutine__state_blocks.kt hosted with ❤ by GitHub

the problem here is that the code does not compile since the states do not communicate and are missing important information.

To fix it we are moving to step #2 where the state parameter will be used as a vessel to pass data from one state to the other:

	class State(
	var label: Int = 0,
	var result: Any? = null
	)
	fun saveUserTasks(userId: Int, state: State) {
	when (state.label) {
	0 -> {
	val user = loadUser(userId)
	println("user loaded")
	state.result = user
	// pause execution
	}
	1 -> {
	// resume execution
	val user = state.result as User
	val tasks = loadTasks(user)
	println("tasks loaded")
	state.result = tasks
	// pause execution
	}
	2 -> {
	// resume execution
	val tasks = state.result as List<Task>
	saveTasks(tasks)
	}
	}
	}

view raw lets_build_a_coroutine__state_object.kt hosted with ❤ by GitHub

the code now has distinct states that share data but it cannot resume correctly since there is no way to move from one state to the other.

Step #3 addresses that by updating the state’s label allowing the function to resume from where it was paused:

	fun saveUserTasks(userId: Int, state: State) {
	when (state.label) {
	0 -> {
	val user = loadUser(userId)
	println("user loaded")
	state.result = user
	state.label = 1
	return
	}
	1 -> {
	// resume execution
	val user = state.result as User
	val tasks = loadTasks(user)
	println("tasks loaded")
	state.result = tasks
	state.label = 2
	return
	}
	2 -> {
	// resume execution
	val tasks = state.result as List<Task>
	saveTasks(tasks)
	}
	}
	}

view raw lets_build_a_coroutine__state_update.kt hosted with ❤ by GitHub

and that’s it. saveUserTasks is now a coroutine where every call executes a small part of the function allowing us to pause and resume the task:

	fun main() {
	val state = State()
	println("Call #1:")
	saveUserTasks(7, state)
	println("Call #2:")
	saveUserTasks(7, state)
	println("Call #3:")
	saveUserTasks(7, state)
	println("done!")
	}
	// results in:
	/*
	Call #1:
	loading a user…
	user loaded
	Call #2:
	loading tasks for provided user…
	tasks loaded
	Call #3:
	saving provided tasks…
	done!
	*/

view raw lets_build_a_coroutine__state_exec.kt hosted with ❤ by GitHub

Concurrency

We did manage to convert a routine to a coroutine but the example did not show the power of using coroutines which is concurrency. Lets change that.

To make things a little bit easier we are going to package a few common functionalities together

	abstract class Coroutine {
	var isFinished: Boolean = false
	private set
	protected val state: State by lazy { State() }
	protected fun resumeWith(result: Any) {
	state.label++
	state.result = result
	}
	protected fun <T> restore(): T {
	return state.result as T
	}
	protected fun finish() {
	state.label++
	isFinished = true
	}
	protected class State(
	var label: Int = 0,
	var result: Any? = null
	)
	}

view raw lets_build_a_coroutine__coroutine.kt hosted with ❤ by GitHub

which allows us to create these

	class SaveUserTasks : Coroutine() {
	operator fun invoke(userId: Int) {
	saveUserTasks(userId, state)
	}
	private fun saveUserTasks(userId: Int, state: State) {
	when (state.label) {
	0 -> {
	val user = loadUser(userId)
	println("user loaded")
	resumeWith(user)
	return
	}
	1 -> {
	val user = restore<User>()
	val tasks = loadTasks(user)
	println("tasks loaded")
	resumeWith(tasks)
	return
	}
	2 -> {
	val tasks = restore<List<Task>>()
	saveTasks(tasks)
	finish()
	}
	}
	}
	}
	class ApplyDownloadedSettings : Coroutine() {
	operator fun invoke() {
	applyDownloadedSettings(state)
	}
	private fun applyDownloadedSettings(state: State) {
	when (state.label) {
	0 -> {
	val settings = downloadSettings()
	println("settings downloaded")
	resumeWith(settings)
	return
	}
	1 -> {
	val settings = restore<Settings>()
	applySettings(settings)
	println("setting applied")
	finish()
	}
	}
	}
	}

view raw lets_build_a_coroutine__coroutine_implementations.kt hosted with ❤ by GitHub

This way we can call the two functions as such:

	fun main() {
	val saveUserTasks = SaveUserTasks()
	val applyDownloadedSettings = ApplyDownloadedSettings()
	while (!saveUserTasks.isFinished || !applyDownloadedSettings.isFinished) {
	saveUserTasks(7)
	applyDownloadedSettings()
	}
	println("done!")
	}
	/*
	loading a user…
	user loaded
	downloading settings…
	settings downloaded
	loading tasks for provided user…
	tasks loaded
	applying settings…
	setting applied
	saving provided tasks…
	done!
	/*

view raw lets_build_a_coroutine__final_exec.kt hosted with ❤ by GitHub

As you can see the two functions are being executed concurrently. First we load the user, then we download the settings, then we load the user’s task and so on and so forth!

Further reading

My goal with this post was to give you a better understanding on what a coroutine is and I did it by using the concept of a finite state machine. The same concept that Kotlin’s implementation of coroutines uses.

For digging in the actual implementation of coroutines I suggest you take a look at a couple of great posts that helped me a lot in grasping the concept:

• The suspend modifier — under the hood
• Coroutines: Suspending State Machines
• Kotlin Continuations