Updated dispatchers references in readmes and docs

Author: elizarov

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:

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
  *     }
  * }
  *

core/kotlinx-coroutines-core/README.md

@@ -16,12 +16,11 @@ Coroutine dispatchers implementing [CoroutineDispatcher]:
 
 | **Name**                    | **Description**
 | --------------------------- | ---------------
-| [DefaultDispatcher]         | Is equal to [CommonPool]
-| [CommonPool]                | Confines coroutine execution to a shared pool of threads
+| [Dispatchers.Default]       | Confines coroutine execution to a shared pool of background threads
+| [Dispatchers.Unconfined]    | Does not confine coroutine execution in any way
 | [newSingleThreadContext]    | Create new single-threaded coroutine context
 | [newFixedThreadPoolContext] | Creates new thread pool of a fixed size 
 | [Executor.asCoroutineDispatcher][java.util.concurrent.Executor.asCoroutineDispatcher] | Extension to convert any executor
-| [Unconfined]                | Does not confine coroutine execution in any way
 
 More context elements:
 
@@ -51,7 +50,7 @@ Top-level suspending functions:
 
 Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
 helper function. [NonCancellable] job object is provided to suppress cancellation with 
-`run(NonCancellable) {...}` block of code.
+`withContext(NonCancellable) {...}` block of code.
 
 [Select][kotlinx.coroutines.experimental.selects.select] expression waits for the result of multiple suspending functions simultaneously:
 
