Split main coroutines guide into multiple files

See PR Kotlin#587

Author: hhariri

CHANGES.md

@@ -18,7 +18,7 @@
   * `currentScope` and `coroutineScope` builders are introduced to extract and provide `CoroutineScope`.
   * Factory methods to create `CoroutineScope` from `CoroutineContext` are introduced.
   * `CoroutineScope.isActive` became an extension property.
-  * New sections about structured concurrency in core guide: ["Structured concurrency"](coroutines-guide.md#structured-concurrency), ["Scope builder"](coroutines-guide.md#scope-builder) and ["Structured concurrency with async"](coroutines-guide.md#structured-concurrency-with-async).
+  * New sections about structured concurrency in core guide: ["Structured concurrency"](docs/coroutines-guide.md#structured-concurrency), ["Scope builder"](docs/coroutines-guide.md#scope-builder) and ["Structured concurrency with async"](docs/coroutines-guide.md#structured-concurrency-with-async).
   * New section in UI guide with Android example: ["Structured concurrency, lifecycle and coroutine parent-child hierarchy"](ui/coroutines-guide-ui.md#structured-concurrency,-lifecycle-and-coroutine-parent-child-hierarchy).
   * Deprecated reactive API is removed.
 * Dispatchers are renamed and grouped in the Dispatchers object (see #41 and #533):
@@ -38,7 +38,7 @@
 ## Version 0.25.0
 
 * Major rework on exception-handling and cancellation in coroutines (see #333, #452 and #451):
-  * New ["Exception Handling" section in the guide](coroutines-guide.md#exception-handling) explains exceptions in coroutines. 
+  * New ["Exception Handling" section in the guide](docs/coroutines-guide.md#exception-handling) explains exceptions in coroutines. 
   * Semantics of `Job.cancel` resulting `Boolean` value changed — `true` means exception was handled by the job, caller shall handle otherwise.
   * Exceptions are properly propagated from children to parents.
   * Installed `CoroutineExceptionHandler` for a family of coroutines receives one aggregated exception in case of failure.
@@ -47,7 +47,7 @@
 * Introduced support for thread-local elements in coroutines context (see #119):
   * `ThreadContextElement` API for custom thread-context sensitive context elements.
   * `ThreadLocal.asContextElement()` extension function to convert an arbitrary thread-local into coroutine context element.
-  * New ["Thread-local data" subsection in the guide](coroutines-guide.md#thread-local-data) with examples.
+  * New ["Thread-local data" subsection in the guide](docs/coroutines-guide.md#thread-local-data) with examples.
   * SLF4J Mapped Diagnostic Context (MDC) integration is provided via `MDCContext` element defined in [`kotlinx-coroutines-slf4j`](integration/kotlinx-coroutines-slf4j/README.md) integration module.
 * Introduced IO dispatcher to offload blocking I/O-intensive tasks (see #79).
 * Introduced `ExecutorCoroutineDispatcher` instead of `CloseableCoroutineDispatcher` (see #385). 
@@ -280,7 +280,7 @@
 * Fixed `actor` and `produce` so that a cancellation of a Job cancels the underlying channel (closes and removes all the pending messages).  
 * Fixed sporadic failure of `example-context-06` (see #160)
 * Fixed hang of `Job.start` on lazy coroutine with attached `invokeOnCompletion` handler.
-* A more gradual introduction to `runBlocking` and coroutines in the [guide](coroutines-guide.md) (see #166).
+* A more gradual introduction to `runBlocking` and coroutines in the [guide](docs/coroutines-guide.md) (see #166).
 
 ## Version 0.19.3
 
@@ -331,7 +331,7 @@
   * When a context is explicitly specified, `newCoroutineContext` function checks if there is any
     interceptor/dispatcher defined in the context and uses `DefaultDispatcher` if there is none.  
   * `DefaultDispatcher` is currently defined to be equal to `CommonPool`.     
-  * Examples in the [guide](coroutines-guide.md) now start with `launch { ... }` code and explanation on the nature
+  * Examples in the [guide](docs/coroutines-guide.md) now start with `launch { ... }` code and explanation on the nature
     and the need for coroutine context starts in "Coroutine context and dispatchers" section.  
 * Parent coroutines now wait for their children (see #125):
   * Job _completing_ state is introduced in documentation as a state in which parent coroutine waits for its children.
@@ -391,7 +391,7 @@
 ## Version 0.17
 
 * `CompletableDeferred` is introduced as a set-once event-like communication primitive (see #70).
-  * [Coroutines guide](coroutines-guide.md) uses it in a section on actors.
+  * [Coroutines guide](docs/coroutines-guide.md) uses it in a section on actors.
   * `CompletableDeferred` is an interface with private impl (courtesy of @fvasco, see #86).
   * It extends `Deferred` interface with `complete` and `completeExceptionally` functions.
 * `Job.join` and `Deferred.await` wait until a cancelled coroutine stops execution (see #64). 
@@ -537,15 +537,15 @@
 * `actor` coroutine builder.
 * Couple more examples for "Shared mutable state and concurrency" section and 
   "Channels are fair" section with ping-pong table example 
-  in [coroutines guide](coroutines-guide.md).
+  in [coroutines guide](docs/coroutines-guide.md).
 
 ## Version 0.11-rc
 
 * `select` expression with onJoin/onAwait/onSend/onReceive clauses.
 * `Mutex` is moved to `kotlinx.coroutines.experimental.sync` package.
 * `ClosedSendChannelException` is a subclass of `CancellationException` now.
 * New sections on "Shared mutable state and concurrency" and "Select expression" 
-  in [coroutines guide](coroutines-guide.md).
+  in [coroutines guide](docs/coroutines-guide.md).
 
 ## Version 0.10-rc
 
@@ -573,20 +573,20 @@
   So, lazy coroutines do not need a separate state variable to track their started/not-started (new/active) status.
 * Exception transparency in `Job.cancel` (original cause is rethrown).
 * Clarified possible states for `Job`/`CancellableContinuation`/`Deferred` in docs.
-* Example on async-style functions and links to API reference site from [coroutines guide](coroutines-guide.md).
+* Example on async-style functions and links to API reference site from [coroutines guide](docs/coroutines-guide.md).
 
 ## Version 0.7-beta
 
 * Buffered and unbuffered channels are introduced: `Channel`, `SendChannel`, and `ReceiveChannel` interfaces,
   `RendezvousChannel` and `ArrayChannel` implementations, `Channel()` factory function and `buildChannel{}`
   coroutines builder.
 * `Here` context is renamed to `Unconfined` (the old name is deprecated).
-* A [guide on coroutines](coroutines-guide.md) is expanded: sections on contexts and channels.  
+* A [guide on coroutines](docs/coroutines-guide.md) is expanded: sections on contexts and channels.  
 
 ## Version 0.6-beta
 
 * Switched to Kotlin version 1.1.0-beta-37.
-* A [guide on coroutines](coroutines-guide.md) is expanded.  
+* A [guide on coroutines](docs/coroutines-guide.md) is expanded.  
 
 ## Version 0.5-beta
 
@@ -599,7 +599,7 @@
   has a default implementation that returns `true`.
 * `NonCancellable` context is introduced.  
 * Performance optimizations for cancellable continuations (fewer objects created).
-* A [guide on coroutines](coroutines-guide.md) is added.  
+* A [guide on coroutines](docs/coroutines-guide.md) is added.  
 
 ## Version 0.4-beta
 

README.md

@@ -40,7 +40,7 @@ GlobalScope.launch {
    * [Introduction to Coroutines](https://www.youtube.com/watch?v=_hfBv0a09Jc) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/introduction-to-coroutines-kotlinconf-2017))
    * [Deep dive into Coroutines](https://www.youtube.com/watch?v=YrrUCSi72E8) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/deep-dive-into-coroutines-on-jvm-kotlinconf-2017))
 * Guides and manuals: 
-  * [Guide to kotlinx.coroutines by example](coroutines-guide.md) (**read it first**)
+  * [Guide to kotlinx.coroutines by example](docs/coroutines-guide.md) (**read it first**)
   * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
   * [Guide to reactive streams with coroutines](reactive/coroutines-guide-reactive.md)
 * [Change log for kotlinx.coroutines](CHANGES.md)

RELEASE.md

@@ -13,7 +13,7 @@ To release new `<version>` of `kotlinx-coroutines`:
 
 4. Search & replace `<old-version>` with `<version>` across the project files. Should replace in:
    * [`README.md`](README.md)
-   * [`coroutines-guide.md`](coroutines-guide.md)
+   * [`coroutines-guide.md`](docs/coroutines-guide.md)
    * [`gradle.properties`](gradle.properties)
    * [`ui/kotlinx-coroutines-android/example-app/gradle.properties`](ui/kotlinx-coroutines-android/example-app/gradle.properties)    
    * [`ui/kotlinx-coroutines-android/animation-app/gradle.properties`](ui/kotlinx-coroutines-android/animation-app/gradle.properties)    

core/kotlinx-coroutines-core/test/guide/test/BasicsGuideTest.kt

@@ -0,0 +1,89 @@
+// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
+package kotlinx.coroutines.experimental.guide.test
+
+import org.junit.Test
+
+class BasicsGuideTest {
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic01() {
+        test("KotlinxCoroutinesExperimentalGuideBasic01") { kotlinx.coroutines.experimental.guide.basic01.main(emptyArray()) }.verifyLines(
+            "Hello,",
+            "World!"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic02() {
+        test("KotlinxCoroutinesExperimentalGuideBasic02") { kotlinx.coroutines.experimental.guide.basic02.main(emptyArray()) }.verifyLines(
+            "Hello,",
+            "World!"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic02b() {
+        test("KotlinxCoroutinesExperimentalGuideBasic02b") { kotlinx.coroutines.experimental.guide.basic02b.main(emptyArray()) }.verifyLines(
+            "Hello,",
+            "World!"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic03() {
+        test("KotlinxCoroutinesExperimentalGuideBasic03") { kotlinx.coroutines.experimental.guide.basic03.main(emptyArray()) }.verifyLines(
+            "Hello,",
+            "World!"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic03s() {
+        test("KotlinxCoroutinesExperimentalGuideBasic03s") { kotlinx.coroutines.experimental.guide.basic03s.main(emptyArray()) }.verifyLines(
+            "Hello,",
+            "World!"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic04() {
+        test("KotlinxCoroutinesExperimentalGuideBasic04") { kotlinx.coroutines.experimental.guide.basic04.main(emptyArray()) }.verifyLines(
+            "Task from coroutine scope",
+            "Task from runBlocking",
+            "Task from nested launch",
+            "Coroutine scope is over"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic05() {
+        test("KotlinxCoroutinesExperimentalGuideBasic05") { kotlinx.coroutines.experimental.guide.basic05.main(emptyArray()) }.verifyLines(
+            "Hello,",
+            "World!"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic05s() {
+        test("KotlinxCoroutinesExperimentalGuideBasic05s") { kotlinx.coroutines.experimental.guide.basic05s.main(emptyArray()) }.verifyLines(
+            "Hello,",
+            "World!"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic06() {
+        test("KotlinxCoroutinesExperimentalGuideBasic06") { kotlinx.coroutines.experimental.guide.basic06.main(emptyArray()) }.also { lines ->
+            check(lines.size == 1 && lines[0] == ".".repeat(100_000))
+        }
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideBasic07() {
+        test("KotlinxCoroutinesExperimentalGuideBasic07") { kotlinx.coroutines.experimental.guide.basic07.main(emptyArray()) }.verifyLines(
+            "I'm sleeping 0 ...",
+            "I'm sleeping 1 ...",
+            "I'm sleeping 2 ..."
+        )
+    }
+}

core/kotlinx-coroutines-core/test/guide/test/CancellationTimeOutsGuideTest.kt

@@ -0,0 +1,87 @@
+// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
+package kotlinx.coroutines.experimental.guide.test
+
+import org.junit.Test
+
+class CancellationTimeOutsGuideTest {
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideCancel01() {
+        test("KotlinxCoroutinesExperimentalGuideCancel01") { kotlinx.coroutines.experimental.guide.cancel01.main(emptyArray()) }.verifyLines(
+            "I'm sleeping 0 ...",
+            "I'm sleeping 1 ...",
+            "I'm sleeping 2 ...",
+            "main: I'm tired of waiting!",
+            "main: Now I can quit."
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideCancel02() {
+        test("KotlinxCoroutinesExperimentalGuideCancel02") { kotlinx.coroutines.experimental.guide.cancel02.main(emptyArray()) }.verifyLines(
+            "I'm sleeping 0 ...",
+            "I'm sleeping 1 ...",
+            "I'm sleeping 2 ...",
+            "main: I'm tired of waiting!",
+            "I'm sleeping 3 ...",
+            "I'm sleeping 4 ...",
+            "main: Now I can quit."
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideCancel03() {
+        test("KotlinxCoroutinesExperimentalGuideCancel03") { kotlinx.coroutines.experimental.guide.cancel03.main(emptyArray()) }.verifyLines(
+            "I'm sleeping 0 ...",
+            "I'm sleeping 1 ...",
+            "I'm sleeping 2 ...",
+            "main: I'm tired of waiting!",
+            "main: Now I can quit."
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideCancel04() {
+        test("KotlinxCoroutinesExperimentalGuideCancel04") { kotlinx.coroutines.experimental.guide.cancel04.main(emptyArray()) }.verifyLines(
+            "I'm sleeping 0 ...",
+            "I'm sleeping 1 ...",
+            "I'm sleeping 2 ...",
+            "main: I'm tired of waiting!",
+            "I'm running finally",
+            "main: Now I can quit."
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideCancel05() {
+        test("KotlinxCoroutinesExperimentalGuideCancel05") { kotlinx.coroutines.experimental.guide.cancel05.main(emptyArray()) }.verifyLines(
+            "I'm sleeping 0 ...",
+            "I'm sleeping 1 ...",
+            "I'm sleeping 2 ...",
+            "main: I'm tired of waiting!",
+            "I'm running finally",
+            "And I've just delayed for 1 sec because I'm non-cancellable",
+            "main: Now I can quit."
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideCancel06() {
+        test("KotlinxCoroutinesExperimentalGuideCancel06") { kotlinx.coroutines.experimental.guide.cancel06.main(emptyArray()) }.verifyLinesStartWith(
+            "I'm sleeping 0 ...",
+            "I'm sleeping 1 ...",
+            "I'm sleeping 2 ...",
+            "Exception in thread \"main\" kotlinx.coroutines.experimental.TimeoutCancellationException: Timed out waiting for 1300 MILLISECONDS"
+        )
+    }
+
+    @Test
+    fun testKotlinxCoroutinesExperimentalGuideCancel07() {
+        test("KotlinxCoroutinesExperimentalGuideCancel07") { kotlinx.coroutines.experimental.guide.cancel07.main(emptyArray()) }.verifyLines(
+            "I'm sleeping 0 ...",
+            "I'm sleeping 1 ...",
+            "I'm sleeping 2 ...",
+            "Result is null"
+        )
+    }
+}