ConflatedBroadcastChannel

@ExperimentalCoroutinesApi class ConflatedBroadcastChannel<E> : 
    BroadcastChannel<E>
(source)

Broadcasts the most recently sent element (aka value) to all openSubscription subscribers.

Back-to-send sent elements are conflated – only the the most recently sent value is received, while previously sent elements are lost. Every subscriber immediately receives the most recently sent element. Sender to this broadcast channel never suspends and offer always returns true.

A secondary constructor can be used to create an instance of this class that already holds a value. This channel is also created by BroadcastChannel(Channel.CONFLATED) factory function invocation.

This implementation is fully lock-free. In this implementation opening and closing subscription takes O(N) time, where N is the number of subscribers.

Note: This API is experimental. It may be changed in the future updates.

Constructors

<init>

ConflatedBroadcastChannel(value: E)

Creates an instance of this class that already holds a value.

ConflatedBroadcastChannel()

Broadcasts the most recently sent element (aka value) to all openSubscription subscribers.

Properties

isClosedForSend

val isClosedForSend: Boolean

Returns true if this channel was closed by invocation of close and thus the send and offer attempts throws exception.

isFull

val isFull: Boolean

Returns true if the channel is full (out of capacity) and the send attempt will suspend. This function returns false for isClosedForSend channel.

onSend

val onSend: SelectClause2<E, SendChannel<E>>

Clause for select expression of send suspending function that selects when the element that is specified as parameter is sent to the channel. When the clause is selected the reference to this channel is passed into the corresponding block.

value

val value: E

The most recently sent element to this channel.

valueOrNull

val valueOrNull: E?

The most recently sent element to this channel or null when this class is constructed without initial value and no value was sent yet or if it was closed.

Functions

cancel

fun cancel(cause: Throwable?): Boolean

Closes this broadcast channel. Same as close.

close

fun close(cause: Throwable?): Boolean

Closes this channel. This is an idempotent operation – repeated invocations of this function have no effect and return false. Conceptually, its sends a special “close token” over this channel.

invokeOnClose

fun invokeOnClose(handler: Handler): Unit

Registers handler which is synchronously invoked once the channel is closed or receiving side of this channel is cancelled. Only one handler can be attached to the channel during channel’s lifetime. Handler is invoked when isClosedForSend starts to return true. If channel is already closed, handler is invoked immediately.

offer

fun offer(element: E): Boolean

Sends the value to all subscribed receives and stores this value as the most recent state for future subscribers. This implementation always returns true. It throws exception if the channel isClosedForSend (see close for details).

openSubscription

fun openSubscription(): ReceiveChannel<E>

Subscribes to this BroadcastChannel and returns a channel to receive elements from it. The resulting channel shall be cancelled to unsubscribe from this broadcast channel.

send

suspend fun send(element: E): Unit

Sends the value to all subscribed receives and stores this value as the most recent state for future subscribers. This implementation never suspends. It throws exception if the channel isClosedForSend (see close for details).

Extension Functions

consume

fun <E, R> BroadcastChannel<E>.consume(
    block: ReceiveChannel<E>.() -> R
): R

Opens subscription to this BroadcastChannel and makes sure that the given block consumes all elements from it by always invoking cancel after the execution of the block.

consumeEach

suspend fun <E> BroadcastChannel<E>.consumeEach(
    action: (E) -> Unit
): Unit

Subscribes to this BroadcastChannel and performs the specified action for each received element.

sendBlocking

fun <E> SendChannel<E>.sendBlocking(element: E): Unit

Adds element into to this channel, blocking the caller while this channel Channel.isFull, or throws exception if the channel Channel.isClosedForSend (see Channel.close for details).