A pipe backed by a fixed-length buffer.
A pipe backed by a fixed-length buffer. Items can be pushed into the buffer
until it fills, at which point the Full
PushResult is returned. When
items are pulled out of the pipe the signal return in the Full result is
fired.
The most efficient way to use a BufferedPipe
is with the pullWhile
method. This allows the pipe to completely bypass buffering and items pushed
to the pipe are fast-tracked directly into the provided processing function.
Wraps 2 sinks and will automatically begin reading from the second only when the first is empty.
Wraps 2 sinks and will automatically begin reading from the second only when
the first is empty. The None
from the first sink is never exposed. The
first error reported from either sink is propagated.
A Pipe is an abstraction that mediates interactions between producers and consumers of a stream of data.
A Pipe is an abstraction that mediates interactions between producers and consumers of a stream of data. It can be thought of as a mutable buffer that has built-in features for addressing both back-pressure (when the pipe "fills") and forward-pressure (when the pipe "empties"). Items are "pushed" into the pipe and "pulled" out of it.
A Pipe is the combination of the Source and Sink traits, representing
the producer and consumer interfaces, respectively. It should be noted that
a Pipe does not contain additional state beyond that provided by the Source
and Sink interfaces. In other words, it may be possible for the producer
Sink
side of a pipe to be Closed or Terminated, while the consumer Source
side is in a different state.
The canonical implementation is the BufferedPipe, backed by a fixed-length buffer. However pipes have many monadic and combinatorial capabilities, allowing them to be mapped, linked together, flattened, and multiplexed.
As opposed to other libraries/frameworks that have a concept of streams, sources, and sinks, these pipes are intended for low-level stream management. They support several features that allow interation with pipes to be very fast and efficient. They form the backbone of all connection handlers and as well as streaming protocols like http/2. Pipes are *not* thread-safe.
A Signal
is a callback mechanism used by both Source and Sink to manage forward/back-pressure.
A Signal
is a callback mechanism used by both Source and Sink to manage forward/back-pressure. In both cases it is returned when a requested operation cannot immediately complete, but can at a later point in time. For example, when pulling from a Source, if no item is immediately available, a signal is returned that will be triggered when an item is available to pull.
val stream: Source[Int] = //... stream.pull() match { case PullResult.Item(num) => //... case PullResult.Full(signal) => signal.notify { //when this callback function is called, it is guaranteed that an item is now available stream.pull()//... } }
Signals are multi-listener, so that multiple consumers can attach callbacks to a single listener. Callbacks are fired in the order they are queued, and generally conditions for triggering a signal are re-checked for each listener (so that, for example, if one item is pushed to an empty Source, only one listener is signaled).
A Sink is the write side of a pipe.
A Sink is the write side of a pipe. It allows you to push items to it, and will return whether or not it can accept more data. In the case where the pipe is full, the Sink will return a mutable Trigger and you can attach a callback to for when the pipe can receive more items
A Source
is the read interface for a Pipe.
A Source
is the read interface for a Pipe. Items can be pulled out of
the source if available. When no item is available, a returned Signal
can be used to be notified when items are available.
Sources can be mapped using the functionality provided in the SourceMapper typeclass
This controller interface can be used to transcode from one encoding to another in a connection handler pipeline
A Transcoder is used to convert streams of one encoding to streams of another.
A Transcoder is used to convert streams of one encoding to streams of another. The two streams are intended to be part of a duplex pipeline, so input is transcoded from A to B, and output is transcoded the other way B to A
When a user attempts to push a value into a pipe, and the pipe either fills or was already full, a Trigger is returned in the PushResult.
When a user attempts to push a value into a pipe, and the pipe either fills or was already full, a Trigger is returned in the PushResult. This is essentially just a fillable callback function that is called when the pipe either becomes empty or is closed or terminated
Notice that when the trigger is executed we don't include any information about the state of the pipe. The handler can just try pushing again to determine if the pipe is dead or not.
Multiplexing is the process of combining multiple independant streams into a single stream.
Multiplexing is the process of combining multiple independant streams into a single stream. Each message in the multiplexed stream carries information about which sub-stream it originated from, so that eventually the stream can be demultiplexed back into the constituent sub-streams.
By multiplexing a "base" Sink[T]
, a new Sink[SubSource[K,T]]
is
created, with each SubSource containing a Source[T]
. When a
Source is pushed into the multiplexing sink, all messages pushed to
that source are routed into the base sink.
Likewise, demultiplexing a multiplexed Source[T]
will create a
Source[SubSource[K,T]]
, with each SubSource being one of the
sub-streams being fed into the multiplexed source.
A PullAction is the return type of a processing function passed to
Source.pullWhile
method.
A PullAction is the return type of a processing function passed to
Source.pullWhile
method. It signals to the source what action should
be taken after the processing function has processed the next item from the
source.