kotlinx.coroutines.channels

Interface SendChannel<E>

All Known Subinterfaces:

BroadcastChannel<E>, Channel<E>, ProducerScope<E>

All Known Implementing Classes:

ConflatedBroadcastChannel

public SendChannel<E>

Sender's interface to interface Channel.

See Also:

interface Channel

Method Summary

Modifier and Type	Method and Description
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 SendChannel.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.
void	invokeOnClose(kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler) Registers handler which is synchronously invoked once the channel is SendChannel.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 SendChannel.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 SendChannel.close and thus the SendChannel.send and SendChannel.offer attempts throws exception.
boolean	isFull() Returns true if the channel is full (out of capacity) and the SendChannel.send attempt will suspend. This function returns false for SendChannel.isClosedForSend channel.
boolean	offer(E element) Adds element into this queue if it is possible to do so immediately without violating capacity restrictions and returns true. Otherwise, it returns false immediately or throws exception if the channel SendChannel.isClosedForSend (see SendChannel.close for details).
java.lang.Object	send(E element, kotlin.coroutines.experimental.Continuation<? super kotlin.Unit> p) Adds element into to this channel, suspending the caller while this channel SendChannel.isFull, or throws exception if the channel SendChannel.isClosedForSend (see SendChannel.close for details).

Method Detail

isClosedForSend

boolean isClosedForSend()

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

Note: This is an experimental api. This property may change its semantics and/or name in the future.

See Also:

SendChannel.close, SendChannel.send, SendChannel.offer

isFull

boolean isFull()

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

Note: This is an experimental api. This property may change its semantics and/or name in the future.

See Also:

SendChannel.send, SendChannel.isClosedForSend

send

java.lang.Object send(E element,
                      kotlin.coroutines.experimental.Continuation<? super kotlin.Unit> p)

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

Note, that closing a channel after this function had suspended does not cause this suspended send invocation to abort, because closing a channel is conceptually like sending a special "close token" over this channel. All elements that are sent over the channel are delivered in first-in first-out order. The element that is being sent will get delivered to receivers before a close token.

This suspending function is cancellable. If the interface Job of the current coroutine is cancelled or completed while this function is suspended, this function immediately resumes with CancellationException.

Cancellation of suspended send is atomic -- when this function throws CancellationException it means that the element was not sent to this channel. As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may continue to execute even after it was cancelled from the same thread in the case when this send operation was already resumed and the continuation was posted for execution to the thread's queue.

Note, that this function does not check for cancellation when it is not suspended. Use YieldKt.yield or CoroutineScopeKt.isActive to periodically check for cancellation in tight loops if needed.

This function can be used in select invocation with SendChannel.getOnSend clause. Use SendChannel.offer to try sending to this channel without waiting.

See Also:

SendChannel.isFull, SendChannel.isClosedForSend, SendChannel.close, interface Job, YieldKt.yield, CoroutineScopeKt.isActive, SendChannel.getOnSend, SendChannel.offer

getOnSend

SelectClause2<E,kotlinx.coroutines.channels.SendChannel> getOnSend()

Clause for select expression of SendChannel.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 SendChannel.isClosedForSend (see SendChannel.close for details).

See Also:

SendChannel.send, SendChannel.isClosedForSend, SendChannel.close

offer

boolean offer(E element)

Adds element into this queue if it is possible to do so immediately without violating capacity restrictions and returns true. Otherwise, it returns false immediately or throws exception if the channel SendChannel.isClosedForSend (see SendChannel.close for details).

See Also:

SendChannel.isClosedForSend, SendChannel.close

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.

Immediately after invocation of this function SendChannel.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.

See Also:

SendChannel.isClosedForSend, ReceiveChannel.isClosedForReceive, interface ReceiveChannel, exception ClosedSendChannelException

invokeOnClose

void invokeOnClose(kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler)

Registers handler which is synchronously invoked once the channel is SendChannel.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 SendChannel.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.

Throws:

- if underlying channel doesn't support SendChannel.invokeOnClose. Implementation note: currently, SendChannel.invokeOnClose is unsupported only by Rx-like integrations

- if another handler was already registered

See Also:

SendChannel.close, ReceiveChannel.cancel, SendChannel.isClosedForSend