Обработка исключений в корутинах

Распространение исключений

Конструкторы корутин бывают двух типов: автоматически обрабатывающие исключения (launch и actor) или предоставляющие их пользователю (async и produce). Когда эти конструкторы используются для создания корневой корутины, которая не является дочерней корутиной другой корутины, первые конструкторы обрабатывают исключения как неперехваченные исключения, аналогично Thread.uncaughtExceptionHandler в Java, в то время как последние полагаются на пользователя для обработки конечного исключения, например, через await или receive (produce и receive описаны в разделе Каналы).

Это можно продемонстрировать на простом примере, создающем корневые корутины с помощью GlobalScope:

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

Вывод этого кода (с отладкой):

Throwing exception from launch
Exception in thread "DefaultDispatcher-worker-2 @coroutine#2" java.lang.IndexOutOfBoundsException
Joined failed job
Throwing exception from async
Caught ArithmeticException

CoroutineExceptionHandler

Можно настроить стандартное поведение вывода неперехваченных исключений в консоль. CoroutineExceptionHandler контекстный элемент корневой корутины может использоваться как универсальный catch блок для этой корневой корутины и всех её дочерних корутин, где может выполняться пользовательская обработка исключений. Это аналогично Thread.uncaughtExceptionHandler. Вы не можете восстановить из исключения в CoroutineExceptionHandler. Корутина уже завершилась с соответствующим исключением, когда вызывается обработчик. Обычно обработчик используется для регистрации исключения, отображения сообщения об ошибке, завершения и/или перезапуска приложения.

CoroutineExceptionHandler вызывается только при неперехваченных исключениях — исключениях, которые не были обработаны другим способом. В частности, все дочерние корутины (корутины, созданные в контексте другой Job) делегируют обработку своих исключений родительской корутине, которая также делегирует родительской, и так далее до корневой, поэтому CoroutineExceptionHandler установленный в их контексте никогда не используется. Кроме того, конструктор async всегда перехватывает все исключения и представляет их в результирующем объекте Deferred, поэтому его CoroutineExceptionHandler также не оказывает никакого эффекта.

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    
}

Вывод этого кода:

CoroutineExceptionHandler got java.lang.AssertionError

Отмена и исключения

Отмена тесно связана с исключениями. Корутины внутренне используют CancellationException для отмены, эти исключения игнорируются всеми обработчиками, поэтому они должны использоваться только как источник дополнительной отладочной информации, которая может быть получена с помощью catch блока. Когда корутина отменяется с помощью Job.cancel, она завершается, но не отменяет своего родителя.

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    
}

Вывод этого кода:

Cancelling child
Child is cancelled
Parent is not cancelled

Если корутина сталкивается с исключением, отличным от CancellationException, она отменяет своего родителя с этим исключением. Это поведение не может быть переопределено и используется для обеспечения стабильности иерархии корутин для структурированной конкурентности. Реализация CoroutineExceptionHandler не используется для дочерних корутин.

Исходное исключение обрабатывается родителем только после завершения всех дочерних корутин, что демонстрируется следующим примером.

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 
}

Вывод этого кода:

Second child throws an exception
Children are cancelled, but exception is not handled until all children terminate
The first child finished its non cancellable block
CoroutineExceptionHandler got java.lang.ArithmeticException

Агрегация исключений

Когда несколько дочерних корутин завершаются с исключением, общее правило — «первое исключение побеждает», поэтому обрабатывается первое исключение. Все дополнительные исключения, произошедшие после первого, прикрепляются к первому исключению как подавленные.

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()  
}

Вывод этого кода:

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

Исключения отмены прозрачны и по умолчанию распаковываются:

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 inner = launch { // all this stack of coroutines will get cancelled
            launch {
                launch {
                    throw IOException() // the original exception
                }
            }
        }
        try {
            inner.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    
}

Вывод этого кода:

Rethrowing CancellationException with original cause
CoroutineExceptionHandler got java.io.IOException

Надзор

Как мы изучали ранее, отмена — это двунаправленное отношение, распространяющееся по всей иерархии корутин. Давайте рассмотрим случай, когда требуется однонаправленная отмена.

Хороший пример такого требования — UI-компонент с задачей, определенной в его области видимости. Если любая из дочерних задач UI завершилась ошибкой, не всегда необходимо отменять (фактически убивать) весь UI-компонент, но если UI-компонент уничтожается (и его задача отменяется), то необходимо отменить все дочерние задачи, так как их результаты больше не нужны.

Другой пример — серверный процесс, который порождает множество дочерних задач и должен контролировать их выполнение, отслеживая ошибки и перезапуская только ошибочные.

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
}

The first child is failing
The first child is cancelled: true, but the second one is still active
Cancelling the supervisor
The second child is cancelled because the supervisor was cancelled

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
}

The child is sleeping
Throwing an exception from the scope
The child is cancelled
Caught an assertion error

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
}

The scope is completing
The child throws an exception
CoroutineExceptionHandler got java.lang.AssertionError
The scope is completed