Guide to select

Author: elizarov

coroutines-guide.md

@@ -117,7 +117,7 @@ fun knit(markdownFileName: String) {
                     requireSingleLine(directive)
                     require(siteRoot != null) { "$SITE_ROOT_DIRECTIVE must be specified" }
                     require(docsRoot != null) { "$DOCS_ROOT_DIRECTIVE must be specified" }
-                    val indexLines = readApiIndex(directive.param, remainingApiRefNames, siteRoot!!, docsRoot!!)
+                    val indexLines = processApiIndex(siteRoot!!, docsRoot!!, directive.param, remainingApiRefNames)
                     skip = true
                     while (true) {
                         val skipLine = readLine() ?: break@mainLoop
@@ -275,38 +275,62 @@ fun writeLines(file: File, lines: List<String>) {
     }
 }
 
+data class ApiIndexKey(
+    val docsRoot: String,
+    val pkg: String
+)
+
+val apiIndexCache: MutableMap<ApiIndexKey, Map<String, String>> = HashMap()
+
 val REF_LINE_REGEX = Regex("<a href=\"([a-z/.\\-]+)\">([a-zA-z.]+)</a>")
 val INDEX_HTML = "/index.html"
 val INDEX_MD = "/index.md"
 
-fun readApiIndex(
-        path: String,
-        remainingApiRefNames: MutableSet<String>,
-        siteRoot: String,
-        docsRoot: String,
-        prefix: String = ""
-): List<String> {
+fun loadApiIndex(
+    docsRoot: String,
+    path: String,
+    pkg: String,
+    namePrefix: String = ""
+): Map<String, String> {
     val fileName = docsRoot + "/" + path + INDEX_MD
     println("Reading index from $fileName")
-    val indexList = arrayListOf<String>()
     val visited = mutableSetOf<String>()
+    val map = HashMap<String,String>()
     File(fileName).withLineNumberReader<LineNumberReader>(::LineNumberReader) {
         while (true) {
             val line = readLine() ?: break
             val result = REF_LINE_REGEX.matchEntire(line) ?: continue
             val refLink = result.groups[1]!!.value
             if (refLink.startsWith("..")) continue // ignore cross-references
-            val refName = prefix + result.groups[2]!!.value
-            if (remainingApiRefNames.remove(refName)) {
-                indexList += "[$refName]: $siteRoot/$path/$refLink"
-            }
+            val refName = namePrefix + result.groups[2]!!.value
+            map.put(refName, refLink)
+            map.put(pkg + "." + refName, refLink)
             if (refLink.endsWith(INDEX_HTML)) {
                 if (visited.add(refLink)) {
                     val path2 = path + "/" + refLink.substring(0, refLink.length - INDEX_HTML.length)
-                    indexList += readApiIndex(path2, remainingApiRefNames, siteRoot, docsRoot, refName + ".")
+                    map += loadApiIndex(docsRoot, path2, pkg, refName + ".")
                 }
             }
         }
     }
+    return map
+}
+
+fun processApiIndex(
+    siteRoot: String,
+    docsRoot: String,
+    pkg: String,
+    remainingApiRefNames: MutableSet<String>
+): List<String> {
+    val key = ApiIndexKey(docsRoot, pkg)
+    val map = apiIndexCache.getOrPut(key, { loadApiIndex(docsRoot, pkg, pkg) })
+    val indexList = arrayListOf<String>()
+    val it = remainingApiRefNames.iterator()
+    while (it.hasNext()) {
+        val refName = it.next()
+        val refLink = map[refName] ?: continue
+        indexList += "[$refName]: $siteRoot/$pkg/$refLink"
+        it.remove()
+    }
     return indexList
-}
+}

knit/src/Knit.kt

@@ -37,6 +37,15 @@ Top-level suspending functions:
 | [run]         | Switches to a different context
 | [withTimeout] | Set execution time-limit (deadline)
 
+[Select][kotlinx.coroutines.experimental.selects.select] expression waits for the result of multiple suspending functions simultaneously:
+
+| **Receiver**     | **Suspending function**                       | **Select clause**                                | **Non-suspending version**
+| ---------------- | --------------------------------------------- | ------------------------------------------------ | --------------------------
+| [Deferred]       | [await][Deferred.await]                       | [onAwait][SelectBuilder.onAwait]                 | [isCompleted][Deferred.isCompleted]
+| [SendChannel]    | [send][SendChannel.send]                      | [onSend][SelectBuilder.onSend]                   | [offer][SendChannel.offer]
+| [ReceiveChannel] | [receive][ReceiveChannel.receive]             | [onReceive][SelectBuilder.onReceive]             | [poll][ReceiveChannel.poll]
+| [ReceiveChannel] | [receiveOrNull][ReceiveChannel.receiveOrNull] | [onReceiveOrNull][SelectBuilder.onReceiveOrNull] | [poll][ReceiveChannel.poll]
+
 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.
@@ -45,43 +54,57 @@ This module provides debugging facilities for coroutines (run JVM with `-ea` or
 and [newCoroutineContext] function to write user-defined coroutine builders that work with these
 debugging facilities.
 
+# Package kotlinx.coroutines.experimental
+
+General-purpose coroutine builders, contexts, and helper functions.
+
+# Package kotlinx.coroutines.experimental.channels
+
+Channels -- non-blocking primitives for communicating a stream of elements between coroutines.
+
+# Package kotlinx.coroutines.experimental.selects
+
+Select expression to perform multiple suspending operations simultaneously until one of them succeeds.
+
 <!--- 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
+[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
+[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
 [CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
+[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
-[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
-[Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-mutex/index.html
-[Mutex.lock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-mutex/lock.html
-[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/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
+[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
+[java.util.concurrent.Executor.toCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/to-coroutine-dispatcher.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
+[Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-mutex/index.html
+[Mutex.lock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/lock.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
+[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.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
+[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
+[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
+[newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-coroutine-context.html
 <!--- INDEX kotlinx.coroutines.experimental.channels -->
-[Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel/index.html
+[produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/produce.html
 [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
-[ReceiveChannel.receive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/receive.html
-[SendChannel.send]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-send-channel/send.html
-[produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/produce.html
+[Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel/index.html
+[SendChannel.send]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/send.html
+[ReceiveChannel.receive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/receive.html
+[SendChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-send-channel/index.html
+[SendChannel.offer]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/offer.html
+[ReceiveChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/index.html
+[ReceiveChannel.poll]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/poll.html
+[ReceiveChannel.receiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/receive-or-null.html
+<!--- INDEX kotlinx.coroutines.experimental.selects -->
+[kotlinx.coroutines.experimental.selects.select]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/select.html
+[SelectBuilder.onSend]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-send.html
+[SelectBuilder.onReceive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-receive.html
+[SelectBuilder.onReceiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-receive-or-null.html
 <!--- END -->
- 
-# Package kotlinx.coroutines.experimental
-
-General-purpose coroutine builders, contexts, and helper functions.
-
-# Package kotlinx.coroutines.experimental.channels
-
-Channels -- non-blocking primitives for communicating a stream of elements between coroutines.

kotlinx-coroutines-core/README.md

@@ -0,0 +1,53 @@
+/*
+ * 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.select.example01
+
+import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.selects.*
+
+val fizz = produce<String>(CommonPool) { // produce using common thread pool
+    while (true) {
+        delay(300)
+        send("Fizz")
+    }
+}
+
+val buzz = produce<String>(CommonPool) {
+    while (true) {
+        delay(500)
+        send("Buzz!")
+    }
+}
+
+suspend fun selectFizzBuzz() {
+    select<Unit> { // <Unit> means that this select expression does not produce any result 
+        fizz.onReceive { value ->  // this is the first select clause
+            println("fizz -> '$value'")
+        }
+        buzz.onReceive { value ->  // this is the second select clause
+            println("buzz -> '$value'")
+        }
+    }
+}
+
+fun main(args: Array<String>) = runBlocking<Unit> {
+    repeat(7) {
+        selectFizzBuzz()
+    }
+}

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

@@ -0,0 +1,55 @@
+/*
+ * 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.select.example02
+
+import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.selects.*
+
+suspend fun selectAorB(a: ReceiveChannel<String>, b: ReceiveChannel<String>): String =
+    select<String> {
+        a.onReceiveOrNull { value -> 
+            if (value == null) 
+                "Channel 'a' is closed" 
+            else 
+                "a -> '$value'"
+        }
+        b.onReceiveOrNull { value -> 
+            if (value == null) 
+                "Channel 'b' is closed"
+            else    
+                "b -> '$value'"
+        }
+    }
+
+fun main(args: Array<String>) = runBlocking<Unit> {
+    // we are using the context of the main thread in this example for predictability ... 
+    val a = produce<String>(context) { 
+        repeat(4) {
+            send("Hello $it")
+        }
+    }
+    val b = produce<String>(context) { 
+        repeat(4) {
+            send("World $it")
+        }
+    }
+    repeat(8) { // print first eight results
+        println(selectAorB(a, b))
+    }
+}

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

@@ -0,0 +1,44 @@
+/*
+ * 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.select.example03
+
+import kotlinx.coroutines.experimental.*
+import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.selects.*
+
+fun produceNumbers(side: SendChannel<Int>) = produce<Int>(CommonPool) {
+    for (num in 1..10) { // produce 10 numbers from 1 to 10
+        delay(100) // every 100 ms
+        select<Unit> {
+            onSend(num) { } // Send to the primary channel
+            side.onSend(num) { } // or to the side channel     
+        }
+    }
+}
+
+fun main(args: Array<String>) = runBlocking<Unit> {
+    val side = Channel<Int>() // allocate side channel
+    launch(context) { // this is a very fast consumer for the side channel
+        for (num in side) println("Side channel has $num")
+    }
+    for (num in produceNumbers(side)) {
+        println("Consuming $num")
+        delay(250) // let us digest the consumed number properly, do not hurry
+    }
+    println("Done consuming")
+}