Problem

You need to select the right function to create a coroutine.

Solution

Decide between the available builder functions.

Discussion

To create a new coroutine, you use one of the available builder functions: runBlocking, launch, or async. The first, runBlocking, is a top-level function, while launch and async are extension functions on CoroutineScope.

Before looking at how they are used, be aware that there are also versions of launch and async defined on GlobalScope, and their usage is highly discouraged, if not completely deprecated. The problem with those functions is that they launch coroutines that are not bound to any particular job, and they span the entire application life cycle if not cancelled prematurely. So please don’t use them unless you have an overriding reason to do so.

fun <T> runBlocking(block: suspend CoroutineScope.() -> T): T

import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking

fun main() {
    println("Before creating coroutine")
    runBlocking {
        print("Hello, ")
        delay(200L)
        println("World!")
    }
    println("After coroutine is finished")
}

Before creating coroutine
Hello, World!
After coroutine finished

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

import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

fun main() {
    println("Before runBlocking")
    runBlocking {                 
        println("Before launch")
        launch {                  
            print("Hello, ")
            delay(200L)
            println("World!")
        }
        println("After launch")
    }
    println("After runBlocking")
}

Before runBlocking
Before launch
After launch
Hello, World!
After runBlocking

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

import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlin.random.Random

suspend fun add(x: Int, y: Int): Int {
    delay(Random.nextLong(1000L))                      
    return x + y
}

suspend fun main() = coroutineScope {                  
    val firstSum = async {                             
        println(Thread.currentThread().name)
        add(2, 2)
    }
    val secondSum = async {                            
        println(Thread.currentThread().name)
        add(3, 4)
    }
    println("Awaiting concurrent sums...")
    val total = firstSum.await() + secondSum.await()   
    println("Total is $total")
}

DefaultDispatcher-worker-2
Awaiting concurrent sums...
DefaultDispatcher-worker-1
Total is 11

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

import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch

suspend fun main() = coroutineScope {   
    for (i in 0 until 10) {
        launch {                        
            delay(1000L - i * 10)       
            print("❤️$i ")
        }
    }
}

❤️9 ❤️8 ❤️7 ❤️6 ❤️5 ❤️4 ❤️3 ❤️2 ❤️1 ❤️0

Problem

You want to simplify code that starts a coroutine with async and then immediately waits for it to complete with await.

Solution

Replace the combination of async/await with withContext.

Discussion

The CoroutineScope class also defines an extension function called withContext. Its signature is given by the following:

suspend fun <T> withContext(
    context: CoroutineContext,
    block: suspend CoroutineScope.() -> T
): T

The documentation says that withContext “calls the specified suspending block with a given coroutine context, suspends until it completes, and returns the result.” In practice, use withContext to replace a combination of async with an immediate await, as in Example 13-5.

suspend fun retrieve1(url: String) = coroutineScope {
    async(Dispatchers.IO) {
        println("Retrieving data on ${Thread.currentThread().name}")
        delay(100L)
        "asyncResults"
    }.await()
}

suspend fun retrieve2(url: String) =
    withContext(Dispatchers.IO) {
        println("Retrieving data on ${Thread.currentThread().name}")
        delay(100L)
        "withContextResults"
    }

fun main() = runBlocking<Unit> {
    val result1 = retrieve1("www.mysite.com")
    val result2 = retrieve2("www.mysite.com")
    println("printing result on ${Thread.currentThread().name} $result1")
    println("printing result on ${Thread.currentThread().name} $result2")
}

The main function starts with runBlocking, again typical of a simple demo like this. The two functions retrieve1 and retrieve2 do the same thing, which is to delay for 100 milliseconds and then return a string. The results are shown here (note the ordering could be different):

Retrieving data on DefaultDispatcher-worker-2
Retrieving data on DefaultDispatcher-worker-2
printing result on main withContextResults
printing result on main asyncResults

