| /* |
| * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. |
| */ |
| |
| @file:Suppress("FunctionName") |
| |
| package kotlinx.coroutines.channels |
| |
| import kotlinx.coroutines.* |
| import kotlinx.coroutines.channels.Channel.Factory.BUFFERED |
| import kotlinx.coroutines.channels.Channel.Factory.CHANNEL_DEFAULT_CAPACITY |
| import kotlinx.coroutines.channels.Channel.Factory.CONFLATED |
| import kotlinx.coroutines.channels.Channel.Factory.UNLIMITED |
| |
| /** |
| * Broadcast channel is a non-blocking primitive for communication between the sender and multiple receivers |
| * that subscribe for the elements using [openSubscription] function and unsubscribe using [ReceiveChannel.cancel] |
| * function. |
| * |
| * See `BroadcastChannel()` factory function for the description of available |
| * broadcast channel implementations. |
| * |
| * **Note: This API is obsolete.** It will be deprecated and replaced by [SharedFlow][kotlinx.coroutines.flow.SharedFlow] |
| * when it becomes stable. |
| */ |
| @ExperimentalCoroutinesApi // not @ObsoleteCoroutinesApi to reduce burden for people who are still using it |
| public interface BroadcastChannel<E> : SendChannel<E> { |
| /** |
| * Subscribes to this [BroadcastChannel] and returns a channel to receive elements from it. |
| * The resulting channel shall be [cancelled][ReceiveChannel.cancel] to unsubscribe from this |
| * broadcast channel. |
| */ |
| public fun openSubscription(): ReceiveChannel<E> |
| |
| /** |
| * Cancels reception of remaining elements from this channel with an optional cause. |
| * This function closes the channel with |
| * the specified cause (unless it was already closed), removes all buffered sent elements from it, |
| * and [cancels][ReceiveChannel.cancel] all open subscriptions. |
| * A cause can be used to specify an error message or to provide other details on |
| * a cancellation reason for debugging purposes. |
| */ |
| public fun cancel(cause: CancellationException? = null) |
| |
| /** |
| * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel]. |
| */ |
| @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only") |
| public fun cancel(cause: Throwable? = null): Boolean |
| } |
| |
| /** |
| * Creates a broadcast channel with the specified buffer capacity. |
| * |
| * The resulting channel type depends on the specified [capacity] parameter: |
| * |
| * * when `capacity` positive, but less than [UNLIMITED] -- creates `ArrayBroadcastChannel` with a buffer of given capacity. |
| * **Note:** this channel looses all items that are send to it until the first subscriber appears; |
| * * when `capacity` is [CONFLATED] -- creates [ConflatedBroadcastChannel] that conflates back-to-back sends; |
| * * when `capacity` is [BUFFERED] -- creates `ArrayBroadcastChannel` with a default capacity. |
| * * otherwise -- throws [IllegalArgumentException]. |
| * |
| * **Note: This is an experimental api.** It may be changed in the future updates. |
| */ |
| @ExperimentalCoroutinesApi |
| public fun <E> BroadcastChannel(capacity: Int): BroadcastChannel<E> = |
| when (capacity) { |
| 0 -> throw IllegalArgumentException("Unsupported 0 capacity for BroadcastChannel") |
| UNLIMITED -> throw IllegalArgumentException("Unsupported UNLIMITED capacity for BroadcastChannel") |
| CONFLATED -> ConflatedBroadcastChannel() |
| BUFFERED -> ArrayBroadcastChannel(CHANNEL_DEFAULT_CAPACITY) |
| else -> ArrayBroadcastChannel(capacity) |
| } |