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.