Both are using the Dispatchers.IO dispatcher (discussed in Recipe 13.3), so the only difference between the two functions is that one uses async/await and the other replaces it with withContext. In fact, when IntelliJ IDEA sees you using async with an immediate await, it will suggest replacing it with withContext as shown, and will do it for you if you let it.

Problem

You need to use a dedicated thread pool to do I/O or other tasks.

Solution

Use the proper dispatcher in the Dispatchers class.

Discussion

Coroutines execute in a context defined by a CoroutineContext type, which includes a coroutine dispatcher represented by an instance of the CoroutineDispatcher class. The dispatcher determines which thread or thread pool the coroutines use for their execution.

When you use a builder like launch or async, you can specify the dispatcher you want to use through an optional CoroutineContext parameter.

Built-in dispatchers provided by the library include the following:

• Dispatchers.Default

• Dispatchers.IO

• Dispatchers.Unconfined

The last one should not normally be used in application code.

The Default dispatcher uses a common pool of shared background threads. It is appropriate for coroutines that consume extensive amounts of computation resources.

The IO dispatcher uses a shared pool of on-demand created threads and is designed for offloading I/O-intensive blocking operations, like file I/O or blocking networking I/O.

Using either is quite simple. Just add them as an argument to launch, async, or withContext as needed. See Example 13-6.

fun main() = runBlocking<Unit> {
    launchWithIO()
    launchWithDefault()
}

suspend fun launchWithIO() {
    withContext(Dispatchers.IO) {            
        delay(100L)
        println("Using Dispatchers.IO")
        println(Thread.currentThread().name)
    }
}

suspend fun launchWithDefault() {
    withContext(Dispatchers.Default) {       
        delay(100L)
        println("Using Dispatchers.Default")
        println(Thread.currentThread().name)
    }
}

The results are shown here (worker numbers may differ):

Using Dispatchers.IO
DefaultDispatcher-worker-3
Using Dispatchers.Default
DefaultDispatcher-worker-2

You can specify either dispatcher when the coroutines are launched.

dependencies {
  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:x.x.x"
  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:x.x.x"
}

See Also

Using a Java executor service as a source of coroutine dispatchers is discussed in Recipe 13.4. Android dispatchers are discussed further in Recipe 13.5.

Problem

You want to supply your own custom thread pool for coroutines to use.

Solution

Use the asCoroutineDispatcher function on Java’s ExecutorService.

Discussion

The Kotlin library adds an extension method on java.util.concurrent.ExecutorService called asCoroutineDispatcher. As the documentation says, the function converts an instance of ExecutorService to an implementation of ExecutorCoroutineDispatcher.

To use it, use the Executors class to define your thread pool and then convert it to be used as a dispatcher, as in Example 13-7.

import kotlinx.coroutines.asCoroutineDispatcher
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import java.util.concurrent.Executors

fun main() = runBlocking<Unit> {
    val dispatcher = Executors.newFixedThreadPool(10)  
        .asCoroutineDispatcher()

    withContext(dispatcher) {                          
        delay(100L)
        println(Thread.currentThread().name)
    }

    dispatcher.close()                                 
}

The output prints pool-1-thread-2, indicating that the system chose to run the coroutine on thread 2 of pool 1.

Note the last line in that example, which invokes the close function on the dispatcher. This is necessary, because the executor service will continue to run without it, meaning the main function will never exit.

While the preceding technique works, it’s also an interesting illustration of how Kotlin goes about solving this sort of problem. Normally, to get a Java ExecutorService to stop, you invoke the shutdown or shutdownNow method. Therefore, in principle you could rewrite the example to keep a reference to the ExecutorService and shut it down manually, as in Example 13-8.

val pool = ExecutorService.newFixedThreadPool(10)
withContext(pool.asCoroutineDispatcher()) {
    // ... same as before ...
}
pool.shutdown()

The problem with that approach is that a user might forget to call the shutdown method. Java solves problems like that by implementing the AutoCloseable interface with a close method, so that you can wrap the code in a try-with-resources block. Unfortunately, the method you want to call here is shutdown, not close.

