kotlinx-coroutines-core/kotlinx.coroutines.channels/ConflatedBroadcastChannel

ConflatedBroadcastChannel

class ConflatedBroadcastChannel<E> : BroadcastChannel<E>

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 trySend always succeeds.

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 obsolete since 1.5.0. It will be deprecated with warning in 1.6.0 and with error in 1.7.0. It is replaced with StateFlow.

Constructors

ConflatedBroadcastChannel

fun <E> ConflatedBroadcastChannel(value: E)

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

ConflatedBroadcastChannel

fun ConflatedBroadcastChannel()

Functions

cancel

open override fun cancel(cause: CancellationException?)

Cancels this conflated broadcast channel with an optional cause, same as close. This function closes the channel with the specified cause (unless it was already closed), and cancels 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.

open override fun close(cause: Throwable?): Boolean

Closes this channel. This is an idempotent operation — subsequent invocations of this function have no effect and return false. Conceptually, it sends a special "close token" over this channel.

invokeOnClose

open override fun invokeOnClose(handler: Handler)

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

openSubscription

open override 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

open suspend override fun send(element: E)

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).

trySend

open override fun trySend(element: E): ChannelResult<Unit>

Sends the value to all subscribed receives and stores this value as the most recent state for future subscribers. This implementation always returns either successful result or closed with an exception.

Properties

isClosedForSend

open override val isClosedForSend: Boolean

Returns true if this channel was closed by an invocation of close. This means that calling send will result in an exception.

onSend

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

Clause for the select expression of the send suspending function that selects when the element that is specified as the 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.

Sources

common source