core
API
Generated with
core/ox/ox.channels/Channel

Channel

ox.channels.Channel
See theChannel companion object
class Channel[T] extends Source[T], Sink[T]

Channel is a thread-safe data structure which exposes three basic operations:

  • send-ing a value to the channel. Values can't be null.
  • receive-ing a value from the channel
  • closing the channel using done or error

There are three channel flavors:

  • rendezvous channels, where senders and receivers must meet to exchange values
  • buffered channels, where a given number of sent values might be buffered, before subsequent sends block
  • unlimited channels, where an unlimited number of values might be buffered, hence send never blocks

Channels can be created using the channel's companion object. A rendezvous channel is created using Channel.rendezvous. A buffered channel can be created either with a given capacity - by providing a positive integer to the Channel.buffered method - or with the default capacity (BufferCapacity.default) using Channel.bufferedDefault . A rendezvous channel behaves like a buffered channel with buffer size 0. An unlimited channel can be created using Channel.unlimited.

In a rendezvous channel, senders and receivers block, until a matching party arrives (unless one is already waiting). Similarly, buffered channels block if the buffer is full (in case of senders), or in case of receivers, if the buffer is empty and there are no waiting senders.

All blocking operations behave properly upon interruption.

Channels might be closed, either because no more values will be produced by the source (using done), or because there was an error while producing or processing the received values (using error).

After closing, no more values can be sent to the channel. If the channel is "done", any pending sends will be completed normally. If the channel is in an "error" state, pending sends will be interrupted and will return with the reason for the closure.

In case the channel is closed, a ChannelClosedException is thrown. Alternatively, you can use the orClosed method variants (e.g. sendOrClosed, receiveOrClosed), which don't throw exceptions, but return a union type which includes one of ChannelClosed values. Such a union type can be further converted to an exception, Either or Try using one of the extension methods in ChannelClosedUnion.

Type parameters

T

The type of the values processed by the channel.

Attributes

Companion
object
Graph
Supertypes
trait Sink[T]
trait Source[T]
trait SourceDrainOps[T]
trait SourceOps[T]
class Object
trait Matchable
class Any
Show all

Members list

Type members

Inherited classlikes

case class Receive extends SelectClause[T]

The clause passed to select, created using receiveClause or receiveOrDoneClause.

The clause passed to select, created using receiveClause or receiveOrDoneClause.

Attributes

Inherited from:
Source
Supertypes
trait Serializable
trait Product
trait Equals
trait SelectClause[T]
class Object
trait Matchable
class Any
Show all
case class Received extends SelectResult[T]

Holds the result of a receiveClause that was selected during a call to select.

Holds the result of a receiveClause that was selected during a call to select.

Attributes

Inherited from:
Source
Supertypes
trait Serializable
trait Product
trait Equals
trait SelectResult[T]
class Object
trait Matchable
class Any
Show all
case class Send extends SelectClause[Unit]

The clause passed to select, created using sendClause.

The clause passed to select, created using sendClause.

Attributes

Inherited from:
Sink
Supertypes
trait Serializable
trait Product
trait Equals
trait SelectClause[Unit]
class Object
trait Matchable
class Any
Show all
case class Sent extends SelectResult[Unit]

Holds the result of a sendClause that was selected during a call to select.

Holds the result of a sendClause that was selected during a call to select.

Attributes

Inherited from:
Sink
Supertypes
trait Serializable
trait Product
trait Equals
trait SelectResult[Unit]
class Object
trait Matchable
class Any
Show all

Value members

Concrete methods

override def toString: String

Returns a string representation of the object.

Returns a string representation of the object.

The default representation is platform dependent.

Attributes

Returns

a string representation of the object.

Definition Classes
Any

Inherited methods

def collect[U](f: PartialFunction[T, U])(using Ox, BufferCapacity): Source[U]

Applies the given mapping function f to each value received from this source, for which the function is defined, and sends the results to the returned channel. If f is not defined at a value, the value will be skipped.

