Initial implementation attempt

Author: dkhalanskyjb

kotlinx-coroutines-core/api/kotlinx-coroutines-core.api

@@ -312,6 +312,13 @@ public final class kotlinx/coroutines/EventLoopKt {
 	public static final fun processNextEventInCurrentThread ()J
 }
 
+public final class kotlinx/coroutines/ExceptionCollector {
+	public static final field INSTANCE Lkotlinx/coroutines/ExceptionCollector;
+	public final fun addOnExceptionCallback (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)V
+	public final fun handleException (Ljava/lang/Throwable;)Z
+	public final fun removeOnExceptionCallback (Ljava/lang/Object;)V
+}
+
 public final class kotlinx/coroutines/ExceptionsKt {
 	public static final fun CancellationException (Ljava/lang/String;Ljava/lang/Throwable;)Ljava/util/concurrent/CancellationException;
 }

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

@@ -4,9 +4,89 @@
 
 package kotlinx.coroutines
 
+import kotlinx.coroutines.internal.*
 import kotlin.coroutines.*
 
-internal expect fun handleCoroutineExceptionImpl(context: CoroutineContext, exception: Throwable)
+internal expect fun propagateExceptionToPlatform(context: CoroutineContext, exception: Throwable)
+
+/**
+ * If [addOnExceptionCallback] is called, the provided callback will be evaluated each time
+ * [handleCoroutineException] is executed and can't find a [CoroutineExceptionHandler] to
+ * process the exception.
+ *
+ * When a callback is registered once, even if it's later removed, the system starts to assume that
+ * other callbacks will eventually be registered, and so collects the exceptions.
+ * Once a new callback is registered, it tries.
+ *
+ * The callbacks in this object are the last resort before relying on platform-dependent
+ * ways to report uncaught exceptions from coroutines.
+ */
+@PublishedApi
+internal object ExceptionCollector {
+    private val lock = SynchronizedObject()
+    private var enabled = false
+    private var unprocessedExceptions = mutableListOf<Throwable>()
+    private val callbacks = mutableMapOf<Any, (Throwable) -> Unit>()
+
+    /**
+     * Registers [callback] to be executed when an uncaught exception happens.
+     * [owner] is a key by which to distinguish different callbacks.
+     */
+    fun addOnExceptionCallback(owner: Any, callback: (Throwable) -> Unit) = synchronized(lock) {
+        enabled = true // never becomes `false` again
+        val previousValue = callbacks.put(owner, callback)
+        assert { previousValue === null }
+        // try to process the exceptions using the newly-registered callback
+        unprocessedExceptions.forEach { reportException(it) }
+        unprocessedExceptions = mutableListOf()
+    }
+
+    /**
+     * Unregisters the callback associated with [owner].
+     */
+    fun removeOnExceptionCallback(owner: Any) = synchronized(lock) {
+        val existingValue = callbacks.remove(owner)
+        assert { existingValue !== null }
+    }
+
+    /**
+     * Tries to handle the exception by propagating it to an interested consumer.
+     * Returns `true` if the exception does not need further processing.
+     *
+     * Doesn't throw.
+     */
+    fun handleException(exception: Throwable): Boolean = synchronized(lock) {
+        if (!enabled) return false
+        if (reportException(exception)) return true
+        /** we don't return the result of the `add` function because we don't have a guarantee
+         * that a callback will eventually appear and collect the unprocessed exceptions, so
+         * we can't consider [exception] to be properly handled. */
+        unprocessedExceptions.add(exception)
+        return false
+    }
+
+    /**
+     * Try to report [exception] to the existing callbacks.
+     */
+    private fun reportException(exception: Throwable): Boolean {
+        var executedACallback = false
+        for (callback in callbacks.values) {
+            callback(exception)
+            executedACallback = true
+            /** We don't leave the function here because we want to fan-out the exceptions to every interested consumer,
+             * it's not enough to have the exception processed by one of them.
+             * The reason is, it's less big of a deal to observe multiple concurrent reports of bad behavior than not
+             * to observe the report in the exact callback that is connected to that bad behavior. */
+        }
+        return executedACallback
+    }
+}
+
+internal fun handleUncaughtCoroutineException(context: CoroutineContext, exception: Throwable) {
+    // TODO: if ANDROID_DETECTED
+    if (!ExceptionCollector.handleException(exception))
+        propagateExceptionToPlatform(context, exception)
+}
 
 /**
  * Helper function for coroutine builder implementations to handle uncaught and unexpected exceptions in coroutines,
@@ -26,11 +106,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/js/src/CoroutineExceptionHandlerImpl.kt

@@ -6,7 +6,7 @@ package kotlinx.coroutines
 
 import kotlin.coroutines.*
 
-internal actual fun handleCoroutineExceptionImpl(context: CoroutineContext, exception: Throwable) {
+internal actual fun propagateExceptionToPlatform(context: CoroutineContext, exception: Throwable) {
     // log exception
     console.error(exception)
 }

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

@@ -41,7 +41,7 @@ private class DiagnosticCoroutineContextException(@Transient private val context
     }
 }
 
-internal actual fun handleCoroutineExceptionImpl(context: CoroutineContext, exception: Throwable) {
+internal actual fun propagateExceptionToPlatform(context: CoroutineContext, exception: Throwable) {
     // use additional extension handlers
     for (handler in handlers) {
         try {

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

@@ -8,7 +8,7 @@ import kotlin.coroutines.*
 import kotlin.native.*
 
 @OptIn(ExperimentalStdlibApi::class)
-internal actual fun handleCoroutineExceptionImpl(context: CoroutineContext, exception: Throwable) {
+internal actual fun propagateExceptionToPlatform(context: CoroutineContext, exception: Throwable) {
     // log exception
     processUnhandledException(exception)
 }

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

@@ -220,6 +220,15 @@ 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 {
+                ExceptionCollector.addOnExceptionCallback(lock, this::reportException)
+            }
             uncaughtExceptions
         }
         if (exceptions.isNotEmpty()) {
@@ -234,6 +243,11 @@ internal class TestScopeImpl(context: CoroutineContext) :
     fun leave(): List<Throwable> {
         val exceptions = synchronized(lock) {
             check(entered && !finished)
+            /** After [finished] becomes `true`, it is no longer valid to have [reportException] as the callback. */
+            @Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
+            run {
+                ExceptionCollector.removeOnExceptionCallback(lock)
+            }
             finished = true
             uncaughtExceptions
         }

kotlinx-coroutines-test/jvm/src/migration/TestCoroutineExceptionHandler.kt

@@ -58,7 +58,7 @@ public class TestCoroutineExceptionHandler :
     override fun handleException(context: CoroutineContext, exception: Throwable) {
         synchronized(_lock) {
             if (_coroutinesCleanedUp) {
-                handleCoroutineExceptionImpl(context, exception)
+                handleUncaughtCoroutineException(context, exception)
             }
             _exceptions += exception
         }