StreamChannel<T> class

An abstract class representing a two-way communication channel.

Users should consider the stream emitting a "done" event to be the canonical indicator that the channel has closed. If they wish to close the channel, they should close the sink—canceling the stream subscription is not sufficient. Protocol errors may be emitted through the stream or through sink.done, depending on their underlying cause. Note that the sink may silently drop events if the channel closes before sink.close is called.

Implementations are strongly encouraged to mix in or extend StreamChannelMixin to get default implementations of the various instance methods. Adding new methods to this interface will not be considered a breaking change if implementations are also added to StreamChannelMixin.

Implementations must provide the following guarantees:

  • The stream is single-subscription, and must follow all the guarantees of single-subscription streams.

  • Closing the sink causes the stream to close before it emits any more events.

  • After the stream closes, the sink is automatically closed. If this happens, sink methods should silently drop their arguments until sink.close is called.

  • If the stream closes before it has a listener, the sink should silently drop events if possible.

  • Canceling the stream's subscription has no effect on the sink. The channel must still be able to respond to the other endpoint closing the channel even after the subscription has been canceled.

  • The sink either forwards errors to the other endpoint or closes as soon as an error is added and forwards that error to the sink.done future.

These guarantees allow users to interact uniformly with all implementations, and ensure that either endpoint closing the stream produces consistent behavior.

Implementers

Constructors

StreamChannel(Stream<T> stream, StreamSink<T> sink)
Creates a new StreamChannel that communicates over stream and sink. [...]
factory
StreamChannel.withCloseGuarantee(Stream<T> stream, StreamSink<T> sink)
Creates a new StreamChannel that communicates over stream and sink. [...]
factory
StreamChannel.withGuarantees(Stream<T> stream, StreamSink<T> sink, { bool allowSinkErrors: true })
Creates a new StreamChannel that communicates over stream and sink. [...]
factory

Properties

sink → StreamSink<T>
The sink for sending values to the other endpoint.
read-only
stream → Stream<T>
The single-subscription stream that emits values from the other endpoint.
read-only
hashCode → int
The hash code for this object.
read-only, inherited
runtimeType → Type
A representation of the runtime type of the object.
read-only, inherited

Methods

cast<S>() StreamChannel<S>
Returns a copy of this with the generic type coerced to S. [...]
changeSink(StreamSink<T> change(StreamSink<T> sink)) StreamChannel<T>
Returns a copy of this with sink replaced by change's return value.
changeStream(Stream<T> change(Stream<T> stream)) StreamChannel<T>
Returns a copy of this with stream replaced by change's return value.
pipe(StreamChannel<T> other) → void
Connects this to other, so that any values emitted by either are sent directly to the other.
transform<S>(StreamChannelTransformer<S, T> transformer) StreamChannel<S>
Transforms this using transformer. [...]
transformSink(StreamSinkTransformer<T, T> transformer) StreamChannel<T>
Transforms only the sink component of this using transformer.
transformStream(StreamTransformer<T, T> transformer) StreamChannel<T>
Transforms only the stream component of this using transformer.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed.
inherited
toString() → String
Returns a string representation of this object.
inherited

Operators

operator ==(dynamic other) → bool
The equality operator.
inherited