Applies the given mapping function f to each value received from this source, for which the function is defined, and sends the results to the returned channel. If f is not defined at a value, the value will be skipped.

Errors from this channel are propagated to the returned channel. Any exceptions that occur when invoking f are propagated as errors to the returned channel as well.

Must be run within a scope, as a child fork is created, which receives from this source and sends the mapped values to the resulting one.

For a lazily-evaluated version, see collectAsView.

Value parameters

f

The mapping function.

Attributes

Returns

A source, onto which results of the mapping function will be sent.

Inherited from:
SourceOps
def collectAsView[U](f: PartialFunction[T, U]): Source[U]

Creates a view of this source, where the results of receive will be transformed on the consumer's thread using the given function f. If the function is not defined at a value, the value will be skipped. For an eager, asynchronous version, see collect.

Creates a view of this source, where the results of receive will be transformed on the consumer's thread using the given function f. If the function is not defined at a value, the value will be skipped. For an eager, asynchronous version, see collect.

The same logic applies to receive clauses created using this source, which can be used in select.

Value parameters

f

The collecting function. Results should not be null.

Attributes

Returns

A source which is a view of this source, with the collecting function applied.

Inherited from:
SourceOps
def done(): Unit

Close the channel, indicating that no more values will be sent. Doesn't throw exceptions when the channel is closed, but returns a value.

Close the channel, indicating that no more values will be sent. Doesn't throw exceptions when the channel is closed, but returns a value.

Any values that are already buffered will be delivered. Any send operations that are in progress will complete normally, when a receiver arrives. Any pending receive operations will complete with a channel closed result.

Subsequent send operations will throw ChannelClosedException.

For a variant which doesn't throw exceptions when the channel is closed, use doneOrClosed.

Attributes

Throws
ChannelClosedException

If the channel is already closed.

Inherited from:
Sink
def doneOrClosed(): Unit | ChannelClosed

Close the channel, indicating that no more values will be sent. Doesn't throw exceptions when the channel is closed, but returns a value.

Close the channel, indicating that no more values will be sent. Doesn't throw exceptions when the channel is closed, but returns a value.

Any values that are already buffered will be delivered. Any send operations that are in progress will complete normally, when a receiver arrives. Any pending receive operations will complete with a channel closed result.

Subsequent sendOrClosed operations will return ChannelClosed.

For a variant which throws exceptions when the channel is closed, use done.

Attributes

Returns

Either (), or ChannelClosed, when the channel is already closed.

Inherited from:
Sink
def drain(): Unit

Receives all values from the channel. Blocks until the channel is done.

Receives all values from the channel. Blocks until the channel is done.

Attributes

Throws
ChannelClosedException.Error

when there is an upstream error.

Inherited from:
SourceDrainOps
def drainOrError(): Unit | Error

The "safe" variant of drain.

The "safe" variant of drain.

Attributes

Inherited from:
SourceDrainOps
def error(reason: Throwable): Unit

Close the channel, indicating an error.

Close the channel, indicating an error.

Any values that are already buffered won't be delivered. Any send or receive operations that are in progress will complete with a channel closed result.

Subsequent send and Source.receive operations will throw ChannelClosedException.

For a variant which doesn't throw exceptions when the channel is closed, use errorOrClosed.

Value parameters

reason

The reason of the error.

Attributes

Throws
ChannelClosedException

If the channel is already closed.

Inherited from:
Sink
def errorOrClosed(reason: Throwable): Unit | ChannelClosed

Close the channel, indicating an error.

Close the channel, indicating an error.

Any values that are already buffered won't be delivered. Any send or receive operations that are in progress will complete with a channel closed result.

Subsequent sendOrClosed and Source.receiveOrClosed operations will return ChannelClosed.

For a variant which throws exceptions when the channel is closed, use error.

Value parameters

reason

The reason of the error.

Attributes

Returns

Either (), or ChannelClosed, when the channel is already closed.

Inherited from:
Sink
def filter(f: T => Boolean)(using Ox, BufferCapacity): Source[T]

