Using coroutines in Android development | Getting started guide

Continuing from the previous article "Using coroutines in Android development | Background introduction"

This article is the second part of a series on Android coroutines. This article will focus on how to use coroutines to handle tasks and keep track of them after they start executing.

[[323364]]

Keeping Track of Coroutines

In the first article of this series, we discussed what problems coroutines are suitable for solving. Here is a brief review, coroutines are suitable for solving the following two common programming problems:

• Handle long running tasks, which often block the main thread;
• Main-safety is the guarantee that any suspend function can be safely called from the main thread.

Coroutines solve the above problems by adding two operations, suspend and resume, to regular functions. When all coroutines on a specific thread are suspended, the thread can free up resources to handle other tasks.

Coroutines themselves cannot keep track of what they are doing, but it is not a big problem to have hundreds or thousands of coroutines and suspend operations on them at the same time. Coroutines are lightweight, but the tasks they perform are not necessarily lightweight, such as reading files or sending network requests.

It is very difficult to manually track thousands of coroutines using code. You can try to track all of them and manually ensure that they are all completed or cancelled, which will make the code bloated and error-prone. If the code is not perfect, it will lose track of the coroutines, which is the so-called "work leak".

A work leak is when a coroutine is lost and cannot be tracked. It is similar to a memory leak, but worse. The lost coroutine can recover itself, occupying memory, CPU, disk resources, and even initiating a network request, which means that the resources it occupies cannot be reused.

Leaking coroutines can waste memory, CPU, disk resources, and even send a useless network request.

In order to avoid coroutine leakage, Kotlin introduces structured concurrency mechanism, which is a combination of a series of programming language features and practical guidelines. Following it can help you track all tasks running in coroutines.

On the Android platform, we can use structured concurrency to do the following three things:

• Cancel tasks - cancel a task when it is no longer needed;
• Tracking tasks - Tracking a task as it is being executed;
• Signal an error - When a coroutine fails, an error is signaled to indicate that an error occurred.

Next, we will discuss the above points one by one and see how structured concurrency can help track all coroutines without causing leaks.

Structured concurrency:

https://kotlinlang.org/docs/reference/coroutines/basics.html#structured-concurrency

Cancelling tasks with scope

In Kotlin, when defining a coroutine, you must specify its CoroutineScope. CoroutineScope can track the coroutine even if the coroutine is suspended. Unlike the dispatcher mentioned in the first article, CoroutineScope does not run the coroutine, it just ensures that you do not lose track of the coroutine.

To ensure that all coroutines are tracked, Kotlin does not allow starting new coroutines without using CoroutineScope. CoroutineScope can be seen as a lightweight version of ExecutorService with superpowers. It can start new coroutines, and this coroutine also has the advantages of suspend and resume that we talked about in the first part.

CoroutineScope keeps track of all coroutines, and it can also cancel all coroutines started by it. This is very useful in Android development, for example, it can stop the execution of coroutines when the user leaves the interface.

CoroutineScope keeps track of all coroutines and can cancel any coroutine started by it.

Start a new coroutine

It is important to note that you cannot just call a suspend function anywhere; the suspend and resume mechanism requires you to switch from a regular function to a coroutine.

There are two ways to start a coroutine, which are suitable for different scenarios:

• The launch builder is suitable for performing "fire-and-forget" work, meaning that it can start a new coroutine without returning the result to the caller;
• The async builder starts a new coroutine and allows you to return a result using a suspending function called await.

Normally, you should use launch to start a new coroutine from a regular function. Since a regular function cannot call await (remember, it cannot call a suspend function directly), it doesn't make much sense to use async as the primary method of starting a coroutine. We'll discuss how to use async later.

You should instead use the coroutine scope to call the launch method to start the coroutine.

 scope.launch {
 // This code starts a new coroutine in the scope
 // It can call the suspend function
 fetchDocs()
 }

You can think of launch as a bridge that sends code from a regular function to the coroutine world. In the body of the launch function, you can call the suspend function and be able to ensure main thread safety as we introduced in the previous article.

Launch is the bridge that sends code from regular functions to the world of coroutines.

Note : A big difference between launch and async is how they handle exceptions. async expects to eventually get a result (or an exception) by calling await, so it doesn't throw exceptions by default. This means that if you use async to launch a new coroutine, it will silently discard the exception.

Since launch and async can only be used in CouroutineScope, any coroutine you create will be tracked by this scope. Kotlin prohibits you from creating coroutines that cannot be tracked, thus avoiding coroutine leaks.

• launchhttps://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html
• asynchttps://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html

Start the coroutine in the ViewModel

Since CoroutineScope keeps track of all coroutines started by it, and launch creates a new coroutine, where should you call launch and put it in the scope? And when should you cancel all coroutines started in the scope?

On Android, you can associate a CoroutineScope implementation with your user interface. This lets you avoid leaking memory or performing extra work on Activities or Fragments that are no longer relevant to the user. When the user navigates away from a screen, the CoroutineScope associated with that screen can cancel any unneeded tasks.

