Отладка корутин

Восстановление трассировки стека для пользовательских исключений

Восстановление трассировки стека может автоматически копировать исключение, если его класс имеет открытый конструктор, принимающий сообщение, причину, оба аргумента или вовсе не принимающий аргументов.

Если вы хотите, чтобы библиотека kotlinx.coroutines восстанавливала трассировку стека исключения, для которого требуются дополнительные аргументы конструктора, например номер строки или код ошибки, реализуйте интерфейс StackTraceRecoverable.

Интерфейс StackTraceRecoverable входит в стандартную библиотеку Kotlin, поэтому его можно реализовать, не добавляя зависимость от библиотеки kotlinx.coroutines.

Чтобы реализовать интерфейс, переопределите функцию copyForStackTraceRecovery(). В переопределённой функции верните новый экземпляр исключения для восстановления трассировки стека или null, если не хотите, чтобы библиотека kotlinx.coroutines копировала исключение.

Эти API являются экспериментальными и требуют явного согласия с помощью аннотации @OptIn(ExperimentalStdlibCoroutineSupportApi::class).

Ниже приведён пример пользовательского исключения, которое сохраняет свойство line при создании нового экземпляра для восстановления трассировки стека:

import kotlinx.coroutines.*
import kotlin.coroutines.ExperimentalStdlibCoroutineSupportApi
import kotlin.coroutines.debug.StackTraceRecoverable

@OptIn(ExperimentalStdlibCoroutineSupportApi::class)
class FileEditException
// The implementation requires a private constructor
// to pass the cause to the IllegalStateException constructor
private constructor(
    val line: Int,
    private val detail: String,
    cause: Throwable?,
) : IllegalStateException("When editing line $line: $detail", cause),
    // Implements StackTraceRecoverable for stack trace recovery
    StackTraceRecoverable<FileEditException> {

    constructor(line: Int, detail: String) : this(line, detail, null)

    // Copies the line number and message details
    override fun copyForStackTraceRecovery(): FileEditException =
        FileEditException(line, detail, this)
}

private fun editFile() {
    throw FileEditException(15, "Unexpected token")
}

suspend fun main() {
    supervisorScope {
        // Starts a new coroutine
        val fileEdit = async(Dispatchers.Default) {
            // Throws the original exception
            editFile()
        }
        
        // Stack trace recovery creates a copy of the exception,
        // adds the calling coroutine's stack frames, and throws the copy
        fileEdit.await()
    }
}

При включённом режиме отладки вывод содержит восстановленную копию, за которой следует исходное исключение в качестве причины.

Добавление зависимости агента отладки

Чтобы использовать агент отладки в проекте, добавьте зависимость kotlinx-coroutines-debug:

// build.gradle.kts
dependencies {
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.11.0")
}

<!-- pom.xml -->
<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-coroutines-debug</artifactId>
    <version>1.11.0</version>
    <scope>test</scope>
</dependency>

Отслеживание корутин с помощью агента отладки

Чтобы начать отслеживать корутины с помощью агента отладки, можно:

• Добавить -javaagent:/path/to/kotlinx-coroutines-debug-1.11.0.jar к параметрам VM, чтобы загрузить агент отладки при запуске приложения.

• Вызвать функцию DebugProbes.install() перед запуском корутин, которые нужно отслеживать.

Когда агент отладки активен, можно использовать следующие API:

• DebugProbes.dumpCoroutines() выводит все активные корутины.

• DebugProbes.dumpCoroutinesInfo() возвращает информацию об активных корутинах.

• DebugProbes.printJob() выводит дамп корутин для иерархии Job.

• DebugProbes.printScope() выводит дамп корутин для иерархии CoroutineScope.

Ниже приведён пример использования агента отладки для вывода активных корутин и иерархии корутин для конкретного Job:

import kotlinx.coroutines.*
import kotlinx.coroutines.debug.*
import kotlin.time.Duration.Companion.seconds

private suspend fun loadAccount() {
    delay(5.seconds)
}

