EsStreamChannel
Description
An abstract class representing a two-way communication channel.
Users should consider the self 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 self sink-canceling the stream subscription is not sufficient. Protocol errors may be emitted through the stream or through self sink done, depending on their underlying cause. Note that the sink may silently drop events if the channel closes before self sink close is called.
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 self 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 self sink done future.
These guarantees allow users to interact uniformly with all implementations, and ensure that either endpoint closing the stream produces consistent behavior.
Class Methods
stream:sink:
Creates a new <EsStreamChannel> that communicates over @stream and @sink.
Note that this stream/sink pair must provide the guarantees listed in the
<EsStreamChannel> class comments. If they don't do so natively,
EsStreamChannel class>>withGuarantees:sink:allowSinkErrors: should be used instead.
Arguments:
stream - <EsStream>
sink - <EsStreamSink>
Answers:
<EsStreamChannel>
withCloseGuarantee:sink:
Creates a new <EsStreamChannel> that communicates over @stream and @sink.
This specifically enforces the second guarantee: closing the sink causes
the stream to close before it emits any more events. This guarantee is
invalidated when an asynchronous gap is added between the original
stream's event dispatch and the returned stream's, for example by
transforming it with an <EsStreamTransformer>. This is a lighter-weight way
of preserving that guarantee in particular than
EsStreamChannel class>>withGuarantees:sink:allowSinkErrors:.
Arguments:
stream - <EsStream>
sink - <EsStreamSink>
Answers:
<EsStreamChannel>
withGuarantees:sink:allowSinkErrors:
Creates a new <EsStreamChannel> that communicates over @stream and @sink.
Unlike [EsStreamChannel class>>stream:sink:], this enforces the guarantees listed in the
Class Comments of <EsStreamChannel>. This makes it somewhat less efficient than
just wrapping a stream and a sink directly, so [EsStreamChannel class>>stream:sink:] should
be used when the guarantees are provided natively.
If @allowSinkErrors is `false`, errors are not allowed to be passed to
@sink. If any are, the connection will close and the error will be
forwarded to [self sink done].
Arguments:
stream - <EsStream>
sink - <EsStreamSink>
allowSinkErrors - <Boolean>
Answers:
<EsStreamChannel>
Instance Methods
changeSink:
Answer a copy of this with #sink replaced by the return value of @aChangeBlock
Arguments:
aChangeBlock - <Block> 1-arg that accepts an <EsStreamSink> and
answers an <EsStreamSink>
Answers:
<EsStreamChannel>
changeStream:
Answer a copy of this with #stream replaced by the return value of @aChangeBlock
Arguments:
aChangeBlock - <Block> 1-arg that accepts an <EsStream> and
answers an <EsStream>
Answers:
<EsStreamChannel>
pipe:
Connects this to [other], so that any values emitted by either are sent
directly to the other.
Arguments:
other - <EsStreamChannel>
Answers:
<EsStreamChannel> self
sink
The sink for sending values to the other endpoint.
Answers:
<EsStreamSink>
stream
The single-subscription stream that emits values from the other endpoint.
Answers:
<EsStream>
transform:
Transforms this using @transformer.
This is identical to calling `transformer bind: channel`.
Arguments:
transformer - <EsStreamChannelTransformer>
Answers:
<EsStreamChannel>
transformSink:
Transforms only the #sink component of this using @transformer.
Arguments:
transformer - <EsStreamSinkTransformer>
Answers:
<EsStreamChannel>
transformStream:
Transforms only the #stream component of this using @transformer.
Arguments:
transformer - <EsStreamTransformer>
Answers:
<EsStreamChannel>
Last modified date: 04/21/2022