Everything you need to know about kotlin coroutines
Tags: kotlin, coroutines, concurrency, java
Published: 2019-10-30 10:24:26


# Everything you need to know about kotlin coroutines

My agenda for this blog post is to get yourself familiar with different terminologies of coroutines and answer the following questions:

* Difference between ***Job*** and ***Deferred***, ***launch*** and ***async***

* Which ***coroutine builder*** you should use?

* What happens when a ***exception*** is thrown in coroutine?

* At a very high level, how ***structured concurrency*** is achieved?

* A thread-safe shared mutable state with a ***single-threaded dispatcher***

* ***IO*** and ***CPU*** bound operations with coroutines

To understand how coroutines work and use them effectively in real-world applications, you need to first understand its core concepts.

We are going to cover the following topics in the rest of the write-up:

* [**Coroutine Scope Builders**](#coroutine-scope-builders) (MainScope, CoroutineScope, coroutineScope, GlobalScope, etc.)

* [**CoroutineContext**](#coroutinecontext) (Job, Deferred, etc.)

* [**Coroutine Builders**](#coroutine-builders) (launch, async, withContext, runBlocking, etc.)

* [**Structured concurrency**](#structured-concurrency)

* [**Suspend**](#suspend)

* [**Continuation**](#continuation)

## Introduction

[Coroutines](https://en.wikipedia.org/wiki/Coroutine) are light-weight threads and the construction of coroutine is very cheap. They do not directly map to native os threads, because of that they are very faster to create and destroy compared to threads. There is no additional overhead of switching context between threads. Practically you can have thousands of or even tens of thousands of coroutines. There might be only one thread having thousands of coroutines.

The two most important building blocks to create/start/run new coroutines are **coroutine scope** and **coroutine builders**.

Coroutine scope consists of all the machinery required to run coroutine, for example, it knows where (on which thread) to run coroutine and coroutine builders are used to create a new coroutine.

If I have to give an analogy with threads, coroutine scope can be seen as Java’s [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html) and coroutine builders are factories to create [Runnable ](https://docs.oracle.com/javase/8/docs/api/java/lang/Runnable.html)instances.
> *CoroutineScope is more than just [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html)!*

To demonstrate that coroutines are ***light-weight***, let’s look at the following examples where we create 100 thousand coroutines vs 100 thousand threads and print(".") in each one of them.

***100_000 coroutines:***

{% kotlin https://pl.kotl.in/OBD3iKVmpH?from=4&to=11 %}
> The above application does not crash and prints 100_000 dots.

***Note:*** Do not worry about launch and runBlocking used in the above example, this is explained in detail in later sections of this article. Just know that runBlocking creates coroutine scope which can be seen as setting up an environment to execute coroutine and launch is a coroutine builder that spawns new coroutine, schedules it for execution in the environment.

***100_000 threads:***

{% kotlin https://pl.kotl.in/L6R0sT68kK?from=3&to=10 %}
> Above application crashes with java.lang.OutOfMemoryError: unable to create new native thread

## Coroutine Scope Builders

[CoroutineScope](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/) is an interface that has a single abstract property called coroutineContext.

```kotlin
    public interface CoroutineScope {
        public val coroutineContext: CoroutineContext
    }
```

CoroutineScope is nothing but a CoroutineContext, the only difference is in their intended use. Roman Elizarov explains this in detail in following blog post
{% medium https://medium.com/@elizarov/coroutine-context-and-scope-c8b255d59055 %}

The important thing you need to know is that whenever a new coroutine scope is created, a new job gets created and associated with it.

Every coroutine created using this scope becomes the child of this job. This is how a parent-child relationship gets created between coroutines. If any of the coroutines throws an unhandled exception, it’s parent job gets canceled which ultimately cancels all its children. This is called ***structured concurrency***, I highly recommend [this](https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/) blog to know more on this topic.

### How to create CoroutineScope

[**MainScope**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-main-scope.html)

This is useful for UI components, it creates [SupervisorJob](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-supervisor-job.html) and all the coroutines created with this scope runs on the [Main](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-main-scope.html) thread. Because it creates SupervisorJob, failure of any coroutine does not trigger the termination of others unlike I have mentioned previously in the context of structured concurrency. Failures of child coroutines can be handled using [CoroutineExceptionHandler](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-exception-handler/).

```kotlin
    public fun MainScope(): CoroutineScope = ContextScope(SupervisorJob() + Dispatchers.Main)
```

**Note**: To work with the [Main](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-main-scope.html) dispatcher, following additional platform specific runtime dependencies required to be added to your project:

* kotlinx-coroutines-android — for Android Main thread dispatcher

* kotlinx-coroutines-javafx — for JavaFx Application thread dispatcher

* kotlinx-coroutines-swing — for Swing EDT dispatcher

[**CoroutineScope(ctx)**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope.html)

This creates a coroutine scope from provided coroutine context and makes sure that a job is associated with this scope.

```kotlin
    public fun CoroutineScope(context: CoroutineContext): CoroutineScope =
        ContextScope(if (context[Job] != null) context else context + Job())
```

The following example demonstrates creating a new CorotuineScope without any Job passed externally but internally it creates one. It also shows a glimpse of structured concurrency. Child coroutine (C*hild-A*) throws exceptions which result in the cancellation of another coroutine (*Child-B*).

{% kotlin https://pl.kotl.in/WM_y5uczk?from=7&to=25 %}

[**coroutineScope(block)**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html)

This is a suspending function that creates a coroutine scope, new Job and calls provided suspending block with this scope. This inherits coroutine scope from the outer scope and overrides the context’s Job. Note that, this is a suspending function and will return when given block and all its child coroutines are completed even though you do not [join](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/join.html)/[await](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/await.html) on coroutines.

```kotlin
    public suspend fun <R> coroutineScope(block: suspend CoroutineScope.() -> R): R
```

Let’s say you have some asynchronous suspending tasks and you want to wait for results from all of them and then perform some action. In this scenario, you can use coroutineScope, fire all the tasks parallelly and then wait for their results.

{% kotlin https://pl.kotl.in/IYOm47v4o?from=7&to=28 %}

[**GlobalScope**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-global-scope/)

This is a singleton and not associated with any Job. This launches top-level coroutines and highly discouraged to use because if you launch coroutines in the global scope, you lose all the benefits you get from structured concurrency.

```kotlin
    public object GlobalScope : CoroutineScope {
        override val coroutineContext: CoroutineContext get() = EmptyCoroutineContext
    }
```

Following blog post explains more reasons to why you should avoid using GlobalScope
{% medium https://medium.com/@elizarov/the-reason-to-avoid-globalscope-835337445abc %}

The following example demonstrates that there is no Job associated with GlobalScope and the exception is thrown in one of the coroutines launched using GlobalScope does not affect other coroutines hence we loose structured concurrency.

{% kotlin https://pl.kotl.in/4NP6osGdy?from=7&to=23 %}

## CoroutineContext

It is simply a map between [Key](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines.experimental/-coroutine-context/-key.html) and [Element](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines.experimental/-coroutine-context/-element/index.html) (Key -> Element) where

* [Key](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines.experimental/-coroutine-context/-key.html): Key for the elements of type CoroutineContext

* [Element](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines.experimental/-coroutine-context/-element/index.html): Subtype of CoroutineContext, for example, Job, Deferred, CoroutineDispacher, ActorCoroutine, etc.

### Problem Statement

Let’s say we have mutable state accessed from different coroutines concurrently and we want this state to be thread-safe.
> *There are multiple ways to achieve this but I am going to show using single-threaded executor service.*

In the following example, 1000 coroutines are created concurrently and each coroutine increments counter value. In the end, asserting that counters value is 1000 proves that there are no race conditions in the solution. You can try printing thread name in the incrementAsyncfunction and verify that all running on the same thread.

{% kotlin https://pl.kotl.in/fDUMxcEET?from=8&to=26 %}

[**Job**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/) & [**Structured Concurrency**](https://kotlinlang.org/docs/reference/coroutines/basics.html#structured-concurrency)

Background job responsible for solely doing side-effects. Conceptually Job is a cancellable thing with lifecycle associated with it.

Coroutines implement [Job](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/) interface which is responsible for maintaining the lifecycle of a coroutine.

Jobs are designed to have a parent-child relationship and this helps a lot in achieving structured concurrency.

Let’s say we have three jobs A, B, and C. Job B and C are children of Job A. Now if for example Job C fails with an exception other than CancellationException, parent Job A gets notified and A immediately sends termination to other children in this case to Job B. This way structured concurrency is achieved.

![](https://cdn-images-1.medium.com/max/2344/1*8J9bK47rcjHk2kquWNzb-A.png)

**Note**: If the cause of the cancellation is [CancellationExcpetion](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html) then it is considered to be canceled normally hence such cancellations need not start sending termination signals to other siblings via parent.

A parent-child relation has the following effect:

* Cancellation of a parent with [cancel] or its exceptional completion (failure)immediately cancels all its children.

* Parent cannot complete until all its children are complete.

* Parent waits for all its children to complete in *completing* or *canceling* state.

* Uncaught exception in a child, by default, cancels parent. In particular, this applies to children created with [launch] [CoroutineScope.launch] coroutine builder.

* Note that [async][CoroutineScope.async] and other future-like coroutine builders do not have uncaught exceptions by definition since all their exceptions are caught and are encapsulated in their result.

[**Deferred**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/)

From the docs: [Deferred](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/) value is a non-blocking cancellable future; it is a [Job](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job) with a result.

Deferred has few additional methods than Job to get completed results either successful or exceptional.

## Coroutine Builders

There are multiple possible ways to create coroutines based on different requirements. In this section, let’s take a look at a few of them.

The two most commonly used coroutine builders are launch and async.

Note that these are extensions to CoroutineScope which means, without coroutine scope, you can not create new coroutine.

[**Launch**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html)

This creates new coroutine and returns a reference to coroutine as [Job](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/). Using this handle, you can manually cancel launched coroutine using the cancel method available on Job.

Launch is used to perform asynchronous fire and forget type of operations where you are not interested in the result of the operation.

```kotlin
    public fun CoroutineScope.launch(
      context: CoroutineContext = EmptyCoroutineContext,
      start: CoroutineStart = CoroutineStart.DEFAULT,
      block: suspend CoroutineScope.() -> Unit
    ): Job
```

[**Async**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html)

This creates new coroutine and returns a reference to coroutine as [Deferred](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/). Using this handle, you can manually cancel launched coroutine using the cancel method available on Deferred.

Async is used to perform asynchronous computation where you expect a result of the computation in the future. Once the result is available, you want to perform other operations using this result.

```kotlin
    public fun <T> CoroutineScope.async(
      context: CoroutineContext = EmptyCoroutineContext,
      start: CoroutineStart = CoroutineStart.DEFAULT,
      block: suspend CoroutineScope.() -> T
    ): Deferred<T>
```

It is very important to note that, when you lunch a coroutine with these constructs, the new job gets created. It inherits the coroutine context and corresponding parent job from where this was launched. The newly created job gets attached to the parent as a child node.

What is the default behavior of launch and async?

* The execution of coroutine starts immediately

* You can override this behavior by passing the different [CoroutineStart](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-start/) argument while launching coroutine, for example, `start = CoroutineStart.LAZY`

* Exceptions in coroutine cancel the parent job in the context which in turn cancels all other coroutines in the same scope

* You can override this behavior by providing explicit [SupervisorJob](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-supervisor-job.html) while creating [CoroutineScope](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html) but this is out of scope for this write-up

* Coroutines get executed on [Default](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html) [CoroutineDispatcher](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html). This is backed by a shared pool of threads and the maximum number of threads is equal to the number of CPU cores (at least two). For example, if you want to perform some IO operation then you can override this behavior by passing custom [CoroutineContext](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/-coroutine-context/index.html) like `context = Dispatchers.IO`

[**withContext**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-context.html)

We often come across a scenario where we want to perform both CPU and IO-bound operations. And it is very important to perform IO-bound operations on a different thread pool (possibly unbounded) than the CPU bound (threads = number of CPU cores). You can find more details on why should we have such segregation in [this](https://gist.github.com/djspiewak/46b543800958cf61af6efa8e072bfd5c) article

[withContext](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-context.html) construct is exactly designed for this purpose. Following example demonstrate the usage of this:

{% kotlin https://pl.kotl.in/4O3yql7oF?from=5&to=21 %}

Above example, [withContext](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-context.html) uses dispatcher from the new context, shifting execution of the block into the different thread if a new dispatcher is specified, and back to the original dispatcher when it completes.

But if you look at the first two lines of output, both got executed on the same thread but the third line got executed on a different thread. This is because IO dispatcher shares threads with a Default dispatcher, so using withContext(Dispatchers.IO) does not lead to an actual switching to another thread & typically execution continues in the same thread. This avoids thread switching costs. But that thread gets marked as IO thread and gets removed from a thread pool. Hence you see line three got executed on a different thread.

```kotlin
    ========= Output =======
    DefaultDispatcher-worker-1 [@coroutine#1] doing CPU work…
    DefaultDispatcher-worker-1 [@coroutine#1] doing IO work…
    DefaultDispatcher-worker-2 [@coroutine#1] back to doing CPU work…
```

[**runBlocking**](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html)

[runBlocking](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html) has very limited use cases and highly discouraged. Avoid using this unless it is the last solution to your problem and you know what you are doing.

runBlocking starts a new coroutine and blocks the current thread until it’s completion. It is designed to bridge regular blocking code and libraries that are written in suspending/non-blocking style. It has very limited use cases, for example,

* you can use runBlocking to block main application so that it will not terminate until all the coroutines launched within the application are completed either successfully or exceptionally

* runBlocking is very useful in ***tests***, you can wrap your tests in runBlocking. This will make sure your test code execute sequentially on the same thread and will not terminate until all coroutines are completed. You do not need to explicitly join or await them. Your tests look similar to the tests for synchronous code. In the following example, we want to test the `increment` function which increments a counter by `1` in async and non-blocking style. Test-should able to increment a counter, calls `increment` function `50` times and asserts that `counter == 50`

{% kotlin https://pl.kotl.in/oO8MCjWEg?from=7&to=20 %}

Find more details on this [here](https://stackoverflow.com/questions/52331373/kotlin-coroutines-runblocking).

## Suspend

We have already come across suspend keyword many times in this post. Let’s go deep into what suspending functions are!

suspend is a keyword in kotlin which indicates function can be paused and resumed later point in time. You can use suspending functions to call long-running computations without blocking the main thread.

Rules for calling suspending functions:

* from other suspending functions

* from coroutine (suspending functions inherits coroutine context from coroutine from where it is invoked)

Eventually, Kotlin code gets converted to JVM bytecode and there is no notion of suspend keyword on JVM. Under the hood, the kotlin compiler converts suspend functions to another function without the suspend keyword, which takes an additional parameter of type [**Continuation**](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/-continuation/index.html) which is nothing but a callback.

Following example shows kotlin suspending function and its compiled version in JVM

```kotlin
    // kotlin
    suspend fun updateUserInfo(name: String, id: Long): User

    // JVM
    public final Object updateUserInfo(String name, long id, Continuation<User> $completion)
```

## Continuation

Continuation is a simple interface defined in kotlin standard library which has only one method `resumeWith(result)`

```kotlin
    public interface Continuation<in T> {
        public val context: CoroutineContext
        public fun resumeWith(result: Result<T>)
    }
```

> Since v1.3, Continuation has only one method resumeWith(result: Result<T>) , earlier it used to have two methods resume(value: T) & resumeWithException(exception: Throwable)
> [Result](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-result/index.html) models eithersuccess with value of typeT or failure with the exception of type Throwable

You can very well relate this with callback style programming where you have methods like onSuccess and onFailure

If you are really interested to know how all these things work behind the scenes, I highly recommend you to watch Roman Elizarov talk — Deep Dive into Coroutines.

{% youtube YrrUCSi72E8 %}

In this talk, Roman Elizarov mentions:
> ***Continuation is a generic callback interface.***
> *Whenever you invoke suspending function, you actually invoke callback, its just callback is implicit and you don't see it in code. You just code it in nice direct style with callback behind the scenes.*

## References

* All the examples used in this article are available [here](https://github.com/kpritam/kotlin-coroutines/tree/master/blog/src/main/kotlin/blog/scopes)

* [Coroutines official guide](https://kotlinlang.org/docs/reference/coroutines/coroutines-guide.html)

* [Coroutines API docs](https://kotlin.github.io/kotlinx.coroutines/)

* [Coroutines youtube playlist](https://www.youtube.com/watch?v=_hfBv0a09Jc&list=PLwDsAAKWJGqcuj3CD8gBEabOituAAYrp3)

* [Structured concurrency](https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/)

* [Coroutine context and scope](https://medium.com/@elizarov/coroutine-context-and-scope-c8b255d59055)

* [Reason to avoid Global Scope](https://medium.com/@elizarov/the-reason-to-avoid-globalscope-835337445abc)