In the test module, collect and report the actual uncaught exceptions

integration-testing/src/jvmCoreTest/kotlin/ListAllCoroutineThrowableSubclassesTest.kt

@@ -27,7 +27,8 @@ class ListAllCoroutineThrowableSubclassesTest {
         "kotlinx.coroutines.JobCancellationException",
         "kotlinx.coroutines.internal.UndeliveredElementException",
         "kotlinx.coroutines.CompletionHandlerException",
-        "kotlinx.coroutines.DiagnosticCoroutineContextException",
+        "kotlinx.coroutines.internal.DiagnosticCoroutineContextException",
+        "kotlinx.coroutines.internal.ExceptionSuccessfullyProcessed",
         "kotlinx.coroutines.CoroutinesInternalError",
         "kotlinx.coroutines.channels.ClosedSendChannelException",
         "kotlinx.coroutines.channels.ClosedReceiveChannelException",

kotlinx-coroutines-core/common/src/CoroutineExceptionHandler.kt

@@ -4,10 +4,9 @@
 
 package kotlinx.coroutines
 
+import kotlinx.coroutines.internal.*
 import kotlin.coroutines.*
 
-internal expect fun handleCoroutineExceptionImpl(context: CoroutineContext, exception: Throwable)
-
 /**
  * Helper function for coroutine builder implementations to handle uncaught and unexpected exceptions in coroutines,
  * that could not be otherwise handled in a normal way through structured concurrency, saving them to a future, and
@@ -26,11 +25,11 @@ public fun handleCoroutineException(context: CoroutineContext, exception: Throwa
             return
         }
     } catch (t: Throwable) {
-        handleCoroutineExceptionImpl(context, handlerException(exception, t))
+        handleUncaughtCoroutineException(context, handlerException(exception, t))
         return
     }
     // If a handler is not present in the context or an exception was thrown, fallback to the global handler
-    handleCoroutineExceptionImpl(context, exception)
+    handleUncaughtCoroutineException(context, exception)
 }
 
 internal fun handlerException(originalException: Throwable, thrownException: Throwable): Throwable {

kotlinx-coroutines-core/common/src/internal/CoroutineExceptionHandlerImpl.common.kt

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2016-2022 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 kotlin.coroutines.*
+
+/**
+ * The list of globally installed [CoroutineExceptionHandler] instances that will be notified of any exceptions that
+ * were not processed in any other manner.
+ */
+internal expect val platformExceptionHandlers: Collection<CoroutineExceptionHandler>
+
+/**
+ * Ensures that the given [callback] is present in the [platformExceptionHandlers] list.
+ */
+internal expect fun ensurePlatformExceptionHandlerLoaded(callback: CoroutineExceptionHandler)
+
+/**
+ * The platform-dependent global exception handler, used so that the exception is logged at least *somewhere*.
+ */
+internal expect fun propagateExceptionFinalResort(exception: Throwable)
+
+/**
+ * Deal with exceptions that happened in coroutines and weren't programmatically dealt with.
+ *
+ * First, it notifies every [CoroutineExceptionHandler] in the [platformExceptionHandlers] list.
+ * If one of them throws [ExceptionSuccessfullyProcessed], it means that that handler believes that the exception was
+ * dealt with sufficiently well and doesn't need any further processing.
+ * Otherwise, the platform-dependent global exception handler is also invoked.
+ */
+internal fun handleUncaughtCoroutineException(context: CoroutineContext, exception: Throwable) {
+    // use additional extension handlers
+    for (handler in platformExceptionHandlers) {
+        try {
+            handler.handleException(context, exception)
+        } catch (_: ExceptionSuccessfullyProcessed) {
+            return
+        } catch (t: Throwable) {
+            propagateExceptionFinalResort(handlerException(exception, t))
+        }
+    }
+
+    try {
+        exception.addSuppressed(DiagnosticCoroutineContextException(context))
+    } catch (e: Throwable) {
+        // addSuppressed is never user-defined and cannot normally throw with the only exception being OOM
+        // we do ignore that just in case to definitely deliver the exception
+    }
+    propagateExceptionFinalResort(exception)
+}
+
+/**
+ * Private exception that is added to suppressed exceptions of the original exception
+ * when it is reported to the last-ditch current thread 'uncaughtExceptionHandler'.
+ *
+ * The purpose of this exception is to add an otherwise inaccessible diagnostic information and to
+ * be able to poke the context of the failing coroutine in the debugger.
+ */
+internal expect class DiagnosticCoroutineContextException(context: CoroutineContext) : RuntimeException
+
+/**
+ * A dummy exception that signifies that the exception was successfully processed by the handler and no further
+ * action is required.
+ *
+ * Would be nicer if [CoroutineExceptionHandler] could return a boolean, but that would be a breaking change.
+ * For now, we will take solace in knowledge that such exceptions are exceedingly rare, even rarer than globally
+ * uncaught exceptions in general.
+ */
+internal object ExceptionSuccessfullyProcessed : Exception()

kotlinx-coroutines-core/js/src/internal/CoroutineExceptionHandlerImpl.kt

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2016-2022 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 kotlin.coroutines.*
+
+private val platformExceptionHandlers_ = mutableSetOf<CoroutineExceptionHandler>()
+
+internal actual val platformExceptionHandlers: Collection<CoroutineExceptionHandler>
+    get() = platformExceptionHandlers_
+
+internal actual fun ensurePlatformExceptionHandlerLoaded(callback: CoroutineExceptionHandler) {
+    platformExceptionHandlers_ += callback
+}
+
+internal actual fun propagateExceptionFinalResort(exception: Throwable) {
+    // log exception
+    console.error(exception)
+}
+
+internal actual class DiagnosticCoroutineContextException actual constructor(context: CoroutineContext) :
+    RuntimeException(context.toString())
+

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

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2016-2022 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.internal
+
+import java.util.*
+import kotlinx.coroutines.*
+import kotlin.coroutines.*
+
+/**
+ * A list of globally installed [CoroutineExceptionHandler] instances.
+ *
+ * Note that Android may have dummy [Thread.contextClassLoader] which is used by one-argument [ServiceLoader.load] function,
+ * see (https://stackoverflow.com/questions/13407006/android-class-loader-may-fail-for-processes-that-host-multiple-applications).
+ * So here we explicitly use two-argument `load` with a class-loader of [CoroutineExceptionHandler] class.
+ *
+ * We are explicitly using the `ServiceLoader.load(MyClass::class.java, MyClass::class.java.classLoader).iterator()`
+ * form of the ServiceLoader call to enable R8 optimization when compiled on Android.
+ */
+internal actual val platformExceptionHandlers: Collection<CoroutineExceptionHandler> = ServiceLoader.load(
+    CoroutineExceptionHandler::class.java,
+    CoroutineExceptionHandler::class.java.classLoader
+).iterator().asSequence().toList()
+
+internal actual fun ensurePlatformExceptionHandlerLoaded(callback: CoroutineExceptionHandler) {
+    // we use JVM's mechanism of ServiceLoader, so this should be a no-op on JVM.
+    // The only thing we do is make sure that the ServiceLoader did work correctly.
+    check(callback in platformExceptionHandlers) { "Exception handler was not found via a ServiceLoader" }
+}
+
+internal actual fun propagateExceptionFinalResort(exception: Throwable) {
+    // use the thread's handler
+    val currentThread = Thread.currentThread()
+    currentThread.uncaughtExceptionHandler.uncaughtException(currentThread, exception)
+}
+
+// This implementation doesn't store a stacktrace, which is good because a stacktrace doesn't make sense for this.
+internal actual class DiagnosticCoroutineContextException actual constructor(@Transient private val context: CoroutineContext) : RuntimeException() {
+    override fun getLocalizedMessage(): String {
+        return context.toString()
+    }
+
+    override fun fillInStackTrace(): Throwable {
+        // Prevent Android <= 6.0 bug, #1866
+        stackTrace = emptyArray()
+        return this
+    }
+}

kotlinx-coroutines-core/native/src/internal/CoroutineExceptionHandlerImpl.kt

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2016-2022 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 kotlin.coroutines.*
+import kotlin.native.*
+
+private val lock = SynchronizedObject()
+
+internal actual val platformExceptionHandlers: Collection<CoroutineExceptionHandler>
+    get() = synchronized(lock) { platformExceptionHandlers_ }
+
+private val platformExceptionHandlers_ = mutableSetOf<CoroutineExceptionHandler>()
+
+internal actual fun ensurePlatformExceptionHandlerLoaded(callback: CoroutineExceptionHandler) {
+    synchronized(lock) {
+        platformExceptionHandlers_ += callback
+    }
+}
+
+@OptIn(ExperimentalStdlibApi::class)
+internal actual fun propagateExceptionFinalResort(exception: Throwable) {
+    // log exception
+    processUnhandledException(exception)
+}
+
+internal actual class DiagnosticCoroutineContextException actual constructor(context: CoroutineContext) :
+    RuntimeException(context.toString())

kotlinx-coroutines-test/common/src/TestScope.kt

@@ -226,6 +226,14 @@ internal class TestScopeImpl(context: CoroutineContext) :
                 throw IllegalStateException("Only a single call to `runTest` can be performed during one test.")
             entered = true
             check(!finished)
+            /** the order is important: [reportException] is only guaranteed not to throw if [entered] is `true` but
+             * [finished] is `false`.
+             * However, we also want [uncaughtExceptions] to be queried after the callback is registered,
+             * because the exception collector will be able to report the exceptions that arrived before this test but
+             * after the previous one, and learning about such exceptions as soon is possible is nice. */
+            @Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
+            run { ensurePlatformExceptionHandlerLoaded(ExceptionCollector) }
+            ExceptionCollector.addOnExceptionCallback(lock, this::reportException)
             uncaughtExceptions
         }
         if (exceptions.isNotEmpty()) {
@@ -239,6 +247,8 @@ internal class TestScopeImpl(context: CoroutineContext) :
     /** Called at the end of the test. May only be called once. Returns the list of caught unhandled exceptions. */
     fun leave(): List<Throwable> = synchronized(lock) {
         check(entered && !finished)
+        /** After [finished] becomes `true`, it is no longer valid to have [reportException] as the callback. */
+        ExceptionCollector.removeOnExceptionCallback(lock)
         finished = true
         uncaughtExceptions
     }
@@ -247,6 +257,8 @@ internal class TestScopeImpl(context: CoroutineContext) :
     fun legacyLeave(): List<Throwable> {
         val exceptions = synchronized(lock) {
             check(entered && !finished)
+            /** After [finished] becomes `true`, it is no longer valid to have [reportException] as the callback. */
+            ExceptionCollector.removeOnExceptionCallback(lock)
             finished = true
             uncaughtExceptions
         }