Attempt to report uncaught exceptions in the test module (#3449)

When when a `Job` doesn't have a parent, failures in it can not
be reported via structured concurrency. Instead, the mechanism of
unhandled exceptions is used. If there is a
`CoroutineExceptionHandler` in the coroutine context or registered
as a `ServiceLoader` service, this gets notified, and otherwise,
something platform-specific happens: on Native, the program
crashes, and on the JVM, by default, the exception is just logged,
though this is configurable via
`Thread.setUncaughtExceptionHandler`.

With tests on the JVM, this is an issue: we want exceptions not
simply *logged*, we want them to fail the test, and this extends
beyond just coroutines. However, JUnit does not override the
uncaught exception handler, and uncaught exceptions do just get
logged:
<https://stackoverflow.com/questions/36648317/how-to-capture-all-uncaucht-exceptions-on-junit-tests>

This is a problem with a widely-used `viewModelScope` on Android.
This is a scope without a parent, and so the exceptions in it are
uncaught. On Android, such uncaught exceptions crash the app by
default, but in tests, they just get logged. Clearly, without
overriding the behavior of uncaught exceptions, the tests are
lacking. This can be solved on the test writers' side via
`setUncaughtExceptionHandler`, but one has to remember to do that.

In this commit, we attempt to solve this issue for the overwhelming
majority of users. To that end, when the test framework is used,
we collect the uncaught exceptions and report them at the end of a
test. This approach is marginally less robust than
`setUncaughtExceptionHandler`: if an exception happened after the
last test using `kotlinx-coroutines-test`, it won't get reported,
for example.

`CoroutineExceptionHandler` is designed in such a way that, when it
is used in a coroutine context, its presence means that the
exceptions are safe in its care and will not be propagated further,
but when used as a service, it has no such property. We, however,
know that our `CoroutineExceptionHandler` reports the exceptions
properly and they don't need to be further logged, and so we had to
extend the behavior of mechanism for uncaught exception handling so
that the handler throws a new kind of exception if the
exception was processed successfully.

Also, because there's no `ServiceLoader` mechanism on JS or Native,
we had to refactor the whole uncaught exception handling mechanism
a bit in the same vein as we had to adapt the `Main` dispatcher
to `Dispatchers.setMain`: by introducing internal setter APIs that
services have to call manually to register in.

Fixes #1205
as thoroughly as we can, given the circumstances.

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
         }