Kotlin Help

Coroutine exceptions handling

This section covers exception handling and cancellation on exceptions. We already know that a cancelled coroutine throws CancellationException in suspension points and that it is ignored by the coroutines' machinery. Here we look at what happens if an exception is thrown during cancellation or multiple children of the same coroutine throw an exception.

Exception propagation

Coroutine builders come in two flavors: propagating exceptions automatically (launch) or exposing them to users (async andproduce). When these builders are used to create aroot coroutine, that is not achild of another coroutine, the former builders treat exceptions asuncaught exceptions, similar to Java'sThread.uncaughtExceptionHandler, while the latter are relying on the user to consume the final exception, for example viaawait orreceive (produce andreceive are covered inChannels section).

It can be demonstrated by a simple example that creates root coroutines using theGlobalScope:

GlobalScope is a delicate API that can backfire in non-trivial ways. Creating a root coroutine for the whole application is one of the rare legitimate uses forGlobalScope, so you must explicitly opt-in into usingGlobalScope with@OptIn(DelicateCoroutinesApi::class).

import kotlinx.coroutines.*//sampleStart@OptIn(DelicateCoroutinesApi::class)fun main() = runBlocking { val job = GlobalScope.launch { // root coroutine with launch println("Throwing exception from launch") throw IndexOutOfBoundsException() // Will be printed to the console by Thread.defaultUncaughtExceptionHandler } job.join() println("Joined failed job") val deferred = GlobalScope.async { // root coroutine with async println("Throwing exception from async") throw ArithmeticException() // Nothing is printed, relying on user to call await } try { deferred.await() println("Unreached") } catch (e: ArithmeticException) { println("Caught ArithmeticException") }}//sampleEnd

You can get the full code here.

The output of this code is (withdebug):

Throwing exception from launchException in thread "DefaultDispatcher-worker-1 @coroutine#2" java.lang.IndexOutOfBoundsExceptionJoined failed jobThrowing exception from asyncCaught ArithmeticException

CoroutineExceptionHandler

It is possible to customize the default behavior of printinguncaught exceptions to the console.CoroutineExceptionHandler context element on aroot coroutine can be used as a genericcatch block for this root coroutine and all its children where custom exception handling may take place. It is similar toThread.uncaughtExceptionHandler. You cannot recover from the exception in theCoroutineExceptionHandler. The coroutine had already completed with the corresponding exception when the handler is called. Normally, the handler is used to log the exception, show some kind of error message, terminate, and/or restart the application.

CoroutineExceptionHandler is invoked only onuncaught exceptions — exceptions that were not handled in any other way. In particular, allchildren coroutines (coroutines created in the context of anotherJob) delegate handling of their exceptions to their parent coroutine, which also delegates to the parent, and so on until the root, so theCoroutineExceptionHandler installed in their context is never used. In addition to that,async builder always catches all exceptions and represents them in the resultingDeferred object, so itsCoroutineExceptionHandler has no effect either.

Coroutines running in supervision scope do not propagate exceptions to their parent and are excluded from this rule. A further Supervision section of this document gives more details.

