Basic exception stacktrace recovery mechanism

qwwdfsad · qwwdfsad · commit cf24a843dda7 · 2018-12-06T11:34:17.000+03:00
* Implement CoroutineStackFrame in CancellableContinuationImpl, DispatchedContinuation and ScopeCoroutine * On coroutine resumption try to reflectively instantiate exception instance of the same type, but with augmented stacktrace * Recover stacktrace by walking over CoroutineStackFrame * Recover stacktrace on fast-path exceptions without CoroutineStackFrame walking to provide more context to an exception * Unwrap exceptions when doing aggregation in JobSupport * Add kill-switch to disable stacktrace recovery, introduce method to recover stacktrace on the exceptional fast-path * Add `suspendCoroutineOrReturn` on exceptional fast-path in await in order to provide "real" stacktrace Design rationale: All recovery of *suspended* continuations takes place in Dispatched.kt file, the only place where all calls to "resume*" ends up, so we don't have to remember about stacktrace recovery in every primitive we are implementing. But to provide more accurate stacktraces we *have to* recover it on every fast-path for better debuggability. Fixes #493
diff --git a/common/kotlinx-coroutines-core-common/src/internal/Exceptions.common.kt b/common/kotlinx-coroutines-core-common/src/internal/Exceptions.common.kt
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+import kotlin.coroutines.*
+
+/**
+ * Tries to recover stacktrace for given [exception] and [continuation].
+ * Stacktrace recovery tries to restore [continuation] stack frames using its debug metadata with [CoroutineStackFrame] API
+ * and then reflectively instantiate exception of given type with original exception as a cause and
+ * sets new stacktrace for wrapping exception.
+ * Some frames may be missing due to tail-call elimination.
+ *
+ * Works only on JVM with enabled debug-mode.
+ */
+internal expect fun <E: Throwable> recoverStackTrace(exception: E, continuation: Continuation<*>): E
+
+/**
+ * Tries to recover stacktrace for given [exception]. Used in non-suspendable points of awaiting.
+ * Stacktrace recovery tries to instantiate exception of given type with original exception as a cause.
+ * Wrapping exception will have proper stacktrace as it's instantiated in the right context.
+ *
+ * Works only on JVM with enabled debug-mode.
+ */
+internal expect fun <E: Throwable> recoverStackTrace(exception: E): E
+
+// Name conflict with recoverStackTrace
+@Suppress("NOTHING_TO_INLINE")
+internal expect suspend inline fun recoverAndThrow(exception: Throwable): Nothing
+
+/**
+ * The opposite of [recoverStackTrace].
+ * It is guaranteed that `unwrap(recoverStackTrace(e)) === e`
+ */
+internal expect fun <E: Throwable> unwrap(exception: E): E
+
+expect class StackTraceElement
+
+internal expect interface CoroutineStackFrame {
+    public val callerFrame: CoroutineStackFrame?
+    public fun getStackTraceElement(): StackTraceElement?
+}
+
+/**
+ * Marker that indicates that stacktrace of the exception should not be recovered.
+ * Currently internal, but may become public in the future
+ */
+internal interface NonRecoverableThrowable
diff --git a/core/kotlinx-coroutines-core/src/internal/Exceptions.kt b/core/kotlinx-coroutines-core/src/internal/Exceptions.kt
@@ -0,0 +1,137 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+import kotlinx.coroutines.*
+import java.util.*
+import kotlin.coroutines.*
+import kotlin.coroutines.intrinsics.*
+
+internal actual fun <E : Throwable> recoverStackTrace(exception: E): E {
+    if (recoveryDisabled(exception)) {
+        return exception
+    }
+
+    val copy = tryCopyException(exception) ?: return exception
+    return copy.sanitizeStackTrace()
+}
+
+private fun <E : Throwable> E.sanitizeStackTrace(): E {
+    val size = stackTrace.size
+
+    var lastIntrinsic = -1
+    for (i in 0 until size) {
+        val name = stackTrace[i].className
+        if ("kotlinx.coroutines.internal.ExceptionsKt" == name) {
+            lastIntrinsic = i
+        }
+    }
+
+    val startIndex = lastIntrinsic + 1
+    val trace = Array(size - lastIntrinsic) {
+        if (it == 0) {
+            artificialFrame("Current coroutine stacktrace")
+        } else {
+            stackTrace[startIndex + it - 1]
+        }
+    }
+
+    stackTrace = trace
+    return this
+}
+
+internal actual fun <E : Throwable> recoverStackTrace(exception: E, continuation: Continuation<*>): E {
+    if (recoveryDisabled(exception) || continuation !is CoroutineStackFrame) {
+        return exception
+    }
+
+    return recoverFromStackFrame(exception, continuation)
+}
+
+private fun <E : Throwable> recoverFromStackFrame(exception: E, continuation: CoroutineStackFrame): E {
+    val newException = tryCopyException(exception) ?: return exception
+    val stacktrace = createStackTrace(continuation)
+    if (stacktrace.isEmpty()) return exception
+    stacktrace.add(0, artificialFrame("Current coroutine stacktrace"))
+    newException.stackTrace = stacktrace.toTypedArray()
+    return newException
+}
+
+
+@Suppress("NOTHING_TO_INLINE")
+internal actual suspend inline fun recoverAndThrow(exception: Throwable): Nothing {
+    if (recoveryDisabled(exception)) throw exception
+    suspendCoroutineUninterceptedOrReturn<Nothing> {
+        if (it !is CoroutineStackFrame) throw exception
+        throw  recoverFromStackFrame(exception, it)
+    }
+}
+
+internal actual fun <E : Throwable> unwrap(exception: E): E {
+    if (recoveryDisabled(exception)) {
+        return exception
+    }
+
+    val element = exception.stackTrace.firstOrNull() ?: return exception
+    if (element.isArtificial()) {
+        @Suppress("UNCHECKED_CAST")
+        return exception.cause as? E ?: exception
+    } else {
+        return exception
+    }
+}
+
+private fun <E : Throwable> recoveryDisabled(exception: E) =
+    !RECOVER_STACKTRACE || !DEBUG || exception is CancellationException || exception is NonRecoverableThrowable
+
+@Suppress("UNCHECKED_CAST")
+private fun <E : Throwable> tryCopyException(exception: E): E? {
+    /*
+     * Try to reflectively find constructor(), constructor(message, cause) or constructor(cause).
+     * Exceptions are shared among coroutines, so we should copy exception before recovering current stacktrace.
+     */
+    var newException: E? = null
+    try {
+        val constructors = exception.javaClass.constructors.sortedByDescending { it.parameterTypes.size }
+        for (constructor in constructors) {
+            val parameters = constructor.parameterTypes
+            if (parameters.size == 2 && parameters[0] == String::class.java && parameters[1] == Throwable::class.java) {
+                newException = constructor.newInstance(exception.message, exception) as E
+            } else if (parameters.size == 1 && parameters[0] == Throwable::class.java) {
+                newException = constructor.newInstance(exception) as E
+            } else if (parameters.isEmpty()) {
+                newException = (constructor.newInstance() as E).also { it.initCause(exception) }
+            }
+
+            if (newException != null) {
+                break
+            }
+        }
+    } catch (e: Exception) {
+        // Do nothing
+    }
+    return newException
+}
+
+private fun createStackTrace(continuation: CoroutineStackFrame): ArrayList<StackTraceElement> {
+    val stack = ArrayList<StackTraceElement>()
+    continuation.getStackTraceElement()?.let { stack.add(it) }
+
+    var last = continuation
+    while (true) {
+        last = (last as? CoroutineStackFrame)?.callerFrame ?: break
+        last.getStackTraceElement()?.let { stack.add(it) }
+    }
+    return stack
+}
+
+
+internal fun artificialFrame(message: String) = java.lang.StackTraceElement("\b\b\b($message", "\b", "\b", -1)
+internal fun StackTraceElement.isArtificial() = className.startsWith("\b\b\b")
+
+@Suppress("ACTUAL_WITHOUT_EXPECT")
+actual typealias CoroutineStackFrame = kotlin.coroutines.jvm.internal.CoroutineStackFrame
+
+actual typealias StackTraceElement = java.lang.StackTraceElement
diff --git a/core/kotlinx-coroutines-core/test/exceptions/StackTraceRecoveryInHierarchiesTest.kt b/core/kotlinx-coroutines-core/test/exceptions/StackTraceRecoveryInHierarchiesTest.kt
@@ -0,0 +1,85 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.exceptions
+
+import kotlinx.coroutines.*
+import org.junit.Test
+import kotlin.test.*
+
+class StackTraceRecoveryInHierarchiesTest : TestBase() {
+
+    @Test
+    fun testNestedAsync() = runTest {
+        val rootAsync = async(NonCancellable) {
+            expect(1)
+
+            // Just a noise for unwrapping
+            async {
+                expect(2)
+                delay(Long.MAX_VALUE)
+            }
+
+            // Do not catch, fail on cancellation
+            async {
+                expect(3)
+                async {
+                    expect(4)
+                    delay(Long.MAX_VALUE)
+                }
+
+                async {
+                    expect(5)
+                    // 1) await(), catch, verify and rethrow
+                    try {
+                        val nested = async {
+                            expect(6)
+                            throw RecoverableTestException()
+                        }
+
+                        nested.awaitNested()
+                    } catch (e: RecoverableTestException) {
+                        expect(7)
+                        e.verifyException(
+                            "await\$suspendImpl",
+                            "awaitNested",
+                            "\$testNestedAsync\$1\$rootAsync\$1\$2\$2.invokeSuspend"
+                        )
+                        // Just rethrow it
+                        throw e
+                    }
+                }
+            }
+        }
+
+        try {
+            rootAsync.awaitRootLevel()
+        } catch (e: RecoverableTestException) {
+            e.verifyException("await\$suspendImpl", "awaitRootLevel")
+            finish(8)
+        }
+    }
+
+    private suspend fun Deferred<*>.awaitRootLevel() {
+        await()
+        assertTrue(true)
+    }
+
+    private suspend fun Deferred<*>.awaitNested() {
+        await()
+        assertTrue(true)
+    }
+
+    private fun RecoverableTestException.verifyException(vararg expectedTraceElements: String) {
+        // It is "recovered" only once
+        assertEquals(1, depth())
+        val stacktrace = stackTrace.map { it.methodName }.toSet()
+        assertTrue(expectedTraceElements.all { stacktrace.contains(it) })
+    }
+
+    private fun Throwable.depth(): Int {
+        val cause = cause ?: return 0
+        return 1 + cause.depth()
+    }
+}
diff --git a/js/kotlinx-coroutines-core-js/src/internal/Exceptions.kt b/js/kotlinx-coroutines-core-js/src/internal/Exceptions.kt
@@ -0,0 +1,21 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+import kotlin.coroutines.*
+
+internal actual fun <E: Throwable> recoverStackTrace(exception: E, continuation: Continuation<*>): E = exception
+internal actual fun <E: Throwable> recoverStackTrace(exception: E): E = exception
+internal actual suspend inline fun recoverAndThrow(exception: Throwable): Nothing = throw exception
+
+internal actual fun <E : Throwable> unwrap(exception: E): E = exception
+
+@Suppress("unused")
+internal actual interface CoroutineStackFrame {
+    public actual val callerFrame: CoroutineStackFrame?
+    public actual fun getStackTraceElement(): StackTraceElement?
+}
+
+actual typealias StackTraceElement = Any
diff --git a/native/kotlinx-coroutines-core-native/src/internal/Exceptions.kt b/native/kotlinx-coroutines-core-native/src/internal/Exceptions.kt
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+import kotlin.coroutines.*
+
+internal actual fun <E: Throwable> recoverStackTrace(exception: E, continuation: Continuation<*>): E = exception
+internal actual fun <E: Throwable> recoverStackTrace(exception: E): E = exception
+internal actual fun <E : Throwable> unwrap(exception: E): E = exception
+internal actual suspend inline fun recoverAndThrow(exception: Throwable): Nothing = throw exception
+
+@Suppress("unused")
+internal actual interface CoroutineStackFrame {
+    public actual val callerFrame: CoroutineStackFrame?
+    public actual fun getStackTraceElement(): StackTraceElement?
+}
+
+actual typealias StackTraceElement = Any
