public class ConflatedBroadcastChannel<E> implements BroadcastChannel<E>
Broadcasts the most recently sent element (aka ConflatedBroadcastChannel.getValue) to all ConflatedBroadcastChannel.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 ConflatedBroadcastChannel.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
ConflatedBroadcastChannel.openSubscription and ReceiveChannel.cancel 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.
| Modifier and Type | Field and Description |
|---|---|
static kotlinx.coroutines.channels.ConflatedBroadcastChannel.Companion |
Companion
Deprecated.
|
| Constructor and Description |
|---|
ConflatedBroadcastChannel()
Broadcasts the most recently sent element (aka
ConflatedBroadcastChannel.getValue) to all ConflatedBroadcastChannel.openSubscription subscribers. |
ConflatedBroadcastChannel(E value)
Creates an instance of this class that already holds a value.
|
| Modifier and Type | Method and Description |
|---|---|
boolean |
cancel(java.lang.Throwable cause)
Closes this broadcast channel. Same as
ConflatedBroadcastChannel.close. |
boolean |
close(java.lang.Throwable cause)
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. |
SelectClause2<E,kotlinx.coroutines.channels.SendChannel> |
getOnSend()
Clause for select expression of
ConflatedBroadcastChannel.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. |
E |
getValue()
The most recently sent element to this channel.
|
E |
getValueOrNull()
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 ConflatedBroadcastChannel.close. |
void |
invokeOnClose(kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler)
Registers handler which is synchronously invoked once the channel is
ConflatedBroadcastChannel.close
or receiving side of this channel is ReceiveChannel.cancel.
Only one handler can be attached to the channel during channel's lifetime.
Handler is invoked when ConflatedBroadcastChannel.isClosedForSend starts to return true.
If channel is already closed, handler is invoked immediately. |
boolean |
isClosedForSend()
Returns
true if this channel was closed by invocation of ConflatedBroadcastChannel.close and thus
the ConflatedBroadcastChannel.send and ConflatedBroadcastChannel.offer attempts throws exception. |
boolean |
isFull()
Returns
true if the channel is full (out of capacity) and the ConflatedBroadcastChannel.send attempt will suspend.
This function returns false for ConflatedBroadcastChannel.isClosedForSend channel. |
boolean |
offer(E element)
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 ConflatedBroadcastChannel.isClosedForSend (see ConflatedBroadcastChannel.close for details). |
ReceiveChannel<E> |
openSubscription()
Subscribes to this
interface BroadcastChannel and returns a channel to receive elements from it.
The resulting channel shall be ReceiveChannel.cancel to unsubscribe from this
broadcast channel. |
java.lang.Object |
send(E element,
kotlin.coroutines.experimental.Continuation<? super kotlin.Unit> p)
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
ConflatedBroadcastChannel.isClosedForSend (see ConflatedBroadcastChannel.close for details). |
cancel, openSubscriptionclose, getOnSend, invokeOnClose, isClosedForSend, isFull, offer, sendpublic static kotlinx.coroutines.channels.ConflatedBroadcastChannel.Companion Companion
public ConflatedBroadcastChannel()
Broadcasts the most recently sent element (aka ConflatedBroadcastChannel.getValue) to all ConflatedBroadcastChannel.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 ConflatedBroadcastChannel.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
ConflatedBroadcastChannel.openSubscription and ReceiveChannel.cancel 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.
public ConflatedBroadcastChannel(E value)
Creates an instance of this class that already holds a value.
It is as a shortcut to creating an instance with a default constructor and
immediately sending an element: ConflatedBroadcastChannel().apply { offer(value) }.
public E getValue()
The most recently sent element to this channel.
Access to this property throws IllegalStateException when this class is constructed without
initial value and no value was sent yet or if it was ConflatedBroadcastChannel.close without a cause.
It throws the original SendChannel.close cause exception if the channel has failed.
public E getValueOrNull()
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 ConflatedBroadcastChannel.close.
ConflatedBroadcastChannel.closepublic boolean isClosedForSend()
Returns true if this channel was closed by invocation of ConflatedBroadcastChannel.close and thus
the ConflatedBroadcastChannel.send and ConflatedBroadcastChannel.offer attempts throws exception.
Note: This is an experimental api. This property may change its semantics and/or name in the future.
public boolean isFull()
Returns true if the channel is full (out of capacity) and the ConflatedBroadcastChannel.send attempt will suspend.
This function returns false for ConflatedBroadcastChannel.isClosedForSend channel.
Note: This is an experimental api. This property may change its semantics and/or name in the future.
public ReceiveChannel<E> openSubscription()
Subscribes to this interface BroadcastChannel and returns a channel to receive elements from it.
The resulting channel shall be ReceiveChannel.cancel to unsubscribe from this
broadcast channel.
interface BroadcastChannel,
ReceiveChannel.cancelpublic boolean close(java.lang.Throwable cause)
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.
Immediately after invocation of this function
ConflatedBroadcastChannel.isClosedForSend starts returning true. However, ReceiveChannel.isClosedForReceive
on the side of interface ReceiveChannel starts returning true only after all previously sent elements
are received.
A channel that was closed without a cause throws exception ClosedSendChannelException on attempts to send or receive.
A channel that was closed with non-null cause is called a failed channel. Attempts to send or
receive on a failed channel throw the specified cause exception.
public void invokeOnClose(kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler)
Registers handler which is synchronously invoked once the channel is ConflatedBroadcastChannel.close
or receiving side of this channel is ReceiveChannel.cancel.
Only one handler can be attached to the channel during channel's lifetime.
Handler is invoked when ConflatedBroadcastChannel.isClosedForSend starts to return true.
If channel is already closed, handler is invoked immediately.
The meaning of cause that is passed to the handler:
null if channel was closed or cancelled without corresponding argument
close or cancel cause otherwise.
Example of usage (exception handling is omitted):
val events = Channel(UNLIMITED)
callbackBasedApi.registerCallback { event ->
events.offer(event)
}
val uiUpdater = launch(UI, parent = UILifecycle) {
events.consume {}
events.cancel()
}
events.invokeOnClose { callbackBasedApi.stop() }
Note: This is an experimental api. This function may change its semantics, parameters or return type in the future.
ConflatedBroadcastChannel.invokeOnClose.
Implementation note: currently, ConflatedBroadcastChannel.invokeOnClose is unsupported only by Rx-like integrationsConflatedBroadcastChannel.close,
ReceiveChannel.cancel,
ConflatedBroadcastChannel.isClosedForSendpublic boolean cancel(java.lang.Throwable cause)
Closes this broadcast channel. Same as ConflatedBroadcastChannel.close.
ConflatedBroadcastChannel.closepublic java.lang.Object send(E element,
kotlin.coroutines.experimental.Continuation<? super kotlin.Unit> p)
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 ConflatedBroadcastChannel.isClosedForSend (see ConflatedBroadcastChannel.close for details).
public boolean offer(E element)
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 ConflatedBroadcastChannel.isClosedForSend (see ConflatedBroadcastChannel.close for details).
public SelectClause2<E,kotlinx.coroutines.channels.SendChannel> getOnSend()
Clause for select expression of ConflatedBroadcastChannel.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.
The select invocation fails with exception if the channel ConflatedBroadcastChannel.isClosedForSend (see ConflatedBroadcastChannel.close for details).