broadcast

fun <E> ReceiveChannel<E>.broadcast(
    capacity: Int = 1,
    start: CoroutineStart = CoroutineStart.LAZY
): BroadcastChannel<E>
(source)

Broadcasts all elements of the channel. This function consumes all elements of the original ReceiveChannel.

The kind of the resulting channel depends on the specified capacity parameter: when capacity is positive (1 by default), but less than UNLIMITED – uses ArrayBroadcastChannel with a buffer of given capacity, when capacity is CONFLATED – uses ConflatedBroadcastChannel that conflates back-to-back sends; Note that resulting channel behaves like ConflatedBroadcastChannel but is not an instance of ConflatedBroadcastChannel. otherwise – throws IllegalArgumentException.

Cancelling broadcast

To stop broadcasting from the underlying channel call cancel on the result.

Do not use close on the resulting channel. It causes eventual failure of the broadcast coroutine and cancellation of the underlying channel, too, but it is not as prompt.

Future replacement

This function has an inappropriate result type of BroadcastChannel which provides send and close operations that interfere with the broadcasting coroutine in hard-to-specify ways. It will be replaced with sharing operators on Flow in the future.

Parameters

start - coroutine start option. The default value is CoroutineStart.LAZY.

fun <E> CoroutineScope.broadcast(
    context: CoroutineContext = EmptyCoroutineContext,
    capacity: Int = 1,
    start: CoroutineStart = CoroutineStart.LAZY,
    onCompletion: CompletionHandler? = null,
    block: suspend ProducerScope<E>.() -> Unit
): BroadcastChannel<E>
(source)

Launches new coroutine to produce a stream of values by sending them to a broadcast channel and returns a reference to the coroutine as a BroadcastChannel. The resulting object can be used to subscribe to elements produced by this coroutine.

The scope of the coroutine contains ProducerScope interface, which implements both CoroutineScope and SendChannel, so that coroutine can invoke send directly. The channel is closed when the coroutine completes.

Coroutine context is inherited from a CoroutineScope, additional context elements can be specified with context argument. If the context does not have any dispatcher nor any other ContinuationInterceptor, then Dispatchers.Default is used. The parent job is inherited from a CoroutineScope as well, but it can also be overridden with corresponding context element.

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.

The kind of the resulting channel depends on the specified capacity parameter:

Note: By default, the coroutine does not start until the first subscriber appears via BroadcastChannel.openSubscription as start parameter has a value of CoroutineStart.LAZY by default. This ensures that the first subscriber does not miss any sent elements. However, later subscribers may miss elements.

See newCoroutineContext for a description of debugging facilities that are available for newly created coroutine.

Cancelling broadcast

To stop broadcasting from the underlying channel call cancel on the result.

Do not use close on the resulting channel. It causes failure of the send operation in broadcast coroutine and would not cancel it if the coroutine is doing something else.

Future replacement

This function has an inappropriate result type of BroadcastChannel which provides send and close operations that interfere with the broadcasting coroutine in hard-to-specify ways. It will be replaced with sharing operators on Flow in the future.

Parameters

context - additional to CoroutineScope.coroutineContext context of the coroutine.

capacity - capacity of the channel’s buffer (1 by default).

start - coroutine start option. The default value is CoroutineStart.LAZY.

onCompletion - optional completion handler for the producer coroutine (see Job.invokeOnCompletion).

block - the coroutine code.