Structured concurrency ensures that when a scope is cancelled, all coroutines created within it are also cancelled.

When integrating coroutines with Android Architecture Components, you often need to start the coroutine in the ViewModel. Since most of the work is done here, it is a reasonable place to start it, and you don't have to worry about rotating the screen orientation terminating the coroutine you created.

Starting with version 2.1.0 of the AndroidX Lifecycle component (released in September 2019), we added support for coroutines in ViewModel by adding the extended property ViewModel.viewModelScope.

Consider the following example:

 class MyViewModel(): ViewModel() {
 fun userNeedsDocs() {
 // Start a new coroutine in ViewModel
        viewModelScope.launch {
 fetchDocs()
 }
 }
 }

When the viewModelScope is cleared (when the onCleared() callback is called), it will automatically cancel all the coroutines it started. This is standard practice, and if a user closes the app before the data is fetched, letting the request continue to complete is a pure waste of battery.

For added safety, CoroutineScope propagates itself. That is, if a coroutine starts another new coroutine, they both terminate in the same scope. This means that even if a codebase you depend on starts a coroutine from a viewModelScope you created, you have a way to cancel it.

Note : When a coroutine is suspended, the system will cooperatively cancel the coroutine by throwing a CancellationException. Exception handlers that catch top-level exceptions (such as Throwable) will catch this exception. If you consume this exception when doing exception handling, or never perform a suspend operation, the coroutine will linger in a semi-canceled state.

Therefore, when you need to keep a coroutine consistent with the lifecycle of ViewModel, use viewModelScope to switch from a regular function to a coroutine. Then, viewModelScope will automatically cancel the coroutine for you, so even if you write an infinite loop here, there will be no leaks at all. The following example:

 fun runForever() {
 // Start a new coroutine in ViewModel
 viewModelScope.launch {
 // When the ViewModel is cleared, the following code will also be cancelled
 while(true) {
 delay(1_000)
 // Do something every 1 second
 }
 }
 }

By using viewModelScope, you can ensure that all tasks, including infinite loops, can be cancelled when they are not needed.

Collaboration Cancellation:

https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#cancellation-and-timeouts

Task Tracking

Using coroutines to handle tasks is really convenient for a lot of code. Start the coroutine, make a network request, and write the result to the database, everything is very natural and smooth.

But sometimes, you may encounter slightly more complicated problems. For example, you need to process two network requests simultaneously in one coroutine. In this case, you need to start more coroutines.

To create multiple coroutines, you can use a constructor named coroutineScope or supervisorScope in the suspend function to start multiple coroutines. But this API is a bit confusing to be honest. The difference between the coroutineScope constructor and CoroutineScope is only one letter difference, but they are completely different things.

In addition, if new coroutines are started randomly, it may cause potential work leaks. The caller may not be aware that a new coroutine has been started, which means it cannot be tracked.

To solve this problem, structured concurrency comes into play, which ensures that when the suspend function returns, it means that the tasks it handles are also completed.

Structured concurrency ensures that when a suspend function returns, the tasks it handles are also completed.

The example uses coroutineScope to get the contents of two documents:

 suspend fun fetchTwoDocs() {
 coroutineScope {
        launch { fetchDoc(1) }
 async { fetchDoc(2) }
 }
 }

In this example, two documents are retrieved from the network at the same time. The first one is started by launching the coroutine in a "once and for all" way, which means that it does not return any results to the caller.

The second one is to get the document in async way, so there will be a return value. However, the above example is a bit strange, because usually both documents should be obtained using async, but here I just want to give an example to illustrate that you can choose to use launch or async according to your needs, or mix the two.

coroutineScope and supervisorScope allow you to safely launch coroutines from suspend functions.

But please note that this code does not explicitly wait for the two created coroutines to complete their tasks before returning. When fetchTwoDocs returns, the coroutines are still running.

Therefore, in order to achieve structured concurrency and avoid leaks, we want to ensure that when suspend functions such as fetchTwoDocs return, all the tasks they do can also be completed. In other words, before fetchTwoDocs returns, all the coroutines it started can also complete their tasks.

Kotlin ensures that fetchTwoDocs will not leak by using the coroutineScope constructor, coroutineScope will suspend itself and wait for all the coroutines started inside it to complete before returning. Therefore, the fetchTwoDocs function will return only after all the coroutines started in the coroutineScope builder have completed their tasks.

• coroutineScope: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
• supervisorScope: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/supervisor-scope.html

Handling a bunch of tasks

Now that we have achieved tracing one or two coroutines, let’s try tracing a thousand coroutines!

Take a look at the following animation first

This animation shows us how to make a thousand network requests at the same time. Of course, it is best not to do this in real Android development, as it is a waste of resources.

In this code, we use launch in the coroutineScope constructor to start a thousand coroutines, and you can see how it all connects together. Since we are using the suspend function, the code must have used a CoroutineScope to create the coroutine. We currently know nothing about this CoroutineScope, it may be a viewModelScope or a CoroutineScope defined elsewhere, but in any case, the coroutineScope constructor will use it as the parent of the new scope it creates.

