Dispatchers are renamed and grouped in the Dispatchers object

* Dispatchers.Default — a default dispatcher for background asynchronous tasks
  (currently backed by FJP commonPool, a new dispatcher in the future).
* Dispatchers.IO — a dispatcher for blocking background operations (#79).
* Dispatchers.Main — a dispatcher for Android Main Thread (#533).
* Dispatchers.Swing — a dispatcher for Swing Event Dispatch Thread.
* Dispatchers.JavaFx — a dispatcher for JavaFx Application Thread.
* Old dispatchers are deprecated, CommonPool is deprecated, too.
* awaitPulse() in JavaFx and awaitFrame() in Android are top-level funs.
* Introduced HandlerDispatcher, SwingDispatcher, and JavaFxDispatcher types
  in the corresponding UI modules for type-safety and future extensions

Fixes #41
Fixes #533

Author: elizarov

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

@@ -3,23 +3,32 @@ 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
 	public fun scheduleResumeAfterDelay (JLjava/util/concurrent/TimeUnit;Lkotlinx/coroutines/experimental/CancellableContinuation;)V
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class kotlinx/coroutines/experimental/android/HandlerContextKt {
-	public static final fun asCoroutineDispatcher (Landroid/os/Handler;)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 synthetic fun asCoroutineDispatcher (Landroid/os/Handler;)Lkotlinx/coroutines/experimental/android/HandlerContext;
+	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;
 	public static final fun getUI ()Lkotlinx/coroutines/experimental/android/HandlerContext;
 }
 

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

@@ -111,7 +111,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 +120,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,

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

@@ -4,7 +4,6 @@
 
 package kotlinx.coroutines.experimental
 
-import kotlinx.coroutines.experimental.internal.*
 import kotlinx.coroutines.experimental.intrinsics.*
 import kotlinx.coroutines.experimental.selects.*
 import kotlin.coroutines.experimental.*
@@ -128,7 +127,7 @@ public interface Deferred<out T> : Job {
  * The running coroutine is cancelled when the resulting deferred 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.
  *
@@ -138,7 +137,7 @@ public interface Deferred<out T> : Job {
  * the resulting [Deferred] is created in _new_ state. It can be explicitly started with [start][Job.start]
  * function and will be started implicitly on the first invocation of [join][Job.join], [await][Deferred.await] or [awaitAll].
  *
- * @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.
@@ -167,7 +166,7 @@ public fun <T> CoroutineScope.async(
     replaceWith = ReplaceWith("GlobalScope.async(context, start, onCompletion, block)", imports = ["kotlinx.coroutines.experimental.*"])
 )
 public fun <T> async(
-    context: CoroutineContext = DefaultDispatcher,
+    context: CoroutineContext = Dispatchers.Default,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     onCompletion: CompletionHandler? = null,
     block: suspend CoroutineScope.() -> T
@@ -183,7 +182,7 @@ public fun <T> async(
     replaceWith = ReplaceWith("GlobalScope.async(context + parent, start, onCompletion, block)", imports = ["kotlinx.coroutines.experimental.*"])
 )
 public fun <T> async(
-    context: CoroutineContext = DefaultDispatcher,
+    context: CoroutineContext = Dispatchers.Default,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     parent: Job? = null,
     onCompletion: CompletionHandler? = null,
@@ -194,7 +193,7 @@ public fun <T> async(
 /** @suppress **Deprecated**: Binary compatibility */
 @Deprecated(message = "Binary compatibility", level = DeprecationLevel.HIDDEN)
 public fun <T> async(
-    context: CoroutineContext = DefaultDispatcher,
+    context: CoroutineContext = Dispatchers.Default,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     parent: Job? = null,
     block: suspend CoroutineScope.() -> T
@@ -204,7 +203,7 @@ public fun <T> async(
 /** @suppress **Deprecated**: Binary compatibility */
 @Deprecated(message = "Binary compatibility", level = DeprecationLevel.HIDDEN)
 public fun <T> async(
-    context: CoroutineContext = DefaultDispatcher,
+    context: CoroutineContext = Dispatchers.Default,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     block: suspend CoroutineScope.() -> T
 ): Deferred<T> =