private suspend fun loadPreferences() {
    delay(5.seconds)
}

private suspend fun loadUserProfile() = coroutineScope {
    launch { loadAccount() }
    launch { loadPreferences() }
}

@OptIn(ExperimentalCoroutinesApi::class)
fun main() {
    // Installs the debug agent
    // This is only required if you don't use the -javaagent VM option
    DebugProbes.install()

    runBlocking {
        // Starts a coroutine with two child coroutines
        val loadingJob = launch {
            loadUserProfile()
        }

        // Gives the child coroutines time to suspend
        delay(1.seconds)

        // Prints all active coroutines
        DebugProbes.dumpCoroutines()

        println("============")

        // Prints the loading job and its child coroutines
        DebugProbes.printJob(loadingJob)
    }
}

Если включён режим отладки, пример выведет следующие данные:

Вывод активных корутин при превышении времени ожидания тестов JUnit

Для тестов JUnit можно задать время ожидания с помощью соответствующего API CoroutinesTimeout, в зависимости от версии JUnit. API автоматически устанавливает диагностические пробы. Если тест не завершится до истечения времени ожидания, он выведет все активные корутины и их трассировки стека, а затем завершится с ошибкой.

import kotlinx.coroutines.*
import kotlinx.coroutines.debug.junit4.CoroutinesTimeout
import org.junit.Rule
import org.junit.Test
import kotlin.time.Duration

@OptIn(ExperimentalCoroutinesApi::class)
class UserProfileTest {
    @get:Rule
    val timeout = CoroutinesTimeout.seconds(1)

    private suspend fun loadUserProfile() {
        withContext(Dispatchers.IO) {
            // Simulates an operation that doesn't complete
            delay(Duration.INFINITE)
        }
    }

    @Test
    fun loadsUserProfile() = runBlocking {
        val loadingJob = launch {
            loadUserProfile()
        }

        // Waits for the coroutine, so the test doesn't complete
        loadingJob.join()
    }
}

import kotlinx.coroutines.*
import kotlinx.coroutines.debug.junit5.CoroutinesTimeout
import org.junit.jupiter.api.Test
import kotlin.time.Duration

@OptIn(ExperimentalCoroutinesApi::class)
// Sets a one-second timeout for all test functions in the class
@CoroutinesTimeout(testTimeoutMs = 1_000)
class UserProfileTest {
    private suspend fun loadUserProfile() {
        withContext(Dispatchers.IO) {
            // Simulates an operation that doesn't complete
            delay(Duration.INFINITE)
        }
    }

    @Test
    fun loadsUserProfile() = runBlocking {
        val loadingJob = launch {
            loadUserProfile()
        }

        // Waits for the coroutine, so the test doesn't complete
        loadingJob.join()
    }
}

Устранение конфликтов ресурсов kotlinx-coroutines-debug на Android

Агент отладки не поддерживается на Android.

Модуль kotlinx-coroutines-debug имеет транзитивные зависимости от JNA, JNA Platform, Byte Buddy и Byte Buddy Agent. Некоторые из этих зависимостей содержат ресурсы с одинаковыми путями. При объединении Android ресурсов зависимостей дублирующиеся пути могут вызвать DuplicateRelativeFileException и привести к сбою сборки.

Чтобы устранить сбой сборки и сохранить зависимость kotlinx-coroutines-debug, исключите конфликтующие ресурсы с помощью следующей конфигурации packaging в файле build.gradle.kts:

// build.gradle.kts
android {
    packaging {
        resources {
            // Excludes license files from JNA and JNA Platform
            excludes += setOf(
                "META-INF/AL2.0",
                "META-INF/LGPL2.1",
            )

            // Excludes the ASM license file from Byte Buddy
            excludes += "META-INF/licenses/ASM"

            // Retains one copy of each Byte Buddy Agent file
            pickFirsts += setOf(
                "win32-x86-64/attach_hotspot_windows.dll",
                "win32-x86/attach_hotspot_windows.dll",
            )
        }
    }
}