Dispatchers are renamed and grouped in the Dispatchers object

README.md

@@ -8,7 +8,7 @@ Library support for Kotlin coroutines with [multiplatform](#multiplatform) suppo
 This is a companion version for Kotlin 1.2.61 release.
 
 ```kotlin
-launch {
+GlobalScope.launch {
     delay(1000)
     println("Hello from Kotlin Coroutines!")
 }
@@ -19,14 +19,12 @@ launch {
 * [common](common/README.md) — common coroutines across all backends:
   * `launch` and `async` coroutine builders;
   * `Job` and `Deferred` light-weight future with cancellation support;
-  * `delay` and `yield` top-level suspending functions.
+  * `delay` and `yield` top-level suspending functions;
   * `Channel` and `Mutex` communication and synchronization primitives;
-  * `produce` coroutine builder;
+  * `produce` and `actor` coroutine builders;
   * `select` expression support and more.
 * [core](core/README.md) — Kotlin/JVM implementation of common coroutines with additional features:
-  * `CommonPool` coroutine context (default on JVM);
-  * `actor` coroutine builder;
-  * `IO` dispatcher for blocking coroutines
+  * `Dispatchers.IO` dispatcher for blocking coroutines.
 * [js](js/README.md) — Kotlin/JS implementation of common coroutines with `Promise` support.
 * [native](native/README.md) — Kotlin/Native implementation of common coroutines with `runBlocking` single-threaded event loop.
 * [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:

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

@@ -3,14 +3,14 @@ public final class kotlinx/coroutines/experimental/android/AndroidExceptionPreHa
 	public fun handleException (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Throwable;)V
 }
 
-public final class kotlinx/coroutines/experimental/android/HandlerContext : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+public final class kotlinx/coroutines/experimental/android/HandlerContext : kotlinx/coroutines/experimental/android/HandlerDispatcher, kotlinx/coroutines/experimental/Delay {
 	public fun <init> (Landroid/os/Handler;Ljava/lang/String;)V
 	public synthetic fun <init> (Landroid/os/Handler;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun awaitFrame (Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
-	public fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
 	public fun equals (Ljava/lang/Object;)Z
-	public final fun getImmediate ()Lkotlinx/coroutines/experimental/android/HandlerContext;
+	public fun getImmediate ()Lkotlinx/coroutines/experimental/android/HandlerContext;
+	public synthetic fun getImmediate ()Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
 	public fun hashCode ()I
 	public fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
 	public fun isDispatchNeeded (Lkotlin/coroutines/experimental/CoroutineContext;)Z
@@ -19,7 +19,19 @@ public final class kotlinx/coroutines/experimental/android/HandlerContext : kotl
 }
 
 public final class kotlinx/coroutines/experimental/android/HandlerContextKt {
-	public static final fun asCoroutineDispatcher (Landroid/os/Handler;)Lkotlinx/coroutines/experimental/android/HandlerContext;
+	public static final synthetic fun asCoroutineDispatcher (Landroid/os/Handler;)Lkotlinx/coroutines/experimental/android/HandlerContext;
 	public static final fun getUI ()Lkotlinx/coroutines/experimental/android/HandlerContext;
 }
 
+public abstract class kotlinx/coroutines/experimental/android/HandlerDispatcher : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+	public fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
+	public abstract fun getImmediate ()Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
+	public fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
+}
+
+public final class kotlinx/coroutines/experimental/android/HandlerDispatcherKt {
+	public static final fun asCoroutineDispatcher (Landroid/os/Handler;)Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
+	public static final fun awaitFrame (Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
+	public static final fun getMain (Lkotlinx/coroutines/experimental/Dispatchers;)Lkotlinx/coroutines/experimental/android/HandlerDispatcher;
+}
+

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

@@ -139,7 +139,6 @@ public final class kotlinx/coroutines/experimental/CoroutineContextKt {
 	public static final field DEBUG_PROPERTY_VALUE_AUTO Ljava/lang/String;
 	public static final field DEBUG_PROPERTY_VALUE_OFF Ljava/lang/String;
 	public static final field DEBUG_PROPERTY_VALUE_ON Ljava/lang/String;
-	public static final field IO_PARALLELISM_PROPERTY_NAME Ljava/lang/String;
 	public static final fun getDefaultDispatcher ()Lkotlinx/coroutines/experimental/CoroutineDispatcher;
 	public static final fun getIO ()Lkotlinx/coroutines/experimental/CoroutineDispatcher;
 	public static final fun newCoroutineContext (Lkotlin/coroutines/experimental/CoroutineContext;)Lkotlin/coroutines/experimental/CoroutineContext;
@@ -297,6 +296,17 @@ public final class kotlinx/coroutines/experimental/DispatchedTask$DefaultImpls {
 	public static fun run (Lkotlinx/coroutines/experimental/DispatchedTask;)V
 }
 
+public final class kotlinx/coroutines/experimental/Dispatchers {
+	public static final field Default Lkotlinx/coroutines/experimental/CoroutineDispatcher;
+	public static final field INSTANCE Lkotlinx/coroutines/experimental/Dispatchers;
+	public static final field Unconfined Lkotlinx/coroutines/experimental/CoroutineDispatcher;
+}
+
+public final class kotlinx/coroutines/experimental/DispatchersKt {
+	public static final field IO_PARALLELISM_PROPERTY_NAME Ljava/lang/String;
+	public static final fun getIO (Lkotlinx/coroutines/experimental/Dispatchers;)Lkotlinx/coroutines/experimental/CoroutineDispatcher;
+}
+
 public abstract interface class kotlinx/coroutines/experimental/DisposableHandle {
 	public abstract fun dispose ()V
 }

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

@@ -1,10 +1,19 @@
-public final class kotlinx/coroutines/experimental/javafx/JavaFx : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+public final class kotlinx/coroutines/experimental/javafx/JavaFx : kotlinx/coroutines/experimental/javafx/JavaFxDispatcher, kotlinx/coroutines/experimental/Delay {
 	public static final field INSTANCE Lkotlinx/coroutines/experimental/javafx/JavaFx;
 	public final fun awaitPulse (Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
-	public fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
 	public fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
 	public fun scheduleResumeAfterDelay (JLjava/util/concurrent/TimeUnit;Lkotlinx/coroutines/experimental/CancellableContinuation;)V
 	public fun toString ()Ljava/lang/String;
 }
 
+public abstract class kotlinx/coroutines/experimental/javafx/JavaFxDispatcher : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+	public fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
+	public fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
+}
+
+public final class kotlinx/coroutines/experimental/javafx/JavaFxDispatcherKt {
+	public static final fun awaitPulse (Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
+	public static final fun getJavaFx (Lkotlinx/coroutines/experimental/Dispatchers;)Lkotlinx/coroutines/experimental/javafx/JavaFxDispatcher;
+}
+

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

@@ -1,9 +1,17 @@
-public final class kotlinx/coroutines/experimental/swing/Swing : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+public final class kotlinx/coroutines/experimental/swing/Swing : kotlinx/coroutines/experimental/swing/SwingDispatcher, kotlinx/coroutines/experimental/Delay {
 	public static final field INSTANCE Lkotlinx/coroutines/experimental/swing/Swing;
-	public fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun dispatch (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Runnable;)V
 	public fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
 	public fun scheduleResumeAfterDelay (JLjava/util/concurrent/TimeUnit;Lkotlinx/coroutines/experimental/CancellableContinuation;)V
 	public fun toString ()Ljava/lang/String;
 }
 
+public abstract class kotlinx/coroutines/experimental/swing/SwingDispatcher : kotlinx/coroutines/experimental/CoroutineDispatcher, kotlinx/coroutines/experimental/Delay {
+	public fun delay (JLjava/util/concurrent/TimeUnit;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
+	public fun invokeOnTimeout (JLjava/util/concurrent/TimeUnit;Ljava/lang/Runnable;)Lkotlinx/coroutines/experimental/DisposableHandle;
+}
+
+public final class kotlinx/coroutines/experimental/swing/SwingDispatcherKt {
+	public static final fun getSwing (Lkotlinx/coroutines/experimental/Dispatchers;)Lkotlinx/coroutines/experimental/swing/SwingDispatcher;
+}
+

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

@@ -19,7 +19,7 @@ import kotlin.coroutines.experimental.intrinsics.*
  * The coroutine is cancelled when the resulting job is [cancelled][Job.cancel].
  *
  * Coroutine context is inherited from a [CoroutineScope], additional context elements can be specified with [context] argument.
- * If the context does not have any dispatcher nor any other [ContinuationInterceptor], then [DefaultDispatcher] is used.
+ * If the context does not have any dispatcher nor any other [ContinuationInterceptor], then [Dispatchers.Default] is used.
  * The parent job is inherited from a [CoroutineScope] as well, but it can also be overridden
  * with corresponding [coroutineContext] element.
  *
@@ -35,10 +35,10 @@ import kotlin.coroutines.experimental.intrinsics.*
  *
  * See [newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
  *
- * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine
+ * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
  * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
  * @param onCompletion optional completion handler for the coroutine (see [Job.invokeOnCompletion]).
- * @param block the coroutine code which will be invoked in the context of the provided scope
+ * @param block the coroutine code which will be invoked in the context of the provided scope.
  **/
 public fun CoroutineScope.launch(
     context: CoroutineContext = EmptyCoroutineContext,
@@ -64,7 +64,7 @@ public fun CoroutineScope.launch(
     replaceWith = ReplaceWith("GlobalScope.launch(context, start, onCompletion, block)", imports = ["kotlinx.coroutines.experimental.*"])
 )
 public fun launch(
-    context: CoroutineContext = DefaultDispatcher,
+    context: CoroutineContext = Dispatchers.Default,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     onCompletion: CompletionHandler? = null,
     block: suspend CoroutineScope.() -> Unit
@@ -80,7 +80,7 @@ public fun launch(
     replaceWith = ReplaceWith("GlobalScope.launch(context + parent, start, onCompletion, block)", imports = ["kotlinx.coroutines.experimental.*"])
 )
 public fun launch(
-    context: CoroutineContext = DefaultDispatcher,
+    context: CoroutineContext = Dispatchers.Default,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     parent: Job? = null, // nullable for binary compatibility
     onCompletion: CompletionHandler? = null,
@@ -91,7 +91,7 @@ public fun launch(
 /** @suppress **Deprecated**: Binary compatibility */
 @Deprecated(message = "Binary compatibility", level = DeprecationLevel.HIDDEN)
 public fun launch(
-    context: CoroutineContext = DefaultDispatcher,
+    context: CoroutineContext = Dispatchers.Default,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     parent: Job? = null,
     block: suspend CoroutineScope.() -> Unit
@@ -101,7 +101,7 @@ public fun launch(
 /** @suppress **Deprecated**: Binary compatibility */
 @Deprecated(message = "Binary compatibility", level = DeprecationLevel.HIDDEN)
 public fun launch(
-    context: CoroutineContext = DefaultDispatcher,
+    context: CoroutineContext = Dispatchers.Default,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     block: suspend CoroutineScope.() -> Unit
 ): Job =

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

@@ -9,8 +9,14 @@ import kotlin.coroutines.experimental.*
 public expect fun CoroutineScope.newCoroutineContext(context: CoroutineContext): CoroutineContext
 
 @Suppress("PropertyName")
+@Deprecated(
+    message = "Use Dispatchers.Default",
+    replaceWith = ReplaceWith("Dispatchers.Default",
+        imports = ["kotlinx.coroutines.experimental.Dispatchers"]))
 public expect val DefaultDispatcher: CoroutineDispatcher
 
+internal expect fun createDefaultDispatcher(): CoroutineDispatcher
+
 @Suppress("PropertyName")
 internal expect val DefaultDelay: Delay
 

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

@@ -9,16 +9,15 @@ import kotlin.coroutines.experimental.*
 /**
  * Base class that shall be extended by all coroutine dispatcher implementations.
  *
- * The following standard implementations are provided by `kotlinx.coroutines`:
+ * The following standard implementations are provided by `kotlinx.coroutines` as properties on
+ * [Dispatchers] objects:
  *
- * * [DefaultDispatcher] -- is used by all standard builder if no dispatcher nor any other [ContinuationInterceptor]
- *   is specified in their context. It is currently equal to [CommonPool] (subject to change in the future).
+ * * [Dispatchers.Default] -- is used by all standard builder if no dispatcher nor any other [ContinuationInterceptor]
+ *   is specified in their context. It uses a common pool of shared background threads.
  *   This is an appropriate choice for compute-intensive coroutines that consume CPU resources.
- * * [CommonPool] -- schedules coroutine execution to a common pool of shared background threads designed
- *   to be used for compute-intensive code.
- * * [IO] -- uses a shared pool of on-demand created threads and is designed for offloading of IO-intensive _blocking_
+ * * [Dispatchers.IO] -- uses a shared pool of on-demand created threads and is designed for offloading of IO-intensive _blocking_
  *   operations (like file I/O and blocking socket I/O).
- * * [Unconfined] -- starts coroutine execution in the current call-frame until the first suspension.
+ * * [Dispatchers.Unconfined] -- starts coroutine execution in the current call-frame until the first suspension.
  *   On first  suspension the coroutine builder function returns.
  *   The coroutine resumes in whatever thread that is used by the
  *   corresponding suspending function, without confining it to any specific thread or pool.

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

@@ -18,9 +18,9 @@ import kotlin.coroutines.experimental.*
  *
  * ```
  * class MyActivity : AppCompatActivity(), CoroutineScope {
- *
+ *     lateinit var job: Job
  *     override val coroutineContext: CoroutineContext
- *         get() = job + UI
+ *         get() = Dispatchers.Main + job
  *
  *     override fun onCreate(savedInstanceState: Bundle?) {
  *         super.onCreate(savedInstanceState)
@@ -34,17 +34,15 @@ import kotlin.coroutines.experimental.*
  *
  *     /*
  *      * Note how coroutine builders are scoped: if activity is destroyed or any of the launched coroutines
- *      * in this method throws an exception, then all nested coroutines will be cancelled.
+ *      * in this method throws an exception, then all nested coroutines are cancelled.
  *      */
- *     fun loadDataFromUI() = launch { // <- extension on current activity, launched in CommonPool
- *        val ioData = async(IO) { // <- extension on launch scope, launched in IO dispatcher
- *          // long computation
- *        }
- *
- *        withContext(UI) {
- *            val data = ioData.await()
- *            draw(data)
+ *     fun loadDataFromUI() = launch { // <- extension on current activity, launched in the main thread
+ *        val ioData = async(Dispatchers.IO) { // <- extension on launch scope, launched in IO dispatcher
+ *            // blocking I/O operation
  *        }
+ *        // do something else concurrently with I/O
+ *        val data = ioData.await() // wait for result of I/O
+ *        draw(data) // can draw in the main thread
  *     }
  * }
  *
@@ -111,7 +109,7 @@ public val CoroutineScope.isActive: Boolean
  *
  * Global scope is used to launch top-level coroutines which are operating on the whole application lifetime
  * and are not cancelled prematurely.
- * Another use of the global scope is [Unconfined] operators, which don't have any job associated with them.
+ * Another use of the global scope is operators running in [Dispatchers.Unconfined], which don't have any job associated with them.
  *
  * Application code usually should use application-defined [CoroutineScope], using
  * [async][CoroutineScope.async] or [launch][CoroutineScope.launch]
@@ -120,7 +118,7 @@ public val CoroutineScope.isActive: Boolean
  * Usage of this interface may look like this:
  *
  * ```
- * fun ReceiveChannel<Int>.sqrt(): ReceiveChannel<Double> = GlobalScope.produce(Unconfined) {
+ * fun ReceiveChannel<Int>.sqrt(): ReceiveChannel<Double> = GlobalScope.produce(Dispatchers.Unconfined) {
  *     for (number in this) {
  *         send(Math.sqrt(number))
  *     }

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

@@ -26,8 +26,8 @@ public enum class CoroutineStart {
      * function as most dispatchers do, then the coroutine code is dispatched for execution later, while the code that
      * invoked the coroutine builder continues execution.
      *
-     * Note, that [Unconfined] dispatcher always returns `false` from its [CoroutineDispatcher.isDispatchNeeded]
-     * function, so starting coroutine with [Unconfined] dispatcher by [DEFAULT] is the same as using [UNDISPATCHED].
+     * Note, that [Dispatchers.Unconfined] always returns `false` from its [CoroutineDispatcher.isDispatchNeeded]
+     * function, so starting coroutine with [Dispatchers.Unconfined] by [DEFAULT] is the same as using [UNDISPATCHED].
      *
      * If coroutine [Job] is cancelled before it even had a chance to start executing, then it will not start its
      * execution at all, but will complete with an exception.
@@ -59,7 +59,7 @@ public enum class CoroutineStart {
 
     /**
      * Immediately executes coroutine until its first suspension point _in the current thread_ as if the
-     * coroutine was started using [Unconfined] dispatcher. However, when coroutine is resumed from suspension
+     * coroutine was started using [Dispatchers.Unconfined]. However, when coroutine is resumed from suspension
      * it is dispatched according to the [CoroutineDispatcher] in its context.
      *
      * This is similar to [ATOMIC] in the sense that coroutine starts executing even if it was already cancelled,