kotlinx.coroutines.channels

Interface ReceiveChannel<E>

All Known Subinterfaces:

ActorScope<E>, Channel<E>

public ReceiveChannel<E>

Receiver's interface to interface Channel.

See Also:

interface Channel

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ReceiveChannel.DefaultImpls Receiver's interface to interface Channel.

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancels reception of remaining elements from this channel. This function closes the channel and removes all buffered sent elements from it.
SelectClause1<E>	getOnReceive() Clause for select expression of ReceiveChannel.receive suspending function that selects with the element that is received from the channel. The select invocation fails with exception if the channel ReceiveChannel.isClosedForReceive (see SendChannel.close for details).
SelectClause1<E>	getOnReceiveOrNull() Clause for select expression of ReceiveChannel.receiveOrNull suspending function that selects with the element that is received from the channel or selects with null if if the channel ReceiveChannel.isClosedForReceive without cause. The select invocation fails with the original SendChannel.close cause exception if the channel has failed.
boolean	isClosedForReceive() Returns true if this channel was closed by invocation of SendChannel.close on the interface SendChannel side and all previously sent items were already received, so that the ReceiveChannel.receive attempt throws exception ClosedReceiveChannelException. If the channel was closed because of the exception, it is considered closed, too, but it is called a failed channel. All suspending attempts to receive an element from a failed channel throw the original SendChannel.close cause exception.
boolean	isEmpty() Returns true if the channel is empty (contains no elements) and the ReceiveChannel.receive attempt will suspend. This function returns false for ReceiveChannel.isClosedForReceive channel.
ChannelIterator<E>	iterator() Returns new iterator to receive elements from this channels using for loop. Iteration completes normally when the channel is ReceiveChannel.isClosedForReceive without cause and throws the original SendChannel.close cause exception if the channel has failed.
E	poll() Retrieves and removes the element from this channel, or returns null if this channel isEmpty or is ReceiveChannel.isClosedForReceive without cause. It throws the original SendChannel.close cause exception if the channel has failed.
java.lang.Object	receive(kotlin.coroutines.experimental.Continuation<? super E> p) Retrieves and removes the element from this channel suspending the caller while this channel isEmpty or throws exception ClosedReceiveChannelException if the channel ReceiveChannel.isClosedForReceive. If the channel was closed because of the exception, it is called a failed channel and this function throws the original SendChannel.close cause exception.
java.lang.Object	receiveOrNull(kotlin.coroutines.experimental.Continuation<? super E> p) Retrieves and removes the element from this channel suspending the caller while this channel isEmpty or returns null if the channel is ReceiveChannel.isClosedForReceive without cause or throws the original SendChannel.close cause exception if the channel has failed.

Method Detail

isClosedForReceive

boolean isClosedForReceive()

Returns true if this channel was closed by invocation of SendChannel.close on the interface SendChannel side and all previously sent items were already received, so that the ReceiveChannel.receive attempt throws exception ClosedReceiveChannelException. If the channel was closed because of the exception, it is considered closed, too, but it is called a failed channel. All suspending attempts to receive an element from a failed channel throw the original SendChannel.close cause exception.

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

See Also:

SendChannel.close, interface SendChannel, ReceiveChannel.receive, exception ClosedReceiveChannelException, SendChannel.close

isEmpty

boolean isEmpty()

Returns true if the channel is empty (contains no elements) and the ReceiveChannel.receive attempt will suspend. This function returns false for ReceiveChannel.isClosedForReceive channel.

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

See Also:

ReceiveChannel.receive, ReceiveChannel.isClosedForReceive

receive

java.lang.Object receive(kotlin.coroutines.experimental.Continuation<? super E> p)

Retrieves and removes the element from this channel suspending the caller while this channel isEmpty or throws exception ClosedReceiveChannelException if the channel ReceiveChannel.isClosedForReceive. If the channel was closed because of the exception, it is called a failed channel and this function throws the original SendChannel.close cause exception.

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 receive is atomic -- when this function throws CancellationException it means that the element was not retrieved from 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 receive 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 ReceiveChannel.getOnReceive clause. Use ReceiveChannel.poll to try receiving from this channel without waiting.

See Also:

isEmpty, exception ClosedReceiveChannelException, ReceiveChannel.isClosedForReceive, SendChannel.close, interface Job, YieldKt.yield, CoroutineScopeKt.isActive, ReceiveChannel.getOnReceive, ReceiveChannel.poll

getOnReceive

SelectClause1<E> getOnReceive()

Clause for select expression of ReceiveChannel.receive suspending function that selects with the element that is received from the channel. The select invocation fails with exception if the channel ReceiveChannel.isClosedForReceive (see SendChannel.close for details).

See Also:

ReceiveChannel.receive, ReceiveChannel.isClosedForReceive, SendChannel.close

receiveOrNull

java.lang.Object receiveOrNull(kotlin.coroutines.experimental.Continuation<? super E> p)

Retrieves and removes the element from this channel suspending the caller while this channel isEmpty or returns null if the channel is ReceiveChannel.isClosedForReceive without cause or throws the original SendChannel.close cause exception if the channel has failed.

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 receive is atomic -- when this function throws CancellationException it means that the element was not retrieved from 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 receive 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 ReceiveChannel.getOnReceiveOrNull clause. Use ReceiveChannel.poll to try receiving from this channel without waiting.

Note: This is an obsolete api. This function will be replaced with receiveOrClosed: ReceiveResult and extension suspend fun ReceiveChannel.receiveOrNull(): E? It is obsolete because it does not distinguish closed channel and null elements.

See Also:

isEmpty, ReceiveChannel.isClosedForReceive, SendChannel.close, interface Job, YieldKt.yield, CoroutineScopeKt.isActive, ReceiveChannel.getOnReceiveOrNull, ReceiveChannel.poll

getOnReceiveOrNull

SelectClause1<E> getOnReceiveOrNull()

Clause for select expression of ReceiveChannel.receiveOrNull suspending function that selects with the element that is received from the channel or selects with null if if the channel ReceiveChannel.isClosedForReceive without cause. The select invocation fails with the original SendChannel.close cause exception if the channel has failed.

Note: This is an experimental api. This function may be replaced with a better one in the future.

See Also:

ReceiveChannel.receiveOrNull, ReceiveChannel.isClosedForReceive, SendChannel.close

poll

E poll()

Retrieves and removes the element from this channel, or returns null if this channel isEmpty or is ReceiveChannel.isClosedForReceive without cause. It throws the original SendChannel.close cause exception if the channel has failed.

See Also:

isEmpty, ReceiveChannel.isClosedForReceive, SendChannel.close

iterator

ChannelIterator<E> iterator()

Returns new iterator to receive elements from this channels using for loop. Iteration completes normally when the channel is ReceiveChannel.isClosedForReceive without cause and throws the original SendChannel.close cause exception if the channel has failed.

See Also:

ReceiveChannel.isClosedForReceive, SendChannel.close

cancel

void cancel()

Cancels reception of remaining elements from this channel. This function closes the channel and removes all buffered sent elements from it.

Immediately after invocation of this function ReceiveChannel.isClosedForReceive and SendChannel.isClosedForSend on the side of interface SendChannel start returning true, so all attempts to send to this channel afterwards will throw exception ClosedSendChannelException, while attempts to receive will throw exception ClosedReceiveChannelException.

See Also:

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