Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +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 | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 3 | */ |
| 4 | |
| 5 | package kotlinx.coroutines.experimental.channels |
| 6 | |
Vsevolod Tolstopyatov | 9619134 | 2018-04-20 18:13:33 +0300 | [diff] [blame] | 7 | import kotlinx.coroutines.experimental.* |
Roman Elizarov | 8385ec9 | 2017-05-11 18:32:52 +0300 | [diff] [blame] | 8 | import kotlinx.coroutines.experimental.channels.Channel.Factory.CONFLATED |
| 9 | import kotlinx.coroutines.experimental.channels.Channel.Factory.UNLIMITED |
Roman Elizarov | c8af35c | 2018-05-16 20:23:37 +0300 | [diff] [blame] | 10 | import kotlinx.coroutines.experimental.internal.* |
Roman Elizarov | f5f0983 | 2018-05-16 15:10:28 +0300 | [diff] [blame] | 11 | import kotlinx.coroutines.experimental.internalAnnotations.* |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 12 | |
| 13 | /** |
| 14 | * Broadcast channel is a non-blocking primitive for communication between the sender and multiple receivers |
Marko Devcic | 1d6230a | 2018-04-04 20:13:08 +0200 | [diff] [blame] | 15 | * that subscribe for the elements using [openSubscription] function and unsubscribe using [ReceiveChannel.cancel] |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 16 | * function. |
Roman Elizarov | 8385ec9 | 2017-05-11 18:32:52 +0300 | [diff] [blame] | 17 | * |
Roman Elizarov | 3638747 | 2017-07-21 18:37:49 +0300 | [diff] [blame] | 18 | * See `BroadcastChannel()` factory function for the description of available |
Roman Elizarov | 8385ec9 | 2017-05-11 18:32:52 +0300 | [diff] [blame] | 19 | * broadcast channel implementations. |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 20 | */ |
| 21 | public interface BroadcastChannel<E> : SendChannel<E> { |
| 22 | /** |
Roman Elizarov | 8385ec9 | 2017-05-11 18:32:52 +0300 | [diff] [blame] | 23 | * Factory for broadcast channels. |
Roman Elizarov | 3638747 | 2017-07-21 18:37:49 +0300 | [diff] [blame] | 24 | * @suppress **Deprecated** |
Roman Elizarov | 8385ec9 | 2017-05-11 18:32:52 +0300 | [diff] [blame] | 25 | */ |
| 26 | public companion object Factory { |
| 27 | /** |
| 28 | * Creates a broadcast channel with the specified buffer capacity. |
Roman Elizarov | 3638747 | 2017-07-21 18:37:49 +0300 | [diff] [blame] | 29 | * @suppress **Deprecated** |
Roman Elizarov | 8385ec9 | 2017-05-11 18:32:52 +0300 | [diff] [blame] | 30 | */ |
Roman Elizarov | 3638747 | 2017-07-21 18:37:49 +0300 | [diff] [blame] | 31 | @Deprecated("Replaced with top-level function", level = DeprecationLevel.HIDDEN) |
| 32 | public operator fun <E> invoke(capacity: Int): BroadcastChannel<E> = BroadcastChannel(capacity) |
Roman Elizarov | 8385ec9 | 2017-05-11 18:32:52 +0300 | [diff] [blame] | 33 | } |
| 34 | |
| 35 | /** |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 36 | * Subscribes to this [BroadcastChannel] and returns a channel to receive elements from it. |
Marko Devcic | 1d6230a | 2018-04-04 20:13:08 +0200 | [diff] [blame] | 37 | * The resulting channel shall be [cancelled][ReceiveChannel.cancel] to unsubscribe from this |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 38 | * broadcast channel. |
| 39 | */ |
Marko Devcic | 1d6230a | 2018-04-04 20:13:08 +0200 | [diff] [blame] | 40 | public fun openSubscription(): ReceiveChannel<E> |
Roman Elizarov | 0f66a6d | 2017-06-22 14:57:53 +0300 | [diff] [blame] | 41 | |
| 42 | /** |
Roman Elizarov | f5f0983 | 2018-05-16 15:10:28 +0300 | [diff] [blame] | 43 | * @suppress **Deprecated**: Return type changed to `ReceiveChannel`, this one left here for binary compatibility. |
| 44 | */ |
| 45 | @Deprecated(level = DeprecationLevel.HIDDEN, message = "Return type changed to `ReceiveChannel`, this one left here for binary compatibility") |
Roman Elizarov | c8af35c | 2018-05-16 20:23:37 +0300 | [diff] [blame] | 46 | @JvmName("openSubscription") |
| 47 | @Suppress("INAPPLICABLE_JVM_NAME") |
| 48 | public fun openSubscription1(): SubscriptionReceiveChannel<E> = openSubscription() as SubscriptionReceiveChannel<E> |
Roman Elizarov | f5f0983 | 2018-05-16 15:10:28 +0300 | [diff] [blame] | 49 | |
| 50 | /** |
Roman Elizarov | 0f66a6d | 2017-06-22 14:57:53 +0300 | [diff] [blame] | 51 | * @suppress **Deprecated**: Renamed to [openSubscription] |
| 52 | */ |
| 53 | @Deprecated(message = "Renamed to `openSubscription`", |
| 54 | replaceWith = ReplaceWith("openSubscription()")) |
Roman Elizarov | f5f0983 | 2018-05-16 15:10:28 +0300 | [diff] [blame] | 55 | public fun open(): SubscriptionReceiveChannel<E> = openSubscription() as SubscriptionReceiveChannel<E> |
Roman Elizarov | 89f8ff7 | 2018-03-14 13:39:03 +0300 | [diff] [blame] | 56 | |
| 57 | /** |
| 58 | * Cancels reception of remaining elements from this channel. This function closes the channel with |
| 59 | * the specified cause (unless it was already closed), removes all buffered sent elements from it, |
| 60 | * and [cancels][ReceiveChannel.cancel] all open subscriptions. |
| 61 | * This function returns `true` if the channel was not closed previously, or `false` otherwise. |
| 62 | * |
| 63 | * A channel that was cancelled with non-null [cause] is called a _failed_ channel. Attempts to send or |
| 64 | * receive on a failed channel throw the specified [cause] exception. |
| 65 | */ |
| 66 | public fun cancel(cause: Throwable? = null): Boolean |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 67 | } |
| 68 | |
| 69 | /** |
Roman Elizarov | 3638747 | 2017-07-21 18:37:49 +0300 | [diff] [blame] | 70 | * Creates a broadcast channel with the specified buffer capacity. |
| 71 | * |
| 72 | * The resulting channel type depends on the specified [capacity] parameter: |
Roman Elizarov | 89f8ff7 | 2018-03-14 13:39:03 +0300 | [diff] [blame] | 73 | * * when `capacity` positive, but less than [UNLIMITED] -- creates [ArrayBroadcastChannel] |
| 74 | * **Note:** this channel looses all items that are send to it until the first subscriber appears; |
Roman Elizarov | 3638747 | 2017-07-21 18:37:49 +0300 | [diff] [blame] | 75 | * * when `capacity` is [CONFLATED] -- creates [ConflatedBroadcastChannel] that conflates back-to-back sends; |
| 76 | * * otherwise -- throws [IllegalArgumentException]. |
| 77 | */ |
| 78 | public fun <E> BroadcastChannel(capacity: Int): BroadcastChannel<E> = |
| 79 | when (capacity) { |
| 80 | 0 -> throw IllegalArgumentException("Unsupported 0 capacity for BroadcastChannel") |
| 81 | UNLIMITED -> throw IllegalArgumentException("Unsupported UNLIMITED capacity for BroadcastChannel") |
| 82 | CONFLATED -> ConflatedBroadcastChannel() |
| 83 | else -> ArrayBroadcastChannel(capacity) |
| 84 | } |
| 85 | |
| 86 | /** |
Roman Elizarov | 0f66a6d | 2017-06-22 14:57:53 +0300 | [diff] [blame] | 87 | * Return type for [BroadcastChannel.openSubscription] that can be used to [receive] elements from the |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 88 | * open subscription and to [close] it to unsubscribe. |
Roman Elizarov | b555d91 | 2017-08-17 21:01:33 +0300 | [diff] [blame] | 89 | * |
| 90 | * Note, that invocation of [cancel] also closes subscription. |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 91 | */ |
Roman Elizarov | f5f0983 | 2018-05-16 15:10:28 +0300 | [diff] [blame] | 92 | @Deprecated("Deprecated in favour of `ReceiveChannel`", replaceWith = ReplaceWith("ReceiveChannel")) |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 93 | public interface SubscriptionReceiveChannel<out T> : ReceiveChannel<T>, Closeable { |
| 94 | /** |
Roman Elizarov | b555d91 | 2017-08-17 21:01:33 +0300 | [diff] [blame] | 95 | * Closes this subscription. This is a synonym for [cancel]. |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 96 | */ |
Roman Elizarov | f5f0983 | 2018-05-16 15:10:28 +0300 | [diff] [blame] | 97 | @Deprecated("Use `cancel`", replaceWith = ReplaceWith("cancel()")) |
Roman Elizarov | b555d91 | 2017-08-17 21:01:33 +0300 | [diff] [blame] | 98 | public override fun close() { cancel() } |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 99 | } |
Vsevolod Tolstopyatov | 313978c | 2018-06-01 15:30:34 +0300 | [diff] [blame] | 100 | |
| 101 | /** @suppress **Deprecated**: Left here for migration from SubscriptionReceiveChannel */ |
Roman Elizarov | c038d63 | 2018-06-15 10:42:49 +0300 | [diff] [blame] | 102 | @Deprecated( |
| 103 | level = DeprecationLevel.WARNING, |
| 104 | message = "Use `ReceiveChannel<*>.consume` instead", |
| 105 | replaceWith = ReplaceWith("consume { let(block) }") |
| 106 | ) |
| 107 | public inline fun <E, R> ReceiveChannel<E>.use(block: (ReceiveChannel<E>) -> R): R { |
Vsevolod Tolstopyatov | 313978c | 2018-06-01 15:30:34 +0300 | [diff] [blame] | 108 | var exception: Throwable? = null |
| 109 | try { |
Roman Elizarov | c038d63 | 2018-06-15 10:42:49 +0300 | [diff] [blame] | 110 | return block(this) |
Vsevolod Tolstopyatov | 313978c | 2018-06-01 15:30:34 +0300 | [diff] [blame] | 111 | } catch (t: Throwable) { |
| 112 | exception = t |
| 113 | throw t |
Roman Elizarov | c038d63 | 2018-06-15 10:42:49 +0300 | [diff] [blame] | 114 | } finally { |
Vsevolod Tolstopyatov | 313978c | 2018-06-01 15:30:34 +0300 | [diff] [blame] | 115 | this.cancel(exception) |
| 116 | } |
| 117 | } |