buildChannel is renamed to produce
top-level readme file for kotlinx-coroutines-core module is improved:
Better grouping and list of all available features
diff --git a/kotlinx-coroutines-core/README.md b/kotlinx-coroutines-core/README.md
index 8a5d263..1a0808b 100644
--- a/kotlinx-coroutines-core/README.md
+++ b/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.
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/ChannelBuilder.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/ChannelBuilder.kt
deleted file mode 100644
index 6f5e652..0000000
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/ChannelBuilder.kt
+++ /dev/null
@@ -1,73 +0,0 @@
-/*
- * 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.
- */
-
-package kotlinx.coroutines.experimental.channels
-
-import kotlinx.coroutines.experimental.*
-import kotlin.coroutines.experimental.*
-
-/**
- * Scope for [buildChannel].
- */
-public interface ChannelBuilder<in E> : CoroutineScope, SendChannel<E>
-
-/**
- * Return type for [buildChannel].
- */
-public interface ChannelJob<out E> : Job, ReceiveChannel<E>
-
-/**
- * Launches new coroutine without blocking current thread to send data over channel
- * and returns a reference to the coroutine as a [ChannelJob], which implements
- * both [Job] and [ReceiveChannel].
- * The scope of the coroutine contains [ChannelBuilder] interface, which implements
- * both [CoroutineScope] and [SendChannel], so that coroutine can invoke
- * [send][SendChannel.send] directly. The channel is [closed][SendChannel.close]
- * 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][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.
- *
- * Uncaught exceptions in this coroutine close the channel with this exception as a cause and
- * the resulting channel becomes _failed_, so that any attempt to receive from such a channel throws exception.
- *
- * See [newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
- */
-public fun <E> buildChannel(
- context: CoroutineContext,
- capacity: Int = 0,
- block: suspend ChannelBuilder<E>.() -> Unit
-): ChannelJob<E> {
- val channel = Channel<E>(capacity)
- return ChannelCoroutine(newCoroutineContext(context), channel).apply {
- initParentJob(context[Job])
- block.startCoroutine(this, this)
- }
-}
-
-private class ChannelCoroutine<E>(
- context: CoroutineContext,
- val channel: Channel<E>
-) : AbstractCoroutine<Unit>(context, active = true), ChannelBuilder<E>, ChannelJob<E>, Channel<E> by channel {
- override fun afterCompletion(state: Any?) {
- val cause = (state as? CompletedExceptionally)?.exception
- if (!channel.close(cause) && cause != null)
- handleCoroutineException(context, cause)
- }
-}
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/Produce.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/Produce.kt
new file mode 100644
index 0000000..148e08b
--- /dev/null
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/Produce.kt
@@ -0,0 +1,113 @@
+/*
+ * 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.
+ */
+
+package kotlinx.coroutines.experimental.channels
+
+import kotlinx.coroutines.experimental.*
+import kotlin.coroutines.experimental.CoroutineContext
+import kotlin.coroutines.experimental.startCoroutine
+
+/**
+ * Scope for [produce] coroutine builder.
+ */
+public interface ProducerScope<in E> : CoroutineScope, SendChannel<E> {
+ /**
+ * A reference to the channel that this coroutine [sends][send] elements to.
+ * It is provided for convenience, so that the code in the coroutine can refer
+ * to the channel as `channel` as apposed to `this`.
+ * All the [SendChannel] functions on this interface delegate to
+ * the channel instance returned by this function.
+ */
+ val channel: SendChannel<E>
+}
+
+/**
+ * @suppress **Deprecated**: Renamed to `ProducerScope`.
+ */
+@Deprecated(message = "Renamed to `ProducerScope`", replaceWith = ReplaceWith("ProducerScope"))
+typealias ChannelBuilder<E> = ProducerScope<E>
+
+/**
+ * Return type for [produce] coroutine builder.
+ */
+public interface ProducerJob<out E> : Job, ReceiveChannel<E> {
+ /**
+ * A reference to the channel that this coroutine is producing.
+ * All the [ReceiveChannel] functions on this interface delegate to
+ * the channel instance returned by this function.
+ */
+ val channel: ReceiveChannel<E>
+}
+
+/**
+ * @suppress **Deprecated**: Renamed to `ProducerJob`.
+ */
+@Deprecated(message = "Renamed to `ProducerJob`", replaceWith = ReplaceWith("ProducerJob"))
+typealias ChannelJob<E> = ProducerJob<E>
+
+/**
+ * Launches new coroutine to produce a stream of values by sending them to a channel
+ * and returns a reference to the coroutine as a [ProducerJob].
+ *
+ * The scope of the coroutine contains [ProducerScope] interface, which implements
+ * both [CoroutineScope] and [SendChannel], so that coroutine can invoke
+ * [send][SendChannel.send] directly. The channel is [closed][SendChannel.close]
+ * 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][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.
+ *
+ * Uncaught exceptions in this coroutine close the channel with this exception as a cause and
+ * the resulting channel becomes _failed_, so that any attempt to receive from such a channel throws exception.
+ *
+ * See [newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
+ */
+public fun <E> produce(
+ context: CoroutineContext,
+ capacity: Int = 0,
+ block: suspend ProducerScope<E>.() -> Unit
+): ProducerJob<E> {
+ val channel = Channel<E>(capacity)
+ return ProducerCoroutine(newCoroutineContext(context), channel).apply {
+ initParentJob(context[Job])
+ block.startCoroutine(this, this)
+ }
+}
+
+/**
+ * @suppress **Deprecated**: Renamed to `produce`.
+ */
+@Deprecated(message = "Renamed to `produce`", replaceWith = ReplaceWith("produce"))
+public fun <E> buildChannel(
+ context: CoroutineContext,
+ capacity: Int = 0,
+ block: suspend ProducerScope<E>.() -> Unit
+): ProducerJob<E> =
+ produce(context, capacity, block)
+
+private class ProducerCoroutine<E>(
+ context: CoroutineContext,
+ override val channel: Channel<E>
+) : AbstractCoroutine<Unit>(context, active = true), ProducerScope<E>, ProducerJob<E>, Channel<E> by channel {
+ override fun afterCompletion(state: Any?) {
+ val cause = (state as? CompletedExceptionally)?.exception
+ if (!channel.close(cause) && cause != null)
+ handleCoroutineException(context, cause)
+ }
+}
diff --git a/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-03.kt b/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-03.kt
index aad1e10..db6bf84 100644
--- a/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-03.kt
+++ b/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-03.kt
@@ -17,10 +17,11 @@
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
package guide.channel.example03
-import kotlinx.coroutines.experimental.*
-import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.CommonPool
+import kotlinx.coroutines.experimental.channels.produce
+import kotlinx.coroutines.experimental.runBlocking
-fun produceSquares() = buildChannel<Int>(CommonPool) {
+fun produceSquares() = produce<Int>(CommonPool) {
for (x in 1..5) send(x * x)
}
diff --git a/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-04.kt b/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-04.kt
index c5910e1..7cbfb6a 100644
--- a/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-04.kt
+++ b/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-04.kt
@@ -17,15 +17,17 @@
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
package guide.channel.example04
-import kotlinx.coroutines.experimental.*
-import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.CommonPool
+import kotlinx.coroutines.experimental.channels.ReceiveChannel
+import kotlinx.coroutines.experimental.channels.produce
+import kotlinx.coroutines.experimental.runBlocking
-fun produceNumbers() = buildChannel<Int>(CommonPool) {
+fun produceNumbers() = produce<Int>(CommonPool) {
var x = 1
while (true) send(x++) // infinite stream of integers starting from 1
}
-fun square(numbers: ReceiveChannel<Int>) = buildChannel<Int>(CommonPool) {
+fun square(numbers: ReceiveChannel<Int>) = produce<Int>(CommonPool) {
for (x in numbers) send(x * x)
}
diff --git a/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-05.kt b/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-05.kt
index a87f95a..5b46862 100644
--- a/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-05.kt
+++ b/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-05.kt
@@ -17,16 +17,17 @@
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
package guide.channel.example05
-import kotlinx.coroutines.experimental.*
-import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.channels.ReceiveChannel
+import kotlinx.coroutines.experimental.channels.produce
+import kotlinx.coroutines.experimental.runBlocking
import kotlin.coroutines.experimental.CoroutineContext
-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
}
-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)
}
diff --git a/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-06.kt b/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-06.kt
index eacf57c..5781836 100644
--- a/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-06.kt
+++ b/kotlinx-coroutines-core/src/test/kotlin/guide/example-channel-06.kt
@@ -17,10 +17,14 @@
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
package guide.channel.example06
-import kotlinx.coroutines.experimental.*
-import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.CommonPool
+import kotlinx.coroutines.experimental.channels.ReceiveChannel
+import kotlinx.coroutines.experimental.channels.produce
+import kotlinx.coroutines.experimental.delay
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
-fun produceNumbers() = buildChannel<Int>(CommonPool) {
+fun produceNumbers() = produce<Int>(CommonPool) {
var x = 1 // start from 1
while (true) {
send(x++) // produce next
diff --git a/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/channels/RendezvousChannelTest.kt b/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/channels/RendezvousChannelTest.kt
index 7c66723..4a05ef3 100644
--- a/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/channels/RendezvousChannelTest.kt
+++ b/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/channels/RendezvousChannelTest.kt
@@ -16,9 +16,12 @@
package kotlinx.coroutines.experimental.channels
-import kotlinx.coroutines.experimental.*
-import org.junit.Test
+import kotlinx.coroutines.experimental.TestBase
+import kotlinx.coroutines.experimental.launch
+import kotlinx.coroutines.experimental.runBlocking
+import kotlinx.coroutines.experimental.yield
import org.junit.Assert.*
+import org.junit.Test
class RendezvousChannelTest : TestBase() {
@Test
@@ -251,9 +254,9 @@
}
@Test
- fun testDeferBadClass() = runBlocking {
+ fun testProduceBadClass() = runBlocking {
val bad = BadClass()
- val c = buildChannel(context) {
+ val c = produce(context) {
expect(1)
send(bad)
}