Introduce test module with testable main dispatcher (#749)

Introduce kotlinx-coroutines-test module with API to set Dispatchers.Main 

  * Dispatchers.setMain and Dispatchers.resetMain extensions
  * Use real factory in HandlerDispatcher instead of using initialized-once statics (prevent ExceptionInInitializerError)
  * Improve MissingCoroutineDispatcher diagnostic
  * Do not cache failed results in test dispatcher to allow reusing it between tests 
  * Deprecate HandlerDispatcher.Main (was accessible only fom Java API)

Fixes #746
Fixed #810

Author: qwwdfsad

README.md

@@ -32,6 +32,8 @@ GlobalScope.launch {
 * [core](core/README.md) — Kotlin/JVM implementation of common coroutines with additional features:
   * `Dispatchers.IO` dispatcher for blocking coroutines;
   * `Executor.asCoroutineDispatcher()` extension, custom thread pools, and more.
+* [test](core/README.md) — test utilities for coroutines, currently with one feature:
+  * `MainDispatcherInjector.inject()` to override `Dispatchers.Main` in tests.
 * [debug](core/README.md) — debug utilities for coroutines.
   * `DebugProbes` API to probe, keep track of, print and dump active coroutines.
 * [js](js/README.md) — Kotlin/JS implementation of common coroutines with `Promise` support.

binary-compatibility-validator/build.gradle

@@ -13,6 +13,7 @@ dependencies {
     testCompile "org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version"
 
     testArtifacts project(':kotlinx-coroutines-core')
+    testArtifacts project(':kotlinx-coroutines-test')
     testArtifacts project(':kotlinx-coroutines-debug')
 
     testArtifacts project(':kotlinx-coroutines-reactive')

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

@@ -0,0 +1,5 @@
+public final class kotlinx/coroutines/test/TestDispatchers {
+	public static final fun resetMain (Lkotlinx/coroutines/Dispatchers;)V
+	public static final fun setMain (Lkotlinx/coroutines/Dispatchers;Lkotlinx/coroutines/CoroutineDispatcher;)V
+}
+

binary-compatibility-validator/resources/api.properties

@@ -2,7 +2,7 @@
 # Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-module.roots=core integration native reactive ui
+module.roots=core integration native reactive ui test
 module.marker=build.gradle
 module.ignore=kotlinx-coroutines-rx-example stdlib-stubs
 

build.gradle

@@ -155,8 +155,7 @@ configure(subprojects.findAll { !internal.contains(it.name) && it.name != 'kotli
 
 // --------------- Configure sub-projects that are published ---------------
 
-// todo: native is not published yet
-def unpublished = internal + ['kotlinx-coroutines-rx-example', 'example-frontend-js']
+def unpublished = internal + ['kotlinx-coroutines-rx-example', 'example-frontend-js', 'android-unit-tests']
 
 def core_docs_url = "https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/"
 def core_docs_file = "$projectDir/core/kotlinx-coroutines-core/build/dokka/kotlinx-coroutines-core/package-list"

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

@@ -11,5 +11,14 @@ import kotlinx.coroutines.*
 public interface MainDispatcherFactory {
     val loadPriority: Int // higher priority wins
 
-    fun createDispatcher(): MainCoroutineDispatcher
+    /**
+     * Creates the main dispatcher. [allFactories] parameter contains all factories found by service loader.
+     * This method is not guaranteed to be idempotent.
+     */
+    fun createDispatcher(allFactories: List<MainDispatcherFactory>): MainCoroutineDispatcher
+
+    /**
+     * Hint used along with error message when the factory failed to create a dispatcher.
+     */
+    fun hintOnError(): String? = null
 }

core/README.md

@@ -6,4 +6,6 @@ Module name below corresponds to the artifact name in Maven/Gradle.
 ## Modules
 
 * [kotlinx-coroutines-core](kotlinx-coroutines-core/README.md) — core coroutine builders and synchronization primitives. 
-* [kotlinx-coroutines-debug](kotlinx-coroutines-debug/README.md) — coroutines debug utilities.
+* [kotlinx-coroutines-debug](kotlinx-coroutines-debug/README.md) — coroutines debug utilities.
+* [kotlinx-coroutines-test](kotlinx-coroutines-test/README.md) — coroutines test utilities such as settable Main dispatcher.
+

core/kotlinx-coroutines-core/resources/META-INF/proguard/coroutines.pro

@@ -1,6 +1,7 @@
 # ServiceLoader support
 -keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
 -keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
+-keepnames class kotlinx.coroutines.test.internal.InjectableDispatcherFactory {}
 
 # Most of volatile fields are updated with AFU and should not be mangled
 -keepclassmembernames class kotlinx.** {

core/kotlinx-coroutines-core/src/Dispatchers.kt

@@ -89,47 +89,3 @@ public actual object Dispatchers {
     @JvmStatic
     public val IO: CoroutineDispatcher = DefaultScheduler.IO
 }
-
-// Lazy loader for the main dispatcher
-private object MainDispatcherLoader {
-    @JvmField
-    val dispatcher: MainCoroutineDispatcher =
-        MainDispatcherFactory::class.java.let { clz ->
-            ServiceLoader.load(clz, clz.classLoader).toList()
-        }.maxBy { it.loadPriority }?.tryCreateDispatcher() ?: MissingMainCoroutineDispatcher(null)
-
-    /**
-     * If anything goes wrong while trying to create main dispatcher (class not found,
-     * initialization failed, etc), then replace the main dispatcher with a special
-     * stub that throws an error message on any attempt to actually use it.
-     */
-    private fun MainDispatcherFactory.tryCreateDispatcher(): MainCoroutineDispatcher =
-        try {
-            createDispatcher()
-        } catch (cause: Throwable) {
-            MissingMainCoroutineDispatcher(cause)
-        }
-}
-
-private class MissingMainCoroutineDispatcher(val cause: Throwable?) : MainCoroutineDispatcher(), Delay {
-    override val immediate: MainCoroutineDispatcher get() = this
-
-    override fun dispatch(context: CoroutineContext, block: Runnable) =
-        missing()
-
-    override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) =
-        missing()
-
-    private fun missing() {
-        if  (cause == null) {
-            throw IllegalStateException(
-                "Module with the Main dispatcher is missing. " +
-                    "Add dependency providing the Main dispatcher, e.g. 'kotlinx-coroutines-android'"
-            )
-        } else {
-            throw IllegalStateException("Module with the Main dispatcher had failed to initialize", cause)
-        }
-    }
-
-    override fun toString(): String = "Main[missing${if (cause != null) ", cause=$cause" else ""}]"
-}

core/kotlinx-coroutines-core/src/internal/MainDispatchers.kt

@@ -0,0 +1,92 @@
+package kotlinx.coroutines.internal
+
+import kotlinx.coroutines.*
+import java.util.*
+import kotlin.coroutines.*
+
+// Lazy loader for the main dispatcher
+internal object MainDispatcherLoader {
+    @JvmField
+    val dispatcher: MainCoroutineDispatcher = loadMainDispatcher()
+
+    private fun loadMainDispatcher(): MainCoroutineDispatcher {
+        return try {
+            val factories = MainDispatcherFactory::class.java.let { clz ->
+                ServiceLoader.load(clz, clz.classLoader).toList()
+            }
+
+            factories.maxBy { it.loadPriority }?.tryCreateDispatcher(factories)
+                ?: MissingMainCoroutineDispatcher(null)
+        } catch (e: Throwable) {
+            // Service loader can throw an exception as well
+            MissingMainCoroutineDispatcher(e)
+        }
+    }
+}
+
+/**
+ * If anything goes wrong while trying to create main dispatcher (class not found,
+ * initialization failed, etc), then replace the main dispatcher with a special
+ * stub that throws an error message on any attempt to actually use it.
+ */
+@InternalCoroutinesApi
+public fun MainDispatcherFactory.tryCreateDispatcher(factories: List<MainDispatcherFactory>): MainCoroutineDispatcher =
+    try {
+        createDispatcher(factories)
+    } catch (cause: Throwable) {
+        MissingMainCoroutineDispatcher(cause, hintOnError())
+    }
+
+/** @suppress */
+@InternalCoroutinesApi
+public fun MainCoroutineDispatcher.isMissing(): Boolean = this is MissingMainCoroutineDispatcher
+
+private class MissingMainCoroutineDispatcher(
+    private val cause: Throwable?,
+    private val errorHint: String? = null
+) : MainCoroutineDispatcher(), Delay {
+
+    override val immediate: MainCoroutineDispatcher get() = this
+
+    override fun isDispatchNeeded(context: CoroutineContext): Boolean {
+        missing()
+    }
+
+    override suspend fun delay(time: Long) {
+        missing()
+    }
+
+    override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+        missing()
+    }
+
+    override fun dispatch(context: CoroutineContext, block: Runnable) =
+        missing()
+
+    override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) =
+        missing()
+
+    private fun missing(): Nothing {
+        if  (cause == null) {
+            throw IllegalStateException(
+                "Module with the Main dispatcher is missing. " +
+                        "Add dependency providing the Main dispatcher, e.g. 'kotlinx-coroutines-android'"
+            )
+        } else {
+            val message = "Module with the Main dispatcher had failed to initialize" + (errorHint?.let { ". $it" } ?: "")
+            throw IllegalStateException(message, cause)
+        }
+    }
+
+    override fun toString(): String = "Main[missing${if (cause != null) ", cause=$cause" else ""}]"
+}
+
+@InternalCoroutinesApi
+public object MissingMainCoroutineDispatcherFactory : MainDispatcherFactory {
+    override val loadPriority: Int
+        get() = -1
+
+    override fun createDispatcher(allFactories: List<MainDispatcherFactory>): MainCoroutineDispatcher {
+       return MissingMainCoroutineDispatcher(null)
+    }
+}