Make JobCancellationException copyable in debug mode

This simplifies trouble-shooting of "what caused cancellation", as you
can print out exception and see its recovered stack trace.

Author: elizarov

kotlinx-coroutines-core/common/test/CoroutineScopeTest.kt

@@ -122,7 +122,8 @@ class CoroutineScopeTest : TestBase() {
                 expectUnreached()
             } catch (e: CancellationException) {
                 expect(5)
-                assertNull(e.cause)
+                val cause = e.cause as JobCancellationException // shall be recovered JCE
+                assertNull(cause.cause)
             }
         }
         repeat(3) { yield() } // let everything to start properly

kotlinx-coroutines-core/common/test/NonCancellableTest.kt

@@ -29,8 +29,9 @@ class NonCancellableTest : TestBase() {
         try {
             job.await()
             expectUnreached()
-        } catch (e: CancellationException) {
-            assertNull(e.cause)
+        } catch (e: JobCancellationException) {
+            val cause = e.cause as JobCancellationException // shall be recovered JCE
+            assertNull(cause.cause)
             finish(6)
         }
     }
@@ -120,7 +121,8 @@ class NonCancellableTest : TestBase() {
             job.await()
             expectUnreached()
         } catch (e: CancellationException) {
-            assertNull(e.cause)
+            val cause = e.cause as JobCancellationException // shall be recovered JCE
+            assertNull(cause.cause)
             finish(7)
         }
     }

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

@@ -48,8 +48,9 @@ public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable
      * 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.
+     * An exception can opt-out of copying by returning `null` from this function.
      */
-    public fun createCopy(): T
+    public fun createCopy(): T?
 }
 
 /**

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

@@ -41,7 +41,7 @@ internal actual class JobCancellationException public actual constructor(
     message: String,
     cause: Throwable?,
     @JvmField internal actual val job: Job
-) : CancellationException(message) {
+) : CancellationException(message), CopyableThrowable<JobCancellationException> {
 
     init {
         if (cause != null) initCause(cause)
@@ -60,6 +60,17 @@ internal actual class JobCancellationException public actual constructor(
         return this
     }
 
+    override fun createCopy(): JobCancellationException? {
+        if (DEBUG) {
+            return JobCancellationException(message!!, this, job)
+        }
+
+        /*
+         * In non-debug mode we don't copy JCE for speed as it does not have the stack trace anyway.
+         */
+        return null
+    }
+
     override fun toString(): String = "${super.toString()}; job=$job"
 
     @Suppress("DEPRECATION")

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

@@ -20,7 +20,7 @@ private val exceptionCtors: WeakHashMap<Class<out Throwable>, Ctor> = WeakHashMa
 internal fun <E : Throwable> tryCopyException(exception: E): E? {
     // Fast path for CopyableThrowable
     if (exception is CopyableThrowable<*>) {
-        return runCatching { exception.createCopy() as E }.getOrNull()
+        return runCatching { exception.createCopy() as E? }.getOrNull()
     }
     // Use cached ctor if found
     cacheLock.read { exceptionCtors[exception.javaClass] }?.let { cachedCtor ->

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

@@ -171,8 +171,10 @@ class WithContextExceptionHandlingTest(private val mode: Mode) : TestBase() {
     @Test
     fun testCancel() = runTest {
         runOnlyCancellation(null) { e ->
-            assertNull(e.cause)
+            val cause = e.cause as JobCancellationException // shall be recovered JCE
+            assertNull(cause.cause)
             assertTrue(e.suppressed.isEmpty())
+            assertTrue(cause.suppressed.isEmpty())
         }
     }