@@ -110,7 +109,8 @@ Components to ease writing unit-tests for code that contains coroutines with del
 [Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
 [runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
 [CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
-[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
+[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-default.html
+[Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-unconfined.html
 [newSingleThreadContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-single-thread-context.html
 [newFixedThreadPoolContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-fixed-thread-pool-context.html
 [java.util.concurrent.Executor.asCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/java.util.concurrent.-executor/as-coroutine-dispatcher.html

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

@@ -84,7 +84,7 @@ public interface ThreadContextElement<S> : CoroutineContext.Element {
  * val myThreadLocal = ThreadLocal<String?>()
  * ...
  * println(myThreadLocal.get()) // Prints "null"
- * launch(CommonPool + myThreadLocal.asContextElement(value = "foo")) {
+ * launch(Dispatchers.Default + myThreadLocal.asContextElement(value = "foo")) {
  *   println(myThreadLocal.get()) // Prints "foo"
  *   withContext(UI) {
  *     println(myThreadLocal.get()) // Prints "foo", but it's on UI thread

core/kotlinx-coroutines-core/test/ThreadContextElementTest.kt

@@ -60,7 +60,7 @@ class ThreadContextElementTest : TestBase() {
         expect(1)
         newSingleThreadContext("withContext").use {
             val data = MyData()
-            GlobalScope.async(CommonPool + MyElement(data)) {
+            GlobalScope.async(Dispatchers.Default + MyElement(data)) {
                 assertSame(data, myThreadLocal.get())
                 expect(2)
 

core/kotlinx-coroutines-core/test/ThreadLocalTest.kt

@@ -22,7 +22,7 @@ class ThreadLocalTest : TestBase() {
     @Test
     fun testThreadLocal() = runTest {
         assertNull(stringThreadLocal.get())
-        val deferred = async(CommonPool + stringThreadLocal.asContextElement("value")) {
+        val deferred = async(Dispatchers.Default + stringThreadLocal.asContextElement("value")) {
             assertEquals("value", stringThreadLocal.get())
             withContext(executor) {
                 assertEquals("value", stringThreadLocal.get())
@@ -38,7 +38,7 @@ class ThreadLocalTest : TestBase() {
     @Test
     fun testThreadLocalInitialValue() = runTest {
         intThreadLocal.set(42)
-        val deferred = async(CommonPool + intThreadLocal.asContextElement(239)) {
+        val deferred = async(Dispatchers.Default + intThreadLocal.asContextElement(239)) {
             assertEquals(239, intThreadLocal.get())
             withContext(executor) {
                 assertEquals(239, intThreadLocal.get())
@@ -55,7 +55,7 @@ class ThreadLocalTest : TestBase() {
         stringThreadLocal.set("test")
         intThreadLocal.set(314)
 
-        val deferred = async(CommonPool
+        val deferred = async(Dispatchers.Default
                 + intThreadLocal.asContextElement(value = 239) + stringThreadLocal.asContextElement(value = "pew")) {
             assertEquals(239, intThreadLocal.get())
             assertEquals("pew", stringThreadLocal.get())
@@ -110,7 +110,7 @@ class ThreadLocalTest : TestBase() {
     fun testThreadLocalModification() = runTest {
         stringThreadLocal.set("main")
 
-        val deferred = async(CommonPool
+        val deferred = async(Dispatchers.Default
                 + stringThreadLocal.asContextElement("initial")) {
             assertEquals("initial", stringThreadLocal.get())
 
@@ -141,7 +141,7 @@ class ThreadLocalTest : TestBase() {
     fun testThreadLocalModificationMutableBox() = runTest {
         myCounterLocal.set(Counter(42))
 
-        val deferred = async(CommonPool
+        val deferred = async(Dispatchers.Default
                 + myCounterLocal.asContextElement(Counter(0))) {
             assertEquals(0, myCounterLocal.get().cnt)
 
@@ -171,7 +171,7 @@ class ThreadLocalTest : TestBase() {
         expect(1)
         newSingleThreadContext("withContext").use {
             val data = 42
-            GlobalScope.async(CommonPool + intThreadLocal.asContextElement(42)) {
+            GlobalScope.async(Dispatchers.Default + intThreadLocal.asContextElement(42)) {
 
                 assertSame(data, intThreadLocal.get())
                 expect(2)

js/kotlinx-coroutines-core-js/README.md

@@ -14,8 +14,8 @@ Coroutine dispatchers implementing [CoroutineDispatcher]:
 
 | **Name**                    | **Description**
 | --------------------------- | ---------------
-| [DefaultDispatcher]         | Posts execution to JS event loop
-| [Unconfined]                | Does not confine coroutine execution in any way
+| [Dispatchers.Default]       | Posts execution to JS event loop
+| [Dispatchers.Unconfined]    | Does not confine coroutine execution in any way
 
 More context elements:
 
@@ -45,7 +45,7 @@ Top-level suspending functions:
 
 Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
 helper function. [NonCancellable] job object is provided to suppress cancellation with 
-`run(NonCancellable) {...}` block of code.
+`withContext(NonCancellable) {...}` block of code.
 
 [Select][kotlinx.coroutines.experimental.selects.select] expression waits for the result of multiple suspending functions simultaneously:
 
@@ -67,7 +67,8 @@ helper function. [NonCancellable] job object is provided to suppress cancellatio
 [async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/async.html
 [Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
 [CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
-[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
+[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-default.html
+[Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-unconfined.html
 [NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
 [CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
 [delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html

native/kotlinx-coroutines-core-native/README.md

@@ -16,8 +16,8 @@ Coroutine dispatchers implementing [CoroutineDispatcher]:
 
 | **Name**                    | **Description**
 | --------------------------- | ---------------
-| [DefaultDispatcher]         | TBD
-| [Unconfined]                | Does not confine coroutine execution in any way
+| [Dispatchers.Default]       | References current [runBlocking] event loop
+| [Dispatchers.Unconfined]    | Does not confine coroutine execution in any way
 
 More context elements:
 
@@ -70,7 +70,8 @@ helper function. [NonCancellable] job object is provided to suppress cancellatio
 [Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
 [runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
 [CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
-[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
+[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-default.html
+[Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-unconfined.html
 [NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
 [CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
 [delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html

reactive/coroutines-guide-reactive.md

@@ -862,7 +862,7 @@ it is going to be executed in Rx computation thread pool. The output is going to
 
 ### Threads with coroutines
 
-In the world of coroutines `Schedulers.computation()` roughly corresponds to [CommonPool], 
+In the world of coroutines `Schedulers.computation()` roughly corresponds to [Dispatchers.Default], 
 so the previous example is similar to the following one:
 
 <!--- INCLUDE
@@ -881,7 +881,7 @@ fun rangeWithInterval(context: CoroutineContext, time: Long, start: Int, count:
 }
 
 fun main(args: Array<String>) {
-    Flowable.fromPublisher(rangeWithInterval(CommonPool, 100, 1, 3))
+    Flowable.fromPublisher(rangeWithInterval(Dispatchers.Default, 100, 1, 3))
         .subscribe { println("$it on thread ${Thread.currentThread().name}") }
     Thread.sleep(1000)
 }
@@ -901,8 +901,8 @@ The produced output is going to be similar to:
 
 Here we've used Rx 
 [subscribe](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Flowable.html#subscribe(io.reactivex.functions.Consumer))
-operator that does not have its own scheduler and operates on the same thread that the publisher -- on a `CommonPool`
-in this example.
+operator that does not have its own scheduler and operates on the same thread that the publisher -- on a default
+shared pool of threads in this example.
 
 ### Rx observeOn 
 
@@ -931,7 +931,7 @@ fun rangeWithInterval(context: CoroutineContext, time: Long, start: Int, count:
 }
 
 fun main(args: Array<String>) {
-    Flowable.fromPublisher(rangeWithInterval(CommonPool, 100, 1, 3))
+    Flowable.fromPublisher(rangeWithInterval(Dispatchers.Default, 100, 1, 3))
         .observeOn(Schedulers.computation())                           // <-- THIS LINE IS ADDED
         .subscribe { println("$it on thread ${Thread.currentThread().name}") }
     Thread.sleep(1000)
@@ -1058,6 +1058,7 @@ coroutines for complex pipelines with fan-in and fan-out between multiple worker
 [Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-unconfined.html
 [yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
 [launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
+[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-dispatchers/-default.html
 [Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/join.html
 <!--- INDEX kotlinx.coroutines.experimental.channels -->
 [Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel/index.html

reactive/kotlinx-coroutines-rx2/test/guide/example-reactive-context-02.kt

@@ -18,7 +18,7 @@ fun rangeWithInterval(context: CoroutineContext, time: Long, start: Int, count:
 }
 
 fun main(args: Array<String>) {
-    Flowable.fromPublisher(rangeWithInterval(CommonPool, 100, 1, 3))
+    Flowable.fromPublisher(rangeWithInterval(Dispatchers.Default, 100, 1, 3))
         .subscribe { println("$it on thread ${Thread.currentThread().name}") }
     Thread.sleep(1000)
 }