Attributes

Inherited from:
SourceOps
def filterAsView(f: T => Boolean): Source[T]

Lazily-evaluated filter: Creates a view of this source, where the results of receive will be filtered on the consumer's thread using the given predicate p. For an eager, asynchronous version, see filter.

Lazily-evaluated filter: Creates a view of this source, where the results of receive will be filtered on the consumer's thread using the given predicate p. For an eager, asynchronous version, see filter.

The same logic applies to receive clauses created using this source, which can be used in select.

Value parameters

f

The predicate to use for filtering.

Attributes

Returns

A source which is a view of this source, with the filtering function applied.

Inherited from:
SourceOps
def foreach(f: T => Unit): Unit

Invokes the given function for each received value. Blocks until the channel is done.

Invokes the given function for each received value. Blocks until the channel is done.

Attributes

Throws
ChannelClosedException.Error

When there is an upstream error.

Inherited from:
SourceDrainOps
def foreachOrError(f: T => Unit): Unit | Error

The "safe" variant of foreach.

The "safe" variant of foreach.

Attributes

Inherited from:
SourceDrainOps
def isClosedForReceive: Boolean

Attributes

Returns

true if no more values can be received from this channel; Source.receive will throw ChannelClosedException. When closed for receive, sending values is also not possible, isClosedForSend will return true.

Inherited from:
Source
def isClosedForReceiveDetail: Option[ChannelClosed]

Attributes

Returns

Some if no more values can be received from this channel; Source.receive will throw ChannelClosedException. When closed for receive, sending values is also not possible, isClosedForSend will return true.

Inherited from:
Source
def isClosedForSend: Boolean

Attributes

Returns

true if no more values can be sent to this channel; Sink.sendOrClosed will return ChannelClosed. When closed for send, receiving using Source.receive might still be possible, if the channel is done, and not in an error. This can be verified using isClosedForReceive.

Inherited from:
Sink
def isClosedForSendDetail: Option[ChannelClosed]

Attributes

Returns

Some if no more values can be sent to this channel; Sink.sendOrClosed will return ChannelClosed. When closed for send, receiving using Source.receive might still be possible, if the channel is done, and not in an error. This can be verified using isClosedForReceive.

Inherited from:
Sink
def map[U](f: T => U)(using Ox, BufferCapacity): Source[U]

Applies the given mapping function f to each value received from this source, and sends the results to the returned channel.

Applies the given mapping function f to each value received from this source, and sends the results to the returned channel.

Errors from this channel are propagated to the returned channel. Any exceptions that occur when invoking f are propagated as errors to the returned channel as well.

Must be run within a scope, as a child fork is created, which receives from this source and sends the mapped values to the resulting one.

For a lazily-evaluated version, see mapAsView.

Value parameters

f

The mapping function.

Attributes

Returns

A source, onto which results of the mapping function will be sent.

Inherited from:
SourceOps
def mapAsView[U](f: T => U): Source[U]

Lazily-evaluated map: creates a view of this source, where the results of receive will be transformed on the consumer's thread using the given function f. For an eager, asynchronous version, see map.

Lazily-evaluated map: creates a view of this source, where the results of receive will be transformed on the consumer's thread using the given function f. For an eager, asynchronous version, see map.

The same logic applies to receive clauses created using this source, which can be used in select.

Value parameters

f

The mapping function. Results should not be null.

Attributes

Returns

A source which is a view of this source, with the mapping function applied.

Inherited from:
SourceOps
def pipeTo(sink: Sink[T], propagateDone: Boolean): Unit

Passes each received values from this channel to the given sink. Blocks until the channel is done.

Passes each received values from this channel to the given sink. Blocks until the channel is done.

Errors are always propagated. Successful channel completion is propagated when propagateDone is set to true.

Attributes

Inherited from:
SourceDrainOps
def receive(): T

Receive a value from the channel. For a variant which doesn't throw exceptions when the channel is closed, use receiveOrClosed.

