Stacktrace recovery improvements

  * Introduce CopyableThrowable to provide a mechanism for flexible exception cloning
  * Do not reflectively clone exceptions with additional non-static fields

Author: qwwdfsad

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-core.txt

@@ -121,6 +121,10 @@ public final class kotlinx/coroutines/CompletionHandlerException : java/lang/Run
 	public fun <init> (Ljava/lang/String;Ljava/lang/Throwable;)V
 }
 
+public abstract interface class kotlinx/coroutines/CopyableThrowable {
+	public abstract fun createCopy ()Ljava/lang/Throwable;
+}
+
 public final class kotlinx/coroutines/CoroutineContextKt {
 	public static final fun newCoroutineContext (Lkotlinx/coroutines/CoroutineScope;Lkotlin/coroutines/CoroutineContext;)Lkotlin/coroutines/CoroutineContext;
 }

kotlinx-coroutines-core/jvm/src/Debug.kt

@@ -4,8 +4,8 @@
 
 package kotlinx.coroutines
 
-import kotlin.coroutines.Continuation
 import kotlinx.coroutines.internal.*
+import kotlin.coroutines.*
 
 /**
  * Name of the property that controls coroutine debugging. See [newCoroutineContext][CoroutineScope.newCoroutineContext].
@@ -26,6 +26,32 @@ public const val DEBUG_PROPERTY_NAME = "kotlinx.coroutines.debug"
  */
 internal const val STACKTRACE_RECOVERY_PROPERTY_NAME = "kotlinx.coroutines.stacktrace.recovery"
 
+/**
+ * Throwable which can be cloned during stacktrace recovery in a class-specific way.
+ * For additional information about stacktrace recovery see [STACKTRACE_RECOVERY_PROPERTY_NAME]
+ *
+ * Example of usage:
+ * ```
+ * class BadResponseCodeException(val responseCode: Int) : Exception(), CopyableThrowable<BadResponseCodeException> {
+ *
+ *  override fun createCopy(): BadResponseCodeException {
+ *    val result = BadResponseCodeException(responseCode)
+ *    result.initCause(this)
+ *    return result
+ *  }
+ * ```
+ */
+@ExperimentalCoroutinesApi
+public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable<T> {
+
+    /**
+     * Creates a copy of the current instance.
+     * For better debuggability, it is recommended to use original exception as [cause][Throwable.cause] of the resulting one.
+     * Stacktrace of copied exception will be overwritten by stacktrace recovery machinery by [Throwable.setStackTrace] call.
+     */
+    public fun createCopy(): T
+}
+
 /**
  * Automatic debug configuration value for [DEBUG_PROPERTY_NAME]. See [newCoroutineContext][CoroutineScope.newCoroutineContext].
  */

kotlinx-coroutines-core/jvm/src/internal/ExceptionsConstuctor.kt

@@ -4,21 +4,35 @@
 
 package kotlinx.coroutines.internal
 
+import kotlinx.coroutines.*
+import java.lang.reflect.*
 import java.util.*
 import java.util.concurrent.locks.*
 import kotlin.concurrent.*
 
+private val throwableFields = Throwable::class.java.fieldsCountOrDefault(-1)
 private val cacheLock = ReentrantReadWriteLock()
 // Replace it with ClassValue when Java 6 support is over
 private val exceptionConstructors: WeakHashMap<Class<out Throwable>, (Throwable) -> Throwable?> = WeakHashMap()
 
 @Suppress("UNCHECKED_CAST")
 internal fun <E : Throwable> tryCopyException(exception: E): E? {
+    if (exception is CopyableThrowable<*>) {
+        return runCatching { exception.createCopy() as E }.getOrNull()
+    }
+
     val cachedCtor = cacheLock.read {
         exceptionConstructors[exception.javaClass]
     }
 
     if (cachedCtor != null) return cachedCtor(exception) as E?
+    /*
+     * Skip reflective copy if an exception has additional fields (that are usually populated in user-defined constructors)
+     */
+    if (throwableFields != exception.javaClass.fieldsCountOrDefault(0)) {
+        cacheLock.write { exceptionConstructors[exception.javaClass] = { null } }
+        return null
+    }
 
     /*
      * Try to reflectively find constructor(), constructor(message, cause) or constructor(cause).
@@ -43,3 +57,12 @@ internal fun <E : Throwable> tryCopyException(exception: E): E? {
     cacheLock.write { exceptionConstructors[exception.javaClass] = (ctor ?: { null }) }
     return ctor?.invoke(exception) as E?
 }
+
+private fun Class<*>.fieldsCountOrDefault(defaultValue: Int) = kotlin.runCatching { fieldsCount() }.getOrDefault(defaultValue)
+
+private tailrec fun Class<*>.fieldsCount(accumulator: Int = 0): Int {
+    val fieldsCount = declaredFields.count { !Modifier.isStatic(it.modifiers) }
+    val totalFields = accumulator + fieldsCount
+    val superClass = superclass ?: return totalFields
+    return superClass.fieldsCount(totalFields)
+}

kotlinx-coroutines-core/jvm/test/exceptions/StackTraceRecoveryCustomExceptionsTest.kt

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2016-2019 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.*
+
+@Suppress("UNREACHABLE_CODE", "UNUSED", "UNUSED_PARAMETER")
+class StackTraceRecoveryCustomExceptionsTest : TestBase() {
+
+    internal class NonCopyable(val customData: Int) : Throwable() {
+        // Bait
+        public constructor(cause: Throwable) : this(42)
+    }
+
+    internal class Copyable(val customData: Int) : Throwable(), CopyableThrowable<Copyable> {
+        // Bait
+        public constructor(cause: Throwable) : this(42)
+
+        override fun createCopy(): Copyable {
+            val copy = Copyable(customData)
+            copy.initCause(this)
+            return copy
+        }
+    }
+
+    @Test
+    fun testStackTraceNotRecovered() = runTest {
+        try {
+            withContext(wrapperDispatcher(coroutineContext)) {
+                throw NonCopyable(239)
+            }
+            expectUnreached()
+        } catch (e: NonCopyable) {
+            assertEquals(239, e.customData)
+            assertNull(e.cause)
+        }
+    }
+
+    @Test
+    fun testStackTraceRecovered() = runTest {
+        try {
+            withContext(wrapperDispatcher(coroutineContext)) {
+                throw Copyable(239)
+            }
+            expectUnreached()
+        } catch (e: Copyable) {
+            assertEquals(239, e.customData)
+            val cause = e.cause
+            assertTrue(cause is Copyable)
+            assertEquals(239, cause.customData)
+        }
+    }
+}