Cancellation and exceptions in coroutines | Detailed explanation of cancellation operations

In daily development, we all know that unnecessary task processing should be avoided to save device memory and power usage - this principle also applies to coroutines. You need to control the life cycle of the coroutine and cancel it when it is not needed. This is also advocated by structured concurrency. Read this article to learn about the ins and outs of coroutine cancellation.

To better understand what this article is about, it is recommended that you first read the first article in this series: Cancellation and Exceptions in Coroutines | Introduction to Core Concepts.

[[332964]]

Calling the cancel method

When launching multiple coroutines, it is a headache to track the coroutine status and cancel each coroutine individually. However, we can solve this problem by directly canceling the entire scope involved in the coroutine launch, because this will cancel all the created child coroutines.

 // Assume we have defined a scope 
 
 val job1 = scope .launch { … }
 val job2 = scope .launch { … } 
 
 scope.cancel()

1. Canceling a scope will cancel its child coroutines

Sometimes, you may only need to cancel one of the coroutines, such as when a user inputs an event and you need to cancel a task in progress in response. As shown in the following code, calling job1.cancel will ensure that only the specific coroutine associated with job1 is canceled without affecting the other sibling coroutines.

 // Assume we have defined a scope 
 
 val job1 = scope .launch { … }
 val job2 = scope .launch { … } 
  
 // The first coroutine will be cancelled, while the other one will not be affected
 job1.cancel()

2. The canceled sub-coroutine does not affect the other sibling coroutines

Coroutines handle cancellation by throwing a special exception, CancellationException. When calling .cancel, you can pass in a CancellationException instance to provide more detailed information about the cancellation. The signature of this method is as follows:

 fun cancel(cause: CancellationException? = null)

If you don't construct a new CancellationException instance and pass it as a parameter, a default CancellationException will be created (see the full code).

 public override fun cancel(cause: CancellationException?) {
    cancelInternal(cause ?: defaultCancellationException())
 }

Complete code:

https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/common/src/JobSupport.kt#L612

Once a CancellationException is thrown, you can use this mechanism to handle the cancellation of the coroutine. For more information on how to do this, see the Handling Side Effects of Cancellation section below.

In the underlying implementation, the child coroutine will notify its parent of the cancellation by throwing an exception. The parent coroutine decides whether to handle the exception based on the cancellation reason passed in. If the child coroutine is cancelled due to CancellationException, no additional operations are required for its parent.

3. You cannot start a new coroutine in a canceled scope

If you are using the androidx KTX library, in most cases you don't need to create your own scopes, so you don't need to be responsible for canceling them. If you are operating in the scope of a ViewModel, use viewModelScope, or if you start a coroutine in a lifecycle-related scope, you should use lifecycleScope. Both viewModelScope and lifecycleScope are CoroutineScope objects, and they will be canceled at the appropriate time. For example, when the ViewModel is cleared, the coroutines started in its scope will also be canceled.

• viewModelScope: https://developer.android.google.cn/reference/kotlin/androidx/lifecycle/package-summary#(androidx.lifecycle.ViewModel).viewModelScope:kotlinx.coroutines.CoroutineScope
• lifecycleScope: https://developer.android.google.cn/reference/kotlin/androidx/lifecycle/package-summary#lifecyclescope

Why doesn't the task processed by the coroutine stop?

If we just call the cancel method, it does not mean that the task processed by the coroutine will also stop. If you use the coroutine to handle some relatively heavy work, such as reading multiple files, your code will not automatically stop the progress of this task.

Let's take a simpler example to see what happens. Suppose we need to use a coroutine to print "Hello" twice a second. We first let the coroutine run for one second and then cancel it. One version of the implementation is as follows:

Let's look at what happens step by step. When we call the launch method, we create an active coroutine. Then we let the coroutine run for 1,000 milliseconds, and the printed result is as follows:

 Hello 0
 Hello 1
 Hello 2

When the job.cancel method is called, our coroutine changes to the canceling state. But then we find that Hello 3 and Hello 4 are printed to the command line. When the task processed by the coroutine is completed, the coroutine changes to the cancelled state.

The task handled by the coroutine does not stop simply when the cancel method is called. Instead, we need to modify the code to periodically check whether the coroutine is still active.

Make your coroutines can be cancelled

You need to make sure that all code implementations that use coroutines to process tasks are cooperative, that is, they are all handled with coroutine cancellation, so you can check whether the coroutine has been cancelled regularly during task processing, or check whether the current coroutine has been cancelled before processing time-consuming tasks. For example, if you get multiple files from disk, check whether the coroutine has been cancelled before starting to read the file content. With this approach, you can avoid processing unnecessary CPU-intensive tasks.

 val job = launch {
 for(file in files) {
 // TODO check if the coroutine is cancelled
 readFile(file)
 }
 }

All suspend functions in kotlinx.coroutines (withContext, delay, etc.) are cancelable. If you use any of them, you don't need to check if the coroutine is cancelled and then stop the task execution or throw a CancellationException. However, if you don't use these functions, in order to make your code cooperate with coroutine cancellation, you can use the following two methods:

• Check job.isActive or use ensureActive()
• Use yield() to allow other tasks to proceed

Check the activity status of the job

Let’s look at the first method first. We’ll add a check for the coroutine status in our while(i<5) loop:

 // Because we are in the launch code block, we can access the job.isActive property
 while (i <   5 && isActive)