Receive a value from the channel. For a variant which doesn't throw exceptions when the channel is closed, use receiveOrClosed.

Attributes

Returns

Either a value of type T, or ChannelClosed, when the channel is closed.

Throws
ChannelClosedException

If the channel is closed (done or in error).

Inherited from:
Source
def receiveClause: Receive

Create a clause which can be used in select. The clause will receive a value from the current channel.

Create a clause which can be used in select. The clause will receive a value from the current channel.

Attributes

Inherited from:
Source
def receiveOrClosed(): T | ChannelClosed

Receive a value from the channel. For a variant which throws exceptions when the channel is closed, use receive.

Receive a value from the channel. For a variant which throws exceptions when the channel is closed, use receive.

Attributes

Returns

Either a value of type T, or ChannelClosed, when the channel is closed.

Inherited from:
Source
def receiveOrDone(): T | Done.type

Receive a value from the channel.

Receive a value from the channel.

Attributes

Returns

Either a value of type T, or ChannelClosed.Done, when the channel is done.

Throws
ChannelClosedException

If the channel is in error.

See also
Inherited from:
Source
def send(t: T): Unit

Send a value to the channel. For a variant which doesn't throw exceptions when the channel is closed, use sendOrClosed.

Send a value to the channel. For a variant which doesn't throw exceptions when the channel is closed, use sendOrClosed.

Value parameters

t

The value to send. Not null.

Attributes

Throws
ChannelClosedException

If the channel is closed (done or in error).

Inherited from:
Sink
def sendClause(t: T): Send

Create a clause which can be used in select. The clause will send the given value to the current channel, and return () as the clause's result.

Create a clause which can be used in select. The clause will send the given value to the current channel, and return () as the clause's result.

Attributes

Inherited from:
Sink
def sendOrClosed(t: T): Unit | ChannelClosed

Send a value to the channel. For a variant which throws exceptions when the channel is closed, use send.

Send a value to the channel. For a variant which throws exceptions when the channel is closed, use send.

Value parameters

t

The value to send. Not null.

Attributes

Returns

Either (), or ChannelClosed, when the channel is closed.

Inherited from:
Sink
def tap(f: T => Unit)(using Ox, BufferCapacity): Source[T]

Applies the given consumer function f to each value received from this source.

Applies the given consumer function f to each value received from this source.

Errors from this channel are propagated to the returned channel. Any exceptions that occur when invoking f are propagated as errors to the returned channel as well.

Must be run within a scope, as a child fork is created, which receives from this source and sends the mapped values to the resulting one.

Useful for side-effects without result values, like logging and debugging. For a lazily-evaluated version, see tapAsView.

Value parameters

f

The consumer function.

Attributes

Returns

A source, which the values from the input source are passed to.

Inherited from:
SourceOps
def tapAsView(f: T => Unit): Source[T]

Lazily-evaluated tap: creates a view of this source, where the results of receive will be applied to the given function f on the consumer's thread. Useful for side-effects without result values, like logging and debugging. For an eager, asynchronous version, see tap.

Lazily-evaluated tap: creates a view of this source, where the results of receive will be applied to the given function f on the consumer's thread. Useful for side-effects without result values, like logging and debugging. For an eager, asynchronous version, see tap.

The same logic applies to receive clauses created using this source, which can be used in select.

Value parameters

f

The consumer function.

Attributes

Returns

A source which is a view of this source, with the consumer function applied.

Inherited from:
SourceOps
def toList: List[T]

Accumulates all values received from the channel into a list. Blocks until the channel is done.

Accumulates all values received from the channel into a list. Blocks until the channel is done.

Attributes

Throws
ChannelClosedException.Error

When there is an upstream error.

Inherited from:
SourceDrainOps
def toListOrError: List[T] | Error

The "safe" variant of toList.

The "safe" variant of toList.

Attributes

Inherited from:
SourceDrainOps
def transform[U](f: (Iterator[T]) => Iterator[U])(using Ox, BufferCapacity): Source[U]

Attributes

Inherited from:
SourceOps
Generated with