Kotlin Coroutines Basics - Simple Android App Demo

This simple Android app demonstrates the basic Kotlin coroutines usages such as creating coroutines (launch and async), cancelling coroutines.

This is part of the Kotlin coroutines series:

Part 1 - Kotlin Coroutines Basics - Simple Android App Demo
Part 2 - kotlinx.coroutines.delay() vs Thread.sleep()
Part 3 - GlobalScope vs viewModelScope vs lifecycleScope vs rememberCoroutineScope
Part 4 - launchWhenCreated() vs launchWhenStarted() vs launchWhenResumed() vs repeatOnLifeCycle()

I created this simple Android app to help me to understand the basic usage of Kotlin coroutines. The app demonstrates how to create coroutines jobs and run them concurrently. It probably won't cover 100% of the use cases, maybe at least 90%?

The app also uses simple MVVM architecture (without the Model to be exact).

App Overview

There are 3 buttons and 2 display texts (left and right) UI in this app.

Launch and Async buttons update both left text and right text UI concurrently
left text and right text are started at -1 as an invalid value.
When Launch or Async button is clicked, coroutines are created to update left text UI from 0 → 9 and right text UI from 10 → 19
If the Cancel button is clicked, both texts are stopped being updated and value is set to -1.
If no Cancel button is clicked, both texts continue to be updated until the final value 9 and 19

There are 2 ways to create coroutines:

CoroutineScope.launch
CoroutineScope.async

CoroutineScope.launch

To create a coroutine, we need to create CoroutineScope first. In ViewModel, CorotineScope is already created (i.e. viewModelScope). So it is highly recommended to use it instead of creating it yourself. One benefit is, all the CoroutineScope children will be automatically cancelled when ViewModel is destroyed.

// Create new coroutine - current job is the parent job
currentJob = viewModelScope.launch {

    // Create a first new sub-coroutine - job1 is the child job
    val job1 = launch {
        ...
    }

    // Create a second new sub-coroutine - job2 is the child job
    val job2 = launch {
        ...
    }

    // job1 and job2 are coroutines that run concurrently

    // wait for both job1 and job2 to complete
    job1.join()
    job2.join()
    ... 
}

CoroutineScpoe.launch is a non-blocking function, and it returns Job immediately. To achieve concurrency, we can call CoroutineScpoe.launch multiple times within the same coroutine scope. job1 is responsible to update the left text UI and job2 is responsible to update the right text UI.

If you want to wait for the job to complete, you need to call the Job.join() suspend function. This will wait until the job is completed before it moves to the next line.

CoroutineScope.async

For creating coroutine that we want to wait for it's returned value, we use CoroutineScope.async.

Similar to CoroutineScpoe.launch, CoroutineScope.async is a non-blocking function. Instead of returning Job, it returns Deferred<T>. The last line in the async block, is the return type T. For example, getData() returns Int, thus, the T is Int type.

// Create new coroutine
viewModelScope.launch {
    // Create a sub-coroutine with async
    val deferred = async {  
        ...
        getData()  
    }  
    // wait for async to return it's value
    data.value = deferred.await()
    ...
}

Instead of using Job.join(), you call Deferred<T>.awailt() to wait for the CoroutineScope.async to finish and also return the value from getData().

CoroutineScope.withContext()

By default, the coroutines are run on main/UI thread. You should move the long-running tasks to different thread so that it doesn't block the main/UI thread.

To switch to a different thread, you specify CoroutineDispatcher. Here are the common pre-defined CoroutineDispatcher that we can use:

Dispatchers.Main - main/UI thread
Dispatchers.Default - CPU operation thread
Dispatchers.IO - IO or network operation thread

To use your own thread, you can create a new thread / new CoroutineDispatcher using newSingleThreadContext("MyOwnThread"). Most of the time, the pre-defined CoroutineDispatcher are enough.

When creating a coroutine either with launch or async, you can specify the CoroutineDispatcher.

viewModelScope.launch {
    // Create coroutine that runs on Dispatchers.Default thread 
    launch(Dispatchers.Default) {
        loadData()
    }
    // Create coroutine that runs on Dispatchers.Default thread 
    async(Dispatchers.Default) {
        loadData()
    }
}

However, a better solution is to use CoroutineScope.withContext() in the suspend function instead of specifying the CoroutineDispatcher during coroutine creation. This is recommended because it makes the suspend function safe to be called from main/UI thread.

private suspend fun loadData() {
    //Switches / moves the coroutine to different thread
    withContext(Dispatchers.Default) {
        ...
    }
}

Please note CoroutineScope.withContext() does NOT create a new coroutine. It moves the coroutines to a different thread.

Job.cancelAndJoin()

To cancel a coroutine job, we call Job.cancel() and Job.join(). Most of the time, you can just simply call Job.cancelAndJoin(). Please note that Job.cancelAndJoin() is a suspend function. So you need to call it inside the coroutine.

fun onCancelButtonClick() {
    if (currentJob == null) return
    viewModelScope.launch() {
        currentJob!!.cancelAndJoin()
    }
}

currentJob is an existing coroutine job that was created before.

kotlinx.coroutines.yield()

One important thing to note is coroutine cancellation is cooperative. If a coroutine is non-cooperative cancellation, there is no way we can cancel it. The coroutine will continue to runs until it is complete although Job.cancel() has been called.

To make a coroutine cancellation cooperative, you can use:

CoroutineScope.isActive
kotlinx.coroutines.yield()

CoroutineScope.isActive required CoroutineScope object to be called, and you need to add logic to exit the coroutine, thus it is less flexible. Since yield() can be called in any suspend function, I personally prefer to use it.

Please note the kotlinx.coroutines.delay() also make the coroutine cancellation cooperative.

For example, if you have a long-running task like below, the coroutine will not honor any Job.cancel() request.

private suspend fun simulateLongRunningTask() {  
    repeat(1_000_000) {  
        Thread.sleep(100)  
    }  
}

To make it to accept the Job.cancel() request, you just need to add yield().

private suspend fun simulateLongRunningTask() {  
    repeat(1_000_000) {  
        Thread.sleep(100)  
        yield()
    }  
}

kotlinx.coroutines.JobCancellationException

When a coroutine is cancellation is accepted, an kotlinx.coroutines.JobCancellationException exception will be thrown. You can catch the exception and perform some clean up.

currentJob = viewModelScope.launch {
    try {
        val job1 = launch {
            ...
        }

        val job2 = launch {
            ...
        }

        job1.join()
        job2.join()

    } catch (e: Exception) {
        // clean up here
        currentJob = null
    }   
}

kotlinx.coroutines.coroutineContext

For debugging coroutine, logging is the easiest way. kotlinx.coroutines.coroutineContext is very useful for logging. It provides the coroutine and thread information.

Please note that it is a suspend property which can only be called from the suspend function.

Example of Utils.log() utility suspend function to wrap the .Log.d():

object Utils {  
    suspend fun log(tag: String, msg: String) {  
        Log.d(tag, "$coroutineContext: $msg")  
    }  
}

//Usage
Utils.log("ViewModel", "======= Created launch coroutine - onButtonClick() =======")

Example of Logcat output:

D/ViewModel: [StandaloneCoroutine{Active}@5261b32, Dispatchers.Main.immediate]: ======= Created launch coroutine - onButtonClick() =======

Some Thoughts

So far, all my personal projects do not use all the coroutines use cases above. I only use CoroutineScope.launch and CoroutineScope.withContext() which is enough for me to accomplish what I want. I don't even need to cancel a coroutine, although I can if I want to, and the apps still work perfectly.

[Update: April 13, 2022]: I did use joinAll() parallelize a few network calls instead of running the code in sequential. Example below:

private suspend fun fetchArticlesFeed() : List<ArticleFeed> = coroutineScope {
    val results = mutableListOf<ArticleFeed>()
    val jobs = mutableListOf<Job>()

    for(url in urls) {
        val job = launch {
            val xmlString = webService.getXMlString(url)
            val articleFeeds = FeedParser().parse(xmlString)
            results.addAll(articleFeeds)
        }

        jobs.add(job)
    }

    jobs.joinAll()

    return@coroutineScope results
}