Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 1 | /* |
Roman Elizarov | 1f74a2d | 2018-06-29 19:19:45 +0300 | [diff] [blame] | 2 | * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 3 | */ |
| 4 | |
Roman Elizarov | 0950dfa | 2018-07-13 10:33:25 +0300 | [diff] [blame] | 5 | @file:UseExperimental(ExperimentalTypeInference::class) |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 6 | |
Roman Elizarov | 0950dfa | 2018-07-13 10:33:25 +0300 | [diff] [blame] | 7 | package kotlinx.coroutines.channels |
| 8 | |
| 9 | import kotlinx.coroutines.* |
| 10 | import kotlinx.coroutines.channels.Channel.Factory.UNLIMITED |
| 11 | import kotlin.coroutines.* |
| 12 | import kotlin.experimental.* |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 13 | |
| 14 | /** |
Roman Elizarov | c32579e | 2018-09-09 19:21:43 +0300 | [diff] [blame] | 15 | * Scope for [produce][CoroutineScope.produce] coroutine builder. |
Roman Elizarov | 27b8f45 | 2018-09-20 21:23:41 +0300 | [diff] [blame] | 16 | * |
| 17 | * **Note: This is an experimental api.** Behaviour of producers that work as children in a parent scope with respect |
| 18 | * to cancellation and error handling may change in the future. |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 19 | */ |
Roman Elizarov | 27b8f45 | 2018-09-20 21:23:41 +0300 | [diff] [blame] | 20 | @ExperimentalCoroutinesApi |
Roman Elizarov | f1d9a4e | 2017-04-05 10:53:14 +0300 | [diff] [blame] | 21 | public interface ProducerScope<in E> : CoroutineScope, SendChannel<E> { |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 22 | /** |
| 23 | * A reference to the channel that this coroutine [sends][send] elements to. |
| 24 | * It is provided for convenience, so that the code in the coroutine can refer |
| 25 | * to the channel as `channel` as apposed to `this`. |
| 26 | * All the [SendChannel] functions on this interface delegate to |
| 27 | * the channel instance returned by this function. |
| 28 | */ |
Roman Elizarov | f1d9a4e | 2017-04-05 10:53:14 +0300 | [diff] [blame] | 29 | val channel: SendChannel<E> |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 30 | } |
| 31 | |
| 32 | /** |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 33 | * Launches new coroutine to produce a stream of values by sending them to a channel |
Roman Elizarov | b555d91 | 2017-08-17 21:01:33 +0300 | [diff] [blame] | 34 | * and returns a reference to the coroutine as a [ReceiveChannel]. This resulting |
Roman Elizarov | c0e19f8 | 2017-02-27 11:59:14 +0300 | [diff] [blame] | 35 | * object can be used to [receive][ReceiveChannel.receive] elements produced by this coroutine. |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 36 | * |
| 37 | * The scope of the coroutine contains [ProducerScope] interface, which implements |
| 38 | * both [CoroutineScope] and [SendChannel], so that coroutine can invoke |
| 39 | * [send][SendChannel.send] directly. The channel is [closed][SendChannel.close] |
| 40 | * when the coroutine completes. |
Roman Elizarov | b555d91 | 2017-08-17 21:01:33 +0300 | [diff] [blame] | 41 | * The running coroutine is cancelled when its receive channel is [cancelled][ReceiveChannel.cancel]. |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 42 | * |
Vsevolod Tolstopyatov | 79414ec | 2018-08-30 16:50:56 +0300 | [diff] [blame] | 43 | * Coroutine context is inherited from a [CoroutineScope], additional context elements can be specified with [context] argument. |
Roman Elizarov | dc29b07 | 2018-09-11 18:42:03 +0300 | [diff] [blame] | 44 | * If the context does not have any dispatcher nor any other [ContinuationInterceptor], then [Dispatchers.Default] is used. |
Vsevolod Tolstopyatov | 79414ec | 2018-08-30 16:50:56 +0300 | [diff] [blame] | 45 | * The parent job is inherited from a [CoroutineScope] as well, but it can also be overridden |
| 46 | * with corresponding [coroutineContext] element. |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 47 | * |
| 48 | * Uncaught exceptions in this coroutine close the channel with this exception as a cause and |
| 49 | * the resulting channel becomes _failed_, so that any attempt to receive from such a channel throws exception. |
| 50 | * |
Roman Elizarov | 5633f91 | 2018-09-23 19:08:36 +0300 | [diff] [blame] | 51 | * The kind of the resulting channel depends on the specified [capacity] parameter. |
| 52 | * See [Channel] interface documentation for details. |
Roman Elizarov | 89f8ff7 | 2018-03-14 13:39:03 +0300 | [diff] [blame] | 53 | * |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 54 | * See [newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine. |
Roman Elizarov | c0e19f8 | 2017-02-27 11:59:14 +0300 | [diff] [blame] | 55 | * |
Roman Elizarov | 27b8f45 | 2018-09-20 21:23:41 +0300 | [diff] [blame] | 56 | * **Note: This is an experimental api.** Behaviour of producers that work as children in a parent scope with respect |
| 57 | * to cancellation and error handling may change in the future. |
| 58 | * |
Roman Elizarov | dc29b07 | 2018-09-11 18:42:03 +0300 | [diff] [blame] | 59 | * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine. |
Roman Elizarov | c0d559b | 2017-09-28 14:27:05 +0300 | [diff] [blame] | 60 | * @param capacity capacity of the channel's buffer (no buffer by default). |
| 61 | * @param block the coroutine code. |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 62 | */ |
Roman Elizarov | 27b8f45 | 2018-09-20 21:23:41 +0300 | [diff] [blame] | 63 | @ExperimentalCoroutinesApi |
Roman Elizarov | 0950dfa | 2018-07-13 10:33:25 +0300 | [diff] [blame] | 64 | @BuilderInference |
Roman Elizarov | 27b8f45 | 2018-09-20 21:23:41 +0300 | [diff] [blame] | 65 | public fun <E> CoroutineScope.produce( |
| 66 | context: CoroutineContext = EmptyCoroutineContext, |
| 67 | capacity: Int = 0, |
Roman Elizarov | 0950dfa | 2018-07-13 10:33:25 +0300 | [diff] [blame] | 68 | @BuilderInference block: suspend ProducerScope<E>.() -> Unit |
Roman Elizarov | 27b8f45 | 2018-09-20 21:23:41 +0300 | [diff] [blame] | 69 | ): ReceiveChannel<E> { |
| 70 | val channel = Channel<E>(capacity) |
| 71 | val newContext = newCoroutineContext(context) |
| 72 | val coroutine = ProducerCoroutine(newContext, channel) |
| 73 | coroutine.start(CoroutineStart.DEFAULT, coroutine, block) |
| 74 | return coroutine |
| 75 | } |
| 76 | |
| 77 | /** |
| 78 | * @suppress **This an internal API and should not be used from general code.** |
| 79 | * onCompletion parameter will be redesigned. |
| 80 | */ |
Roman Elizarov | 0950dfa | 2018-07-13 10:33:25 +0300 | [diff] [blame] | 81 | @BuilderInference |
Roman Elizarov | 27b8f45 | 2018-09-20 21:23:41 +0300 | [diff] [blame] | 82 | @InternalCoroutinesApi |
Vsevolod Tolstopyatov | 79414ec | 2018-08-30 16:50:56 +0300 | [diff] [blame] | 83 | public fun <E> CoroutineScope.produce( |
| 84 | context: CoroutineContext = EmptyCoroutineContext, |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 85 | capacity: Int = 0, |
Roman Elizarov | 55a66ac | 2018-03-12 20:15:07 +0300 | [diff] [blame] | 86 | onCompletion: CompletionHandler? = null, |
Roman Elizarov | 0950dfa | 2018-07-13 10:33:25 +0300 | [diff] [blame] | 87 | @BuilderInference block: suspend ProducerScope<E>.() -> Unit |
Roman Elizarov | b555d91 | 2017-08-17 21:01:33 +0300 | [diff] [blame] | 88 | ): ReceiveChannel<E> { |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 89 | val channel = Channel<E>(capacity) |
Vsevolod Tolstopyatov | 79414ec | 2018-08-30 16:50:56 +0300 | [diff] [blame] | 90 | val newContext = newCoroutineContext(context) |
Roman Elizarov | e8f694e | 2017-11-28 10:12:00 +0300 | [diff] [blame] | 91 | val coroutine = ProducerCoroutine(newContext, channel) |
Roman Elizarov | 55a66ac | 2018-03-12 20:15:07 +0300 | [diff] [blame] | 92 | if (onCompletion != null) coroutine.invokeOnCompletion(handler = onCompletion) |
Roman Elizarov | 2adf8bc | 2018-01-24 20:09:57 +0300 | [diff] [blame] | 93 | coroutine.start(CoroutineStart.DEFAULT, coroutine, block) |
Roman Elizarov | e8f694e | 2017-11-28 10:12:00 +0300 | [diff] [blame] | 94 | return coroutine |
Roman Elizarov | a5e653f | 2017-02-13 13:49:55 +0300 | [diff] [blame] | 95 | } |
| 96 | |
Roman Elizarov | 9faa61e | 2018-02-22 23:20:28 +0300 | [diff] [blame] | 97 | private class ProducerCoroutine<E>( |
| 98 | parentContext: CoroutineContext, channel: Channel<E> |
Vsevolod Tolstopyatov | d92b0fa | 2018-10-08 19:41:18 +0300 | [diff] [blame^] | 99 | ) : ChannelCoroutine<E>(parentContext, channel, active = true), ProducerScope<E> { |
Vsevolod Tolstopyatov | 79414ec | 2018-08-30 16:50:56 +0300 | [diff] [blame] | 100 | override val isActive: Boolean |
Vsevolod Tolstopyatov | d92b0fa | 2018-10-08 19:41:18 +0300 | [diff] [blame^] | 101 | get() = super.isActive |
Vsevolod Tolstopyatov | 79414ec | 2018-08-30 16:50:56 +0300 | [diff] [blame] | 102 | |
Roman Elizarov | ecbc85c | 2018-09-14 12:52:50 +0300 | [diff] [blame] | 103 | override fun onCompletionInternal(state: Any?, mode: Int, suppressed: Boolean) { |
| 104 | val cause = (state as? CompletedExceptionally)?.cause |
Roman Elizarov | 6685fd0 | 2018-09-25 13:23:53 +0300 | [diff] [blame] | 105 | val processed = _channel.close(cause) |
Roman Elizarov | ecbc85c | 2018-09-14 12:52:50 +0300 | [diff] [blame] | 106 | if (cause != null && !processed && suppressed) handleExceptionViaHandler(context, cause) |
Roman Elizarov | 9faa61e | 2018-02-22 23:20:28 +0300 | [diff] [blame] | 107 | } |
| 108 | } |