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

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

Блоки-строители корутин бывают двух типов: автоматически обрабатывающие исключения (launch и actor) или предоставляющие их пользователю (async и produce). Когда эти блоки-строители используются для создания корневой корутины, которая не является дочерней корутиной другой корутины, первые блоки-строители обрабатывают исключения как необработанные исключения, аналогично Java's Thread.uncaughtExceptionHandler, в то время как последние полагаются на пользователя для обработки конечного исключения, например, с помощью 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