The developers of the Kotlin library therefore made a change to the underlying ExecutorCoroutineDispatcher class, an instance of which is created in the preceding code. They refactored it to implement the Closeable interface, so that the new abstract class is called CloseableCoroutineDispatcher, whose close method looks like this:

import java.util.concurrent.ExecutorService

abstract class ExecutorCoroutineDispatcher: CoroutineDispatcher(), Closeable {
    abstract override fun close()
    abstract val executor: Executor
}

// Then, in subclasses:
override fun close()  {
    (executor as? ExecutorService)?.shutdown()
}

That means that the dispatchers created using the executor service now have a close function that will shut down the underlying executor service. The question then is how do you ensure that the close function is called, given that Kotlin doesn’t support a try-with-resources construct similar to Java? What Kotlin does have is a use function. The definition of use is shown in Example 13-9.

inline fun <T : Closeable?, R> T.use(block: (T) -> R): R

Therefore, use is defined as an extension function on Java’s Closeable interface. That gives a straightforward solution to the problem of shutting down the Java executor service, shown in Example 13-10.

Executors.newFixedThreadPool(10).asCoroutineDispatcher().use {
    withContext(it) {
        delay(100L)
        println(Thread.currentThread().name)
    }
}

This will close the dispatcher when the use block ends, which will also close the underlying thread pool.

See Also

The use function is described in Recipe 10.1.

Problem

You need more information about executing coroutines.

Solution

On the JVM, run with the -Dkotlinx.coroutines.debug flag.

Discussion

Debugging asynchronous programs is always difficult, because multiple operations can be running at the same time. Fortunately, the coroutines library includes a simple debugging feature.

To execute coroutines in debug mode (on the JVM), use the system property kotlinx.coroutines.debug.

Debug mode attaches a unique name to every launched coroutine. Example 13-5, reproduced here for convenience, shows two coroutines being launched in addition to the main thread:

suspend fun retrieve1(url: String) = coroutineScope {
    async(Dispatchers.IO) {
        println("Retrieving data on ${Thread.currentThread().name}")
        delay(100L)
        "asyncResults"
    }.await()
}

suspend fun retrieve2(url: String) =
    withContext(Dispatchers.IO) {
        println("Retrieving data on ${Thread.currentThread().name}")
        delay(100L)
        "withContextResults"
    }

fun main() = runBlocking<Unit> {
    val result1 = retrieve1("www.mysite.com")
    val result2 = retrieve2("www.mysite.com")
    println("printing result on ${Thread.currentThread().name} $result1")
    println("printing result on ${Thread.currentThread().name} $result2")
}

If you execute this program with -Dkotlinx.coroutines.debug, the output is as follows:

Retrieving data on DefaultDispatcher-worker-1 @coroutine#1
Retrieving data on DefaultDispatcher-worker-1 @coroutine#2
printing result on main @coroutine#1 withContextResults
printing result on main @coroutine#1 asyncResults

Each coroutine has been given a unique name (@coroutine#1, etc.) that is displayed as part of the thread name.

While this is helpful, sometimes you want to supply names to the coroutines rather than use the generated ones. The Kotlin library includes a class called CoroutineName for this purpose. The CoroutineName constructor produces a context element that can be used as the thread name, as in Example 13-15.

suspend fun retrieve1(url: String) = coroutineScope {
    async(Dispatchers.IO + CoroutineName("async")) {  
        // ... as before ...
    }.await()
}

suspend fun retrieve2(url: String) =
    withContext(Dispatchers.IO + CoroutineName("withContext")) { 
        // ... as before ...
    }

The result now looks like this:

Retrieving data on DefaultDispatcher-worker-1 @withContext#1
Retrieving data on DefaultDispatcher-worker-1 @async#2
printing result on main @coroutine#1 withContextResults
printing result on main @coroutine#1 asyncResults

The words “async” and “withContext” now appear as the names of the coroutines. This is also a nice example of the overloaded plus operator when used on CoroutineContext. Another example of the plus operator being used is shown in Recipe 13.5 for Android applications.