This means that our task will only be executed when the coroutine is active. This also means that outside of the while loop, if we want to handle other actions, such as logging when the job is cancelled, we can check !isActive and then proceed accordingly.

The Coroutine codebase also provides another useful method - ensureActive(), which is implemented as follows:

 fun Job.ensureActive(): Unit {
 if (!isActive) {
         throw getCancellationException()
 }
 }

If the job is not active, this method will throw an exception immediately. We can use this method at the beginning of the while loop.

 while (i <   5 ) {
 ensureActive()
 …
 }

By using the ensureActive method, you can avoid using an if statement to check the isActive state, which reduces the amount of boilerplate code, but also loses the flexibility of handling behaviors such as logging.

Use the yield() function to run other tasks

If the task you are handling is 1) CPU intensive, 2) may exhaust thread pool resources, and 3) needs to allow the thread to handle other tasks without adding more threads to the thread pool, then use yield(). If the job is already completed, the first task handled by yield will be to check the completion status of the task, and if so, exit the coroutine directly by throwing a CancellationException. yield can be used as the first function called for periodic checks, such as the ensureActive() method mentioned above.

yield():

https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/yield.html

Job.join 🆚 Deferred.await cancellation

There are two ways to wait for the result of coroutine processing: the job from launch can call the join method, and the Deferred (one of the job types) returned by async can call the await method.

Job.join will suspend the coroutine until the task is completed. When used with job.cancel, it will proceed as follows:

• If you call job.cancel and then job.join, the coroutine will be suspended until the task processing is completed;
• Calling job.cancel after job.join has no effect, because the job has already been completed.

Job.join:

https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/join.html

If you care about the result of the coroutine, you should use Deferred. When the coroutine is completed, the result will be returned by Deferred.await. Deferred is a type of Job, which can also be cancelled.

• Deferred: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html
• Deferred.await: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/await.html

Calling await on a canceled deferred will throw a JobCancellationException.

 val deferred = async { … } 
 
 deferred.cancel()
 val result = deferred .await() // Throws JobCancellationException

Why do we get this exception? The role of await is to suspend the coroutine until the coroutine processing result comes out, because if the coroutine is cancelled, the coroutine will not continue to calculate, and no result will be generated. Therefore, calling await after the coroutine is cancelled will throw a JobCancellationException: because the Job has been cancelled.

On the other hand, if you call deferred.await after deferred.cancel nothing will happen because the coroutine has already been processed.

Handling the side effects of coroutine cancellation

Suppose you want to perform some specific action after the coroutine is cancelled, such as closing resources that may be in use, logging the cancellation, or executing some other cleanup code. There are several ways to do this:

1. Check !isActive

If you check isActive regularly, you can clean up resources once you break out of the while loop. The previous code can be updated to the following version:

 while (i <   5 && isActive) {
 if (…) {
        println(“Hello ${i++}”)
 nextPrintTime += 500L
 }
 } 
  
 // The task handled by the coroutine has completed, so we can do some cleanup
 println("Clean up!")

You can view the full version.

Full version: https://pl.kotl.in/loI9DaIYj

So now, when the coroutine is no longer active, it exits the while loop and can do some cleanup.

2. Try catch finally

Because a CancellationException is thrown when a coroutine is cancelled, we can place the pending task in a try/catch block and then perform any cleanup tasks in a finally block.

 val job = launch {
 try {
 work()
   } catch (e: CancellationException){
      println(“Work canceled!”)
 finally
      println("Clean up!")
 }
 } 
 
 delay(1000L)
 println("Cancel!")
 job.cancel()
 println("Done!")

However, once the cleanup we need to perform is also suspended, the above code will not work anymore, because once the coroutine is in the canceled state, it can no longer be suspended. You can view the full code.

Full code: https://pl.kotl.in/wjPINnWfG

A coroutine in the canceled state cannot be suspended

When the coroutine is cancelled and the suspend function needs to be called, we need to put the cleanup code in a NonCancellable CoroutineContext. This will suspend the running code and keep the coroutine in the cancelled state until the task is completed.

 val job = launch {
 try {
 work()
   } catch (e: CancellationException){
      println(“Work canceled!”)
 finally
      withContext(NonCancellable){
 delay(1000L) // or some other suspend function
         println(“Cleanup done!”)
 }
 }
 } 
 
 delay(1000L)
 println("Cancel!")
 job.cancel()
 println("Done!")

You can check out how it works.

How it works: https://pl.kotl.in/ufZRQSa7o

suspendCancellableCoroutine and invokeOnCancellation

If you convert the callback to a coroutine via the suspendCoroutine method, you should use the suspendCancellableCoroutine method. You can use continuation.invokeOnCancellation to perform cancellation:

 suspend fun work() {
   return suspendCancellableCoroutine { continuation - >  
       continuation.invokeOnCancellation {
 // Handle cleanup
 }
 // The rest of the implementation code
 }

In order to enjoy the benefits of structured concurrency and ensure that we are not performing unnecessary operations, we need to make our code cancellable.

Use CoroutineScopes defined in Jetpack: viewModelScope or lifecycleScope, they will cancel the tasks they handle when the scope is completed. If you are creating your own CoroutineScope, make sure to bind it to the job and call cancel when needed.

Cancellation of coroutine code needs to be cooperative, so update your code to check for coroutine cancellation lazily and avoid unnecessary operations.

Now, you have learned some basic concepts of coroutines in the first part of this series and the cancellation of coroutines in the second part. In the next article, we will continue to explore and study exception handling in the third part. Interested readers, please continue to pay attention to 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