import kotlinx.coroutines.*@OptIn(DelicateCoroutinesApi::class)fun main() = runBlocking {//sampleStart val handler = CoroutineExceptionHandler { _, exception -> println("CoroutineExceptionHandler got $exception") } val job = GlobalScope.launch(handler) { // root coroutine, running in GlobalScope throw AssertionError() } val deferred = GlobalScope.async(handler) { // also root, but async instead of launch throw ArithmeticException() // Nothing will be printed, relying on user to call deferred.await() } joinAll(job, deferred)//sampleEnd }

You can get the full code here.

The output of this code is:

CoroutineExceptionHandler got java.lang.AssertionError

Cancellation and exceptions

Cancellation is closely related to exceptions. Coroutines internally useCancellationException for cancellation, these exceptions are ignored by all handlers, so they should be used only as the source of additional debug information, which can be obtained bycatch block. When a coroutine is cancelled usingJob.cancel, it terminates, but it does not cancel its parent.

import kotlinx.coroutines.*fun main() = runBlocking {//sampleStart val job = launch { val child = launch { try { delay(Long.MAX_VALUE) } finally { println("Child is cancelled") } } yield() println("Cancelling child") child.cancel() child.join() yield() println("Parent is not cancelled") } job.join()//sampleEnd }

You can get the full code here.

The output of this code is:

Cancelling childChild is cancelledParent is not cancelled

If a coroutine encounters an exception other thanCancellationException, it cancels its parent with that exception. This behaviour cannot be overridden and is used to provide stable coroutines hierarchies forstructured concurrency.CoroutineExceptionHandler implementation is not used for child coroutines.

In these examples,CoroutineExceptionHandler is always installed to a coroutine that is created inGlobalScope. It does not make sense to install an exception handler to a coroutine that is launched in the scope of the mainrunBlocking, since the main coroutine is going to be always cancelled when its child completes with exception despite the installed handler.

The original exception is handled by the parent only when all its children terminate, which is demonstrated by the following example.

import kotlinx.coroutines.*@OptIn(DelicateCoroutinesApi::class)fun main() = runBlocking {//sampleStart val handler = CoroutineExceptionHandler { _, exception -> println("CoroutineExceptionHandler got $exception") } val job = GlobalScope.launch(handler) { launch { // the first child try { delay(Long.MAX_VALUE) } finally { withContext(NonCancellable) { println("Children are cancelled, but exception is not handled until all children terminate") delay(100) println("The first child finished its non cancellable block") } } } launch { // the second child delay(10) println("Second child throws an exception") throw ArithmeticException() } } job.join()//sampleEnd }

You can get the full code here.

The output of this code is:

Second child throws an exceptionChildren are cancelled, but exception is not handled until all children terminateThe first child finished its non cancellable blockCoroutineExceptionHandler got java.lang.ArithmeticException

Exceptions aggregation

When multiple children of a coroutine fail with an exception, the general rule is "the first exception wins", so the first exception gets handled. All additional exceptions that happen after the first one are attached to the first exception as suppressed ones.

import kotlinx.coroutines.*import java.io.*@OptIn(DelicateCoroutinesApi::class)fun main() = runBlocking { val handler = CoroutineExceptionHandler { _, exception -> println("CoroutineExceptionHandler got $exception with suppressed ${exception.suppressed.contentToString()}") } val job = GlobalScope.launch(handler) { launch { try { delay(Long.MAX_VALUE) // it gets cancelled when another sibling fails with IOException } finally { throw ArithmeticException() // the second exception } } launch { delay(100) throw IOException() // the first exception } delay(Long.MAX_VALUE) } job.join() }

You can get the full code here.

The output of this code is:

CoroutineExceptionHandler got java.io.IOException with suppressed [java.lang.ArithmeticException]

Note that this mechanism currently only works on Java version 1.7+. The JS and Native restrictions are temporary and will be lifted in the future.

Cancellation exceptions are transparent and are unwrapped by default:

import kotlinx.coroutines.*import java.io.*@OptIn(DelicateCoroutinesApi::class)fun main() = runBlocking {//sampleStart val handler = CoroutineExceptionHandler { _, exception -> println("CoroutineExceptionHandler got $exception") } val job = GlobalScope.launch(handler) { val innerJob = launch { // all this stack of coroutines will get cancelled launch { launch { throw IOException() // the original exception } } } try { innerJob.join() } catch (e: CancellationException) { println("Rethrowing CancellationException with original cause") throw e // cancellation exception is rethrown, yet the original IOException gets to the handler } } job.join()//sampleEnd }

You can get the full code here.

The output of this code is:

Rethrowing CancellationException with original causeCoroutineExceptionHandler got java.io.IOException

Supervision

As we have studied before, cancellation is a bidirectional relationship propagating through the whole hierarchy of coroutines. Let us take a look at the case when unidirectional cancellation is required.

A good example of such a requirement is a UI component with the job defined in its scope. If any of the UI's child tasks have failed, it is not always necessary to cancel (effectively kill) the whole UI component, but if the UI component is destroyed (and its job is cancelled), then it is necessary to cancel all child jobs as their results are no longer needed.

Another example is a server process that spawns multiple child jobs and needs tosupervise their execution, tracking their failures and only restarting the failed ones.

Supervision job

TheSupervisorJob can be used for these purposes. It is similar to a regularJob with the only exception that cancellation is propagated only downwards. This can easily be demonstrated using the following example:

import kotlinx.coroutines.*fun main() = runBlocking {//sampleStart val supervisor = SupervisorJob() with(CoroutineScope(coroutineContext + supervisor)) { // launch the first child -- its exception is ignored for this example (don't do this in practice!) val firstChild = launch(CoroutineExceptionHandler { _, _ -> }) { println("The first child is failing") throw AssertionError("The first child is cancelled") } // launch the second child val secondChild = launch { firstChild.join() // Cancellation of the first child is not propagated to the second child println("The first child is cancelled: ${firstChild.isCancelled}, but the second one is still active") try { delay(Long.MAX_VALUE) } finally { // But cancellation of the supervisor is propagated println("The second child is cancelled because the supervisor was cancelled") } } // wait until the first child fails & completes firstChild.join() println("Cancelling the supervisor") supervisor.cancel() secondChild.join() }//sampleEnd}

You can get the full code here.

The output of this code is:

The first child is failingThe first child is cancelled: true, but the second one is still activeCancelling the supervisorThe second child is cancelled because the supervisor was cancelled

Supervision scope

Instead ofcoroutineScope, we can usesupervisorScope forscoped concurrency. It propagates the cancellation in one direction only and cancels all its children only if it failed itself. It also waits for all children before completion just likecoroutineScope does.

import kotlin.coroutines.*import kotlinx.coroutines.*fun main() = runBlocking {//sampleStart try { supervisorScope { val child = launch { try { println("The child is sleeping") delay(Long.MAX_VALUE) } finally { println("The child is cancelled") } } // Give our child a chance to execute and print using yield yield() println("Throwing an exception from the scope") throw AssertionError() } } catch(e: AssertionError) { println("Caught an assertion error") }//sampleEnd}

You can get the full code here.

The output of this code is:

The child is sleepingThrowing an exception from the scopeThe child is cancelledCaught an assertion error

Exceptions in supervised coroutines

Another crucial difference between regular and supervisor jobs is exception handling. Every child should handle its exceptions by itself via the exception handling mechanism. This difference comes from the fact that child's failure does not propagate to the parent. It means that coroutines launched directly inside thesupervisorScopedo use theCoroutineExceptionHandler that is installed in their scope in the same way as root coroutines do (see theCoroutineExceptionHandler section for details).

import kotlin.coroutines.*import kotlinx.coroutines.*fun main() = runBlocking {//sampleStart val handler = CoroutineExceptionHandler { _, exception -> println("CoroutineExceptionHandler got $exception") } supervisorScope { val child = launch(handler) { println("The child throws an exception") throw AssertionError() } println("The scope is completing") } println("The scope is completed")//sampleEnd}

You can get the full code here.

The output of this code is:

The scope is completingThe child throws an exceptionCoroutineExceptionHandler got java.lang.AssertionErrorThe scope is completed

16 February 2022

Channels Shared mutable state and concurrency

Movatterモバイル変換

Coroutine exceptions handling

Exception propagation

CoroutineExceptionHandler

Cancellation and exceptions

Exceptions aggregation

Supervision

Supervision job

Supervision scope

Exceptions in supervised coroutines