Cancellation and exceptions in coroutines | Introduction to core concepts

In previous articles, we shared with developers some basic knowledge about using coroutines in Android, including background introduction, getting started guide and code practice in Android coroutines. This series of articles "Cancellation and Exceptions in Coroutines" is also related to Android coroutines. We will discuss in depth the knowledge points and techniques about cancellation operations and exception handling in coroutines.

[[332617]]

When we need to avoid unnecessary processing to reduce memory waste and save power, cancellation is particularly important; and proper exception handling is also the key to improving user experience. This article is the basis of the other two articles (the second and third articles will explain coroutine cancellation and exception handling respectively), so it is necessary to first explain some core concepts of coroutines, such as CoroutineScope (coroutine scope), Job (task) and CoroutineContext (coroutine context), so that we can study more deeply.

CoroutineScope

CoroutineScope tracks every coroutine you create via launch or async (these two are extension functions of CoroutineScope). You can cancel the work in progress (the running coroutine) at any time by calling scope.cancel().

• CoroutineScope: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/
• launch: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html
• async: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html

When you want to start or control the lifecycle of a coroutine at a certain level of your application, you need to create a CoroutineScope. For some platforms, such as Android, there are libraries such as KTX that provide CoroutineScope in the lifecycle of some classes, such as viewModelScope and lifecycleScope.

• 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

When creating a CoroutineScope, it takes a CoroutineContext as a constructor parameter. You can create a new scope and coroutine with the following code:

 //Job and Dispatcher have been integrated into CoroutineContext
 // We will introduce it in detail later
 val scope = CoroutineScope (Job() + Dispatchers.Main) 
 
 val job = scope .launch {
 //New coroutine
 }

Job

Job is used to handle coroutines. For each coroutine you create (via launch or async), it returns a Job instance, which is the unique identifier of the coroutine and is responsible for managing the lifecycle of the coroutine. As we saw above, you can pass a Job instance to CoroutineScope to control its lifecycle.

Job：

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

CoroutineContext

CoroutineContext is a set of elements used to define the behavior of a coroutine. It consists of the following items:

• Job: controls the life cycle of the coroutine;
• CoroutineDispatcher: dispatches tasks to appropriate threads;
• CoroutineName: the name of the coroutine, which is useful when debugging;
• CoroutineExceptionHandler: Handles uncaught exceptions, which will be explained in detail in the third article in the future.

CoroutineContext:

thttps://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/-coroutine-context/index.html

So what is the CoroutineContext of the newly created coroutine? We already know that an instance of Job will be created, which will help us control the life cycle of the coroutine. The remaining elements will be inherited from the parent class of CoroutineContext, which may be another coroutine or the CoroutineScope that created the coroutine.

Since CoroutineScope can create coroutines, and you can create more coroutines inside a coroutine, there is an implicit task hierarchy inside. In the following code snippet, in addition to creating a new coroutine through CoroutineScope, let's see how to create more coroutines in a coroutine:

 val scope = CoroutineScope (Job() + Dispatchers.Main) 
 
 val job = scope .launch {
 // The new coroutine will have CoroutineScope as its parent
 val result = async {
 // The new coroutine created by launch will take the current coroutine as its parent
 }.await()
 }

The root of the hierarchy is usually CoroutineScope. Graphically, the hierarchy looks like this:

△ Coroutines are executed in order of task level.

The parent is CoroutineScope or other coroutines

Job Lifecycle

A task can contain a series of states: New, Active, Completing, Completed, Cancelling, and Cancelled. Although we cannot access these states directly, we can access the properties of the Job: isActive, isCancelled, and isCompleted.

△ Job life cycle

If the coroutine is in the active state, an error in the coroutine operation or calling job.cancel() will put the current task into the Cancelling state (isActive = false, isCancelled = true). When all sub-coroutines are completed, the coroutine will enter the Cancelled state, and isCompleted = true.

Resolving the parent CoroutineContext

In the task hierarchy, each coroutine has a parent object, either CoroutineScope or another coroutine. However, in reality, the parent CoroutineContext of a coroutine is different from the CoroutineContext of the parent coroutine, because of the following formula:

Parent context = default value + inherited CoroutineContext + parameters

in:

• Some elements contain default values: Dispatchers.Default is the default CoroutineDispatcher, and "coroutine" as the default CoroutineName;
• The inherited CoroutineContext is CoroutineScope or the CoroutineContext of its parent coroutine;
• Parameters passed into the coroutine builder take precedence over inherited context parameters and will therefore override the corresponding parameter values.

Note: CoroutineContext can be merged using the "+" operator. Since CoroutineContext is composed of a set of elements, the elements on the right side of the plus sign will overwrite the elements on the left side of the plus sign to form the newly created CoroutineContext. For example, (Dispatchers.Main, "name") + (Dispatchers.IO) = (Dispatchers.IO, "name").

Dispatchers.IO: http://dispatchers.io/

For each coroutine created by the CoroutineScope, the CoroutineContext will contain at least these elements. The CoroutineName here is gray because the value comes from the default parameter value. Now we understand what the parent CoroutineContext of the new coroutine looks like. Its actual CoroutineContext is:

New CoroutineContext = parent CoroutineContext + Job()

If we use the CoroutineScope in the figure above, we can create a new coroutine like this:

 val job = scope .launch(Dispatchers.IO) {
 //New coroutine
 }

What does the parent CoroutineContext of the coroutine and its actual CoroutineContext look like? Please see the picture below.

It is impossible for the Job in CoroutineContext and the one in the parent context to be passed through the same instance, because the new coroutine will always get a new instance of Job.

The final parent CoroutineContext will contain Dispatchers.IO instead of the CoroutineDispatcher in the scope object, because it is overwritten by the parameters in the coroutine builder. In addition, note that the Job in the parent CoroutineContext is the Job of the scope object (red), and the new Job instance (green) will be assigned to the CoroutineContext of the new coroutine.

In the third part of our series, CoroutineScope will have another Job implementation called SupervisorJob included in its CoroutineContext, which changes the way CoroutineScope handles exceptions. Therefore, new coroutines created by this scope object will have a SupervisorJob as their parent Job. However, when a coroutine's parent is another coroutine, the parent's Job will still be of type Job.

Now, everyone understands some basic concepts of coroutines. In the next article, we will continue to explore the cancellation of coroutines in the second article and the exception handling of coroutines in the third article. 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