Documentation for DefaultDispatcher in the guide

Author: elizarov

core/kotlinx-coroutines-core/README.md

@@ -16,6 +16,7 @@ Coroutine dispatchers implementing [CoroutineDispatcher]:
 
 | **Name**                    | **Description**
 | --------------------------- | ---------------
+| [DefaultDispatcher]         | Is equal to [CommonPool]
 | [CommonPool]                | Confines coroutine execution to a shared pool of threads
 | [newSingleThreadContext]    | Create new single-threaded coroutine context
 | [newFixedThreadPoolContext] | Creates new thread pool of a fixed size 
@@ -91,6 +92,7 @@ Select expression to perform multiple suspending operations simultaneously until
 [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
 [CommonPool]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-common-pool/index.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

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/Actor.kt

@@ -19,6 +19,7 @@ package kotlinx.coroutines.experimental.channels
 import kotlinx.coroutines.experimental.*
 import kotlinx.coroutines.experimental.selects.SelectClause2
 import kotlinx.coroutines.experimental.selects.SelectInstance
+import kotlin.coroutines.experimental.ContinuationInterceptor
 import kotlin.coroutines.experimental.CoroutineContext
 
 /**
@@ -58,10 +59,11 @@ public interface ActorJob<in E> : Job, SendChannel<E> {
  * when the coroutine completes.
  * The running coroutine is cancelled when the its job is [cancelled][Job.cancel].
  *
- * The [context] for the new coroutine must be explicitly specified.
- * See [CoroutineDispatcher] for the standard [context] implementations that are provided by `kotlinx.coroutines`.
+ * The [context] for the new coroutine can be explicitly specified.
+ * See [CoroutineDispatcher] for the standard context implementations that are provided by `kotlinx.coroutines`.
  * The [context][CoroutineScope.context] of the parent coroutine from its [scope][CoroutineScope] may be used,
  * in which case the [Job] of the resulting coroutine is a child of the job of the parent coroutine.
+ * If the context does not have any dispatcher nor any other [ContinuationInterceptor], then [DefaultDispatcher] is used.
  *
  * By default, the coroutine is immediately scheduled for execution.
  * Other options can be specified via `start` parameter. See [CoroutineStart] for details.
@@ -75,13 +77,13 @@ public interface ActorJob<in E> : Job, SendChannel<E> {
  *
  * See [newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
  *
- * @param context context of the coroutine
- * @param capacity capacity of the channel's buffer (no buffer by default)
- * @param start coroutine start option
- * @param block the coroutine code
+ * @param context context of the coroutine. The default value is [DefaultDispatcher].
+ * @param capacity capacity of the channel's buffer (no buffer by default).
+ * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
+ * @param block the coroutine code.
  */
 public fun <E> actor(
-    context: CoroutineContext,
+    context: CoroutineContext = DefaultDispatcher,
     capacity: Int = 0,
     start: CoroutineStart = CoroutineStart.DEFAULT,
     block: suspend ActorScope<E>.() -> Unit

core/kotlinx-coroutines-core/src/test/kotlin/guide/example-basic-01.kt

@@ -17,10 +17,11 @@
 // This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
 package guide.basic.example01
 
-import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
 
 fun main(args: Array<String>) {
-    launch(CommonPool) { // create new coroutine in common thread pool
+    launch { // launch new coroutine
         delay(1000L) // non-blocking delay for 1 second (default time unit is ms)
         println("World!") // print after delay
     }

core/kotlinx-coroutines-core/src/test/kotlin/guide/example-basic-02.kt

@@ -17,10 +17,12 @@
 // This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
 package guide.basic.example02
 
-import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
 
 fun main(args: Array<String>) = runBlocking<Unit> { // start main coroutine
-    launch(CommonPool) { // create new coroutine in common thread pool
+    launch { // launch new coroutine
         delay(1000L)
         println("World!")
     }

core/kotlinx-coroutines-core/src/test/kotlin/guide/example-basic-03.kt

@@ -17,10 +17,12 @@
 // This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
 package guide.basic.example03
 
-import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
 
 fun main(args: Array<String>) = runBlocking<Unit> {
-    val job = launch(CommonPool) { // create new coroutine and keep a reference to its Job
+    val job = launch { // launch new coroutine and keep a reference to its Job
         delay(1000L)
         println("World!")
     }

core/kotlinx-coroutines-core/src/test/kotlin/guide/example-basic-04.kt

@@ -17,10 +17,12 @@
 // This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
 package guide.basic.example04
 
-import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
 
 fun main(args: Array<String>) = runBlocking<Unit> {
-    val job = launch(CommonPool) { doWorld() }
+    val job = launch { doWorld() }
     println("Hello,")
     job.join()
 }

core/kotlinx-coroutines-core/src/test/kotlin/guide/example-basic-05.kt

@@ -17,11 +17,13 @@
 // This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
 package guide.basic.example05
 
-import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
 
 fun main(args: Array<String>) = runBlocking<Unit> {
-    val jobs = List(100_000) { // create a lot of coroutines and list their jobs
-        launch(CommonPool) {
+    val jobs = List(100_000) { // launch a lot of coroutines and list their jobs
+        launch {
             delay(1000L)
             print(".")
         }

core/kotlinx-coroutines-core/src/test/kotlin/guide/example-basic-06.kt

@@ -17,10 +17,12 @@
 // This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
 package guide.basic.example06
 
-import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
 
 fun main(args: Array<String>) = runBlocking<Unit> {
-    launch(CommonPool) {
+    launch {
         repeat(1000) { i ->
             println("I'm sleeping $i ...")
             delay(500L)

core/kotlinx-coroutines-core/src/test/kotlin/guide/example-cancel-01.kt

@@ -17,10 +17,12 @@
 // This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
 package guide.cancel.example01
 
-import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
 
 fun main(args: Array<String>) = runBlocking<Unit> {
-    val job = launch(CommonPool) {
+    val job = launch {
         repeat(1000) { i ->
             println("I'm sleeping $i ...")
             delay(500L)

core/kotlinx-coroutines-core/src/test/kotlin/guide/example-cancel-02.kt

@@ -17,11 +17,14 @@
 // This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
 package guide.cancel.example02
 
-import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.cancelAndJoin
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
 
 fun main(args: Array<String>) = runBlocking<Unit> {
     val startTime = System.currentTimeMillis()
-    val job = launch(CommonPool) {
+    val job = launch {
         var nextPrintTime = startTime
         var i = 0
         while (i < 5) { // computation loop, just wastes CPU