StackTraceRecoverable

С версии Kotlin: 2.4

@ExperimentalStdlibCoroutineSupportApi
interface StackTraceRecoverable<T : Throwable, StackTraceRecoverable<T>>

Throwable, поддерживающий восстановление трассировки стека и явно предоставляющий процедуру для создания своей копии.

Если объект исключения создаётся в одном параллельном вычислении, сохраняется в общей памяти, а затем используется и повторно выбрасывается в другом параллельном вычислении, трассировка стека вычисления, в котором исключение выбрасывается повторно, отсутствует в трассировке стека исключения.

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

В kotlinx.coroutines такое соглашение доступно на JVM в качестве функции с явным включением, называемой «восстановлением трассировки стека». По умолчанию оно доступно для всех классов исключений, у которых есть один из следующих конструкторов:

• (String, Throwable?)

• (String)

• (Throwable?)

• конструктор без параметров.

Реализация StackTraceRecoverable в подклассе Throwable позволяет создавать копии его экземпляров для восстановления трассировки стека, если асинхронная платформа не может найти подходящий конструктор.

Кроме того, этот интерфейс можно использовать, чтобы отказаться от восстановления трассировки стека даже в случаях, когда асинхронная платформа может эвристически найти процедуру копирования. Для этого copyForStackTraceRecovery должен возвращать null.

В kotlinx.coroutines механизм копирования доступен только на JVM, однако этот интерфейс доступен на всех целевых платформах, чтобы исключения, реализованные в общем коде, также могли поддерживать восстановление трассировки стека на JVM.

Реализация StackTraceRecoverable

Рассмотрим этот класс:

class BadResponseCodeException(val responseCode: Int): Exception()

Поскольку у него есть только конструктор, который не распознаётся kotlinx.coroutines, трассировки стека останутся без изменений.

На JVM для реализации StackTraceRecoverable достаточно добавить ограничение типа и реализовать новый метод:

class BadResponseCodeException(
    val responseCode: Int
): Exception(), StackTraceRecoverable<BadResponseCodeException> {
    override fun copyForStackTraceRecovery(): BadResponseCodeException {
        val result = BadResponseCodeException(responseCode)
        result.initCause(this)
        return result
    }
}

В мультиплатформенном коде initCause недоступен, поэтому выполнить рекомендуемое требование сохранять исходное исключение в качестве причины сложнее. Для этого потребуется отдельный приватный конструктор:

class BadResponseCodeException private constructor(
    val responseCode: Int,
    cause: Throwable?
) : Exception(cause), StackTraceRecoverable<BadResponseCodeException> {

    // The original public constructor
    constructor(responseCode: Int): this(responseCode, null)

    override fun copyForStackTraceRecovery(): BadResponseCodeException =
        BadResponseCodeException(responseCode, this)
}