buildChannel is renamed to produce

top-level readme file for kotlinx-coroutines-core module is improved:
Better grouping and list of all available features

Author: elizarov

coroutines-guide.md

@@ -1,20 +1,26 @@
-<!---
-
-Copyright 2016-2017 JetBrains s.r.o.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
+<!--- INCLUDE .*/example-([a-z]+)-([0-9]+)\.kt 
+/*
+ * Copyright 2016-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
+package guide.$$1.example$$2
 
+import kotlinx.coroutines.experimental.*
 -->
+<!--- KNIT kotlinx-coroutines-core/src/test/kotlin/guide/.*\.kt -->
 
 # Guide to kotlinx.coroutines by example
 
@@ -63,31 +69,8 @@ This is a short guide on core features of `kotlinx.coroutines` with a series of
   * [Fan-in](#fan-in)
   * [Buffered channels](#buffered-channels)
 
-<!--- KNIT kotlinx-coroutines-core/src/test/kotlin/guide/.*\.kt -->
-
-<!--- INCLUDE .*/example-([a-z]+)-([0-9]+)\.kt 
-/*
- * Copyright 2016-2017 JetBrains s.r.o.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package guide.$$1.example$$2
+<!--- END_TOC -->
 
-import kotlinx.coroutines.experimental.*
--->
-  
 ## Coroutine basics
 
 This section covers basic coroutine concepts.
@@ -1060,13 +1043,15 @@ fun main(args: Array<String>) = runBlocking<Unit> {
 
 ### Building channel producers
 
-The pattern where a coroutine is producing a sequence of elements into a channel is quite common.
+The pattern where a coroutine is producing a sequence of elements is quite common. 
+This is a part of _producer-consumer_ pattern that is often found in concurrent code. 
 You could abstract such a producer into a function that takes channel as its parameter, but this goes contrary
-to common sense that results must be returned from functions. Here is a convenience 
-coroutine builder named [buildChannel] that makes it easy to do it right:
+to common sense that results must be returned from functions. 
+
+There is a convenience coroutine builder named [produce] that makes it easy to do it right:
 
 ```kotlin
-fun produceSquares() = buildChannel<Int>(CommonPool) {
+fun produceSquares() = produce<Int>(CommonPool) {
     for (x in 1..5) send(x * x)
 }
 
@@ -1084,22 +1069,22 @@ fun main(args: Array<String>) = runBlocking<Unit> {
 Pipeline is a pattern where one coroutine is producing, possibly infinite, stream of values:
 
 ```kotlin
-fun produceNumbers() = buildChannel<Int>(CommonPool) {
+fun produceNumbers() = produce<Int>(CommonPool) {
     var x = 1
     while (true) send(x++) // infinite stream of integers starting from 1
 }
 ```
 
-And another coroutine or coroutines are receiving that stream, doing some processing, and sending the result.
+And another coroutine or coroutines are consuming that stream, doing some processing, and producing some other results.
 In the below example the numbers are just squared:
 
 ```kotlin
-fun square(numbers: ReceiveChannel<Int>) = buildChannel<Int>(CommonPool) {
+fun square(numbers: ReceiveChannel<Int>) = produce<Int>(CommonPool) {
     for (x in numbers) send(x * x)
 }
 ```
 
-The main code starts and connects pipeline:
+The main code starts and connects the whole pipeline:
 
 ```kotlin
 fun main(args: Array<String>) = runBlocking<Unit> {
@@ -1131,7 +1116,7 @@ import kotlin.coroutines.experimental.CoroutineContext
 -->
 
 ```kotlin
-fun numbersFrom(context: CoroutineContext, start: Int) = buildChannel<Int>(context) {
+fun numbersFrom(context: CoroutineContext, start: Int) = produce<Int>(context) {
     var x = start
     while (true) send(x++) // infinite stream of integers from start
 }
@@ -1141,7 +1126,7 @@ The following pipeline stage filters an incoming stream of numbers, removing all
 that are divisible by the given prime number:
 
 ```kotlin
-fun filter(context: CoroutineContext, numbers: ReceiveChannel<Int>, prime: Int) = buildChannel<Int>(context) {
+fun filter(context: CoroutineContext, numbers: ReceiveChannel<Int>, prime: Int) = produce<Int>(context) {
     for (x in numbers) if (x % prime != 0) send(x)
 }
 ```
@@ -1150,7 +1135,7 @@ Now we build our pipeline by starting a stream of numbers from 2, taking a prime
 and launching new pipeline stage for each prime number found:
 
 ```
-numbers -> filter(2) -> filter(3) -> filter(5) -> filter(7) ... 
+numbersFrom(2) -> filter(2) -> filter(3) -> filter(5) -> filter(7) ... 
 ``` 
 
 The following example prints the first ten prime numbers, 
@@ -1184,16 +1169,16 @@ The output of this code is:
 29
 ```
 
-Note, that you can build the same pipeline using `buildIterator` from the standard library. 
-Replace `buildSequence` with `buildIterator`, `send` with `yield`, `receive` with `next`, 
+Note, that you can build the same pipeline using `buildIterator` coroutine builder from the standard library. 
+Replace `produce` with `buildIterator`, `send` with `yield`, `receive` with `next`, 
 `ReceiveChannel` with `Iterator`, and get rid of the context. You will not need `runBlocking` either.
 However, the benefit of a pipeline that uses channels as shown above is that it can actually use 
 multiple CPU cores if you run it in [CommonPool] context.
 
-Anyway, this is an extremely impractical way to find prime numbers. In practise, pipelines do involve some
+Anyway, this is an extremely impractical way to find prime numbers. In practice, pipelines do involve some
 other suspending invocations (like asynchronous calls to remote services) and these pipelines cannot be
 built using `buildSeqeunce`/`buildIterator`, because they do not allow arbitrary suspension, unlike
-`buildChannel` which is fully asynchronous.
+`produce` which is fully asynchronous.
 
 ### Fan-out
 
@@ -1202,7 +1187,7 @@ Let us start with a producer coroutine that is periodically producing integers
 (ten numbers per second):
 
 ```kotlin
-fun produceNumbers() = buildChannel<Int>(CommonPool) {
+fun produceNumbers() = produce<Int>(CommonPool) {
     var x = 1 // start from 1
     while (true) {
         send(x++) // produce next
@@ -1303,7 +1288,7 @@ The channels shown so far had no buffer. Unbuffered channels transfer elements w
 meet each other (aka rendezvous). If send is invoked first, then it is suspended until receive is invoked, 
 if receive is invoked first, it is suspended until send is invoked.
 
-Both [Channel()][Channel.invoke] factory function and [buildChannel] builder take an optional `capacity` parameter to 
+Both [Channel()][Channel.invoke] factory function and [produce] builder take an optional `capacity` parameter to 
 specify _buffer size_. Buffer allows senders to send multiple elements before suspending, 
 similar to the `BlockingQueue` with a specified capacity, which blocks when buffer is full.
 
@@ -1369,5 +1354,5 @@ The first four elements are added to the buffer and the sender suspends when try
 [ReceiveChannel.receive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/receive.html
 [SendChannel.close]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-send-channel/close.html
 [SendChannel.send]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-send-channel/send.html
-[buildChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/build-channel.html
+[produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/produce.html
 <!--- END -->

knit/src/Knit.kt

@@ -39,11 +39,16 @@ val SECTION_START = "##"
 val API_REF_REGEX = Regex("(^|[ \\]])\\[([A-Za-z0-9_.]+)\\]($|[^\\[\\(])")
 
 fun main(args: Array<String>) {
-    if(args.size != 1) {
-        println("Usage: Knit <markdown-file>")
+    if (args.isEmpty()) {
+        println("Usage: Knit <markdown-files>")
         return
     }
-    val markdownFile = File(args[0])
+    args.forEach(::knit)
+}
+
+fun knit(markdownFileName: String) {
+    println("*** Reading $markdownFileName")
+    val markdownFile = File(markdownFileName)
     val toc = arrayListOf<String>()
     var knitRegex: Regex? = null
     val includes = arrayListOf<Include>()
@@ -122,8 +127,8 @@ fun main(args: Array<String>) {
                         }
                     }
                     skip = false
-                    postTocText += indexLines
-                    postTocText += putBackLine!!
+                    outText += indexLines
+                    outText += putBackLine!!
                 }
             }
             if (inLine.startsWith(CODE_START)) {
@@ -172,8 +177,16 @@ fun main(args: Array<String>) {
         }
     }
     // update markdown file with toc
-    val newLines = markdown.preTocText + "" + toc + "" + markdown.postTocText
-    if (newLines != markdown.allText) writeLines(markdownFile, newLines)
+    val newLines = buildList<String> {
+        addAll(markdown.preTocText)
+        if (!toc.isEmpty()) {
+            add("")
+            addAll(toc)
+            add("")
+        }
+        addAll(markdown.postTocText)
+    }
+    if (newLines != markdown.inText) writeLines(markdownFile, newLines)
     // check apiRefs
     for (apiRef in allApiRefs) {
         if (apiRef.name in remainingApiRefNames) {
@@ -182,6 +195,12 @@ fun main(args: Array<String>) {
     }
 }
 
+private inline fun <T> buildList(block: ArrayList<T>.() -> Unit): List<T> {
+    val result = arrayListOf<T>()
+    result.block()
+    return result
+}
+
 private fun requireSingleLine(directive: Directive) {
     require(directive.singleLine) { "${directive.name} directive must end on the same line with '$DIRECTIVE_END'" }
 }
@@ -212,23 +231,23 @@ class ApiRef(val line: Int, val name: String)
 enum class MarkdownPart { PRE_TOC, TOC, POST_TOC }
 
 class MarkdownTextReader(r: Reader) : LineNumberReader(r) {
-    val allText = arrayListOf<String>()
+    val inText = arrayListOf<String>()
     val preTocText = arrayListOf<String>()
     val postTocText = arrayListOf<String>()
     var markdownPart: MarkdownPart = MarkdownPart.PRE_TOC
     var skip = false
 
+    val outText: MutableList<String> get() = when (markdownPart) {
+        MarkdownPart.PRE_TOC -> preTocText
+        MarkdownPart.POST_TOC -> postTocText
+        else -> throw IllegalStateException("Wrong state: $markdownPart")
+    }
+
     override fun readLine(): String? {
         val line = super.readLine() ?: return null
-        allText += line
-        if (!skip) {
-            when (markdownPart) {
-                MarkdownPart.PRE_TOC -> preTocText += line
-                MarkdownPart.POST_TOC -> postTocText += line
-                MarkdownPart.TOC -> {
-                } // do nothing
-            }
-        }
+        inText += line
+        if (!skip && markdownPart != MarkdownPart.TOC)
+            outText += line
         return line
     }
 }

kotlinx-coroutines-core/README.md

@@ -1,32 +1,75 @@
 # Module kotlinx-coroutines-core
 
 Core primitives to work with coroutines.
+
+This module provides the following coroutine builders:
+
+| **Name**      | **Result**    | **Scope**        | **Description**
+| ------------- | ------------- | ---------------- | ---------------
+| [launch]      | [Job]         | [CoroutineScope] | Launches coroutine that does not have any result 
+| [async]       | [Deferred]    | [CoroutineScope] | Returns a single value with the future result
+| [produce]     | [ProducerJob] | [ProducerScope]  | Produces a stream of elements
+| [runBlocking] | `T`           | [CoroutineScope] | Blocks the thread while the coroutine runs
+
+These builders can be used with the following [coroutine dispatchers][CoroutineDispatcher]:
+ 
+| **Name**                    | **Description**
+| --------------------------- | ---------------
+| [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 
+| [Executor.toCoroutineDispatcher][java.util.concurrent.Executor.toCoroutineDispatcher] | Extension to convert any executor
+| [Unconfined]                | Does not confine coroutine execution in any way
+
+The following top-level suspending functions are provided to be used _inside coroutines_:
+
+| **Name**      | **Description**
+| ------------- | ---------------
+| [delay]       | Non-blocking sleep
+| [yield]       | Yields thread in single-threaded dispatchers
+| [run]         | Switches to a different context
+| [withTimeout] | Set execution time-limit (deadline)
+
+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.
+
+This module provides debugging facilities for coroutines (run JVM with `-ea` or `-Dkotlinx.coroutines.debug` options) 
+and [newCoroutineContext] function to write user-defined coroutine builders that work with these
+debugging facilities.
+
+<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
+<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
+<!--- INDEX kotlinx.coroutines.experimental -->
+[CommonPool]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-common-pool/index.html
+[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
+[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
+[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
+[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
+[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
+[Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-unconfined/index.html
+[java.util.concurrent.Executor.toCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/java.util.concurrent.-executor/to-coroutine-dispatcher.html
+[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/async.html
+[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html
+[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
+[newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-coroutine-context.html
+[newFixedThreadPoolContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-fixed-thread-pool-context.html
+[newSingleThreadContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-single-thread-context.html
+[run]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run.html
+[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
+[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
+[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout.html
+[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
+<!--- INDEX kotlinx.coroutines.experimental.channels -->
+[ProducerJob]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-producer-job/index.html
+[ProducerScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-producer-scope/index.html
+[produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/produce.html
+<!--- END -->
 
 # Package kotlinx.coroutines.experimental
 
-General-purpose coroutine builders and contexts.
-
-* `launch(context) {...}` to start a coroutine in the given context and get reference to its `Job`.
-* `run(context) {...}` to switch to a different context inside a coroutine.
-* `runBlocking {...}` to use asynchronous Kotlin APIs from a thread-blocking code.  
-* `async(context) {...}` to get a deferred result of coroutine execution in a 
-   non-blocking way via a light-weight future interface called `Deferred`.
-* `delay(...)` for a non-blocking sleep in coroutines and 
-  `yield()` to release a thread in single-threaded dispatchers.
-* `withTimeout(timeout) {...}` scope function to easily set coroutine time-limit (deadline),
-   and `NonCancellable` context to avoid it when needed.
-* `CommonPool` and `Unconfined` contexts, access to `context` of a parent coroutine in its `CoroutineScope`.
-* `newSingleThreadContext(...)` and `newFixedThreadPoolContext(...)` functions, 
-  `Executor.toCoroutineDispatcher()` extension.
-* Cancellation support with `Job` interface and `suspendCancellableCoroutine` helper function.
-* Debugging facilities for coroutines (run JVM with `-ea` or `-Dkotlinx.coroutines.debug` options) and
-  `newCoroutineContext(context)` function to write user-defined coroutine builders that work with these
-   debugging facilities.
+General-purpose coroutine builders, contexts, and helper functions.
 
 # Package kotlinx.coroutines.experimental.channels
 
-Channels -- non-blocking primitives for communicating a stream of values between coroutines.
-
-* `Channel`, `SendChannel`, and `ReceiveChannel` interfaces,
-* `RendezvousChannel` (unbuffered) and `ArrayChannel` (buffered) implementations
-* `Channel()` factory function and `buildChannel{}` coroutines builder.
+Channels -- non-blocking primitives for communicating a stream of elements between coroutines.