Then, inside the coroutineScope block, launch will start the coroutine in the new scope, and the scope will track the coroutines as they are launched. Finally, once all the coroutines launched inside the coroutineScope have completed, the loadLots method can simply return.

Note : The parent-child relationship between scope and coroutine is created using the Job object. But you don’t need to understand it in depth, just know this.

coroutineScope and supervisorScope will wait for all child coroutines to complete.

The point above is that using coroutineScope and supervisorScope, you can safely start a coroutine from any suspend function. Even if you start a new coroutine, there will be no leaks because the caller is always suspended until the new coroutine is completed.

What's more, coroutineScope will create a child scope, so once the parent scope is cancelled, it will pass the cancellation message to all new coroutines. If the caller is viewModelScope, these thousand coroutines will be automatically cancelled after the user leaves the interface, which is very neat and efficient.

Before we move on to error-related issues, it is necessary to take a moment to discuss supervisorScope and coroutineScope. The main difference between them is that coroutineScope will be cancelled if any subscope fails. If a network request fails, all other requests will be cancelled immediately. For this requirement, choose coroutineScope. On the contrary, if you want other requests to continue even if one request fails, you can use supervisorScope. When a coroutine fails, supervisorScope will not cancel the remaining sub-coroutines.

Signal an error when a coroutine fails

In coroutines, error signals are sent by throwing exceptions, just like the functions we write normally. Exceptions from suspend functions will be re-thrown to the caller through resume for processing. Like regular functions, you can not only use try/catch to handle errors, but also build abstractions to handle errors in the way you like.

However, in some cases, the coroutine may still lose the obtained error.

 val unrelatedScope = MainScope ()
 // Lost error example
 suspend fun lostError() {
 // async without structured concurrency
 unrelatedScope.async {
        throw InAsyncNoOneCanHearYou("except")
 }
 }

Note : The above code declares an unrelated coroutine scope, which will not start a new coroutine in the way of structured concurrency. Remember what I said at the beginning that structured concurrency is a collection of programming language features and practice guidelines. Introducing unrelated coroutine scope in the suspend function violates the rules of structured concurrency.

In this code the error will be lost because async assumes you will eventually call await and it will rethrow the exception, but you didn't call await so the exception is sitting there forever waiting to be called and the error will never be handled.

Structured concurrency ensures that when a coroutine fails, its caller or scope will be notified.

If you write the above code according to the specifications of structured concurrency, the error will be correctly thrown to the caller for handling.

 suspend fun foundError() {
 coroutineScope {
 async {
            throw StructuredConcurrencyWill("throw")
 }
 }
 }

coroutineScope not only waits until all subtasks are completed, but it also gets notified when they fail. If a coroutine created with coroutineScope throws an exception, coroutineScope will throw it to the caller. Because we are using coroutineScope instead of supervisorScope, when an exception is thrown, it will immediately cancel all subtasks.

Using structured concurrency

In this article, I introduced structured concurrency and showed how to make our code work with ViewModels in Android to avoid task leaks.

Likewise, I helped you better understand and use suspend functions, by ensuring that they complete their tasks before returning, or by ensuring that they properly signal errors by exposing exceptions.

If we use code that does not conform to structured concurrency, it will be easy to have coroutine leaks, that is, the caller does not know how to track the task. In this case, the task cannot be cancelled, and there is no guarantee that the exception will be re-thrown. This will make our code difficult to understand and may cause some difficult-to-track bugs.

You can do this by introducing a new unrelated CoroutineScope (note the capital C), or by creating a global scope using GlobalScope, but this code does not conform to the requirements of structured concurrency.

However, when there is a situation where the coroutine needs to outlive the caller, you may need to consider unstructured concurrency coding, but this situation is relatively rare. Therefore, it would be a good idea to use structured programming to track unstructured coroutines and perform error handling and task cancellation.

If you haven't been coding with structured concurrency before, it will take some time to get used to it at first. This structure does make interacting with suspend functions safer and easier to use. When coding, use structured concurrency as much as possible, which makes the code easier to maintain and understand.

At the beginning of this article, we listed three problems that structured concurrency solves for us:

• Cancel tasks - cancel a task when it is no longer needed;
• Tracking tasks - Tracking a task as it is being executed;
• Signal an error - When a coroutine fails, an error is signaled to indicate that an error occurred.

Implementing this structured concurrency provides some guarantees for our code:

• When a scope is cancelled, all coroutines within it will also be cancelled;
• When a suspend function returns, it means that all its tasks have been completed;
• When a coroutine reports an error, its scope or caller will receive an error notification.

In summary, structured concurrency makes our code safer, easier to understand, and avoids task leakage.

Next step

In this article, we explored how to start a coroutine in Android's ViewModel and how to use structured concurrency in our code to make our code easier to maintain and understand.

In the next article, we will explore how to use coroutines in actual coding. Interested readers please stay tuned for our updates.

[This article is an original article from the 51CTO column "Google Developers". Please contact the original author (WeChat public account: Google_Developers) for reprinting.]

Click here to read more articles by this author