EsStreamSubscription
Description
A subscription on events from a Stream.
When you listen on an EsStream using EsStream>>listen:, an <EsStreamSubscription> object is returned.
The subscription provides events to the listener, and holds the callbacks used to handle the events. The subscription can also be used to unsubscribe from the events, or to temporarily pause the events from the stream.
Class Methods
None
Instance Methods
asFuture
Returns a future that handles the #onDone: and #onError: handlers.
This method *overwrites* the existing #onDone: and #onError: handlers
with new ones that complete the answered future.
In case of an error the subscription will automatically cancel (even
when it was listening with `cancelOnError` set to `false`).
In case of a `done` event the future completes with `nil`
Answers:
<EsFuture>
asFuture:
Returns a future that handles the #onDone: and #onError: handlers.
This method *overwrites* the existing #onDone: and #onError: handlers
with new ones that complete the answered future.
In case of an error the subscription will automatically cancel (even
when it was listening with `cancelOnError` set to `false`).
In case of a `done` event the future completes with the given
@futureValue.
Arguments:
futureValue - <Object>
Answers:
<EsFuture>
cancel
Cancels this subscription.
After this call, the subscription no longer receives events.
The stream may need to shut down the source of events and clean up after
the subscription is canceled.
Returns a future that is completed once the stream has finished
its cleanup.
Typically, cleanup happens when the stream needs to release resources.
For example, a stream might need to close an open file (as an asynchronous
operation). If the listener wants to delete the file after having
canceled the subscription, it must wait for the cleanup future to complete.
If the cleanup raise an exception, which it really shouldn't, the answered future
completes with that error.
Answers:
<EsFuture>
isPaused
Whether the StreamSubscription is currently paused.
If there have been more calls to #pause: than to #resume on this
stream subscription, the subscription is paused, and this getter
answers `true`.
Returns `false` if the stream can currently emit events, or if
the subscription has completed or been cancelled.
Answers:
<Boolean>
onData:
Replaces the data event handler of this subscription.
The @handleData block is called for each data event of the stream
after this method is called.
If @handleData is `nil`, data events are ignored.
This method replaces the current handler set by the invocation of
EsStream>>listen: or by a previous call to #onData:.
Arguments:
handleData - <Block> 0-arg block or nil
onDone:
Replaces the done event handler of this subscription.
The @handleDone block is called when the stream closes.
The value may be `nil`, in which case no block is evaluated.
This method replaces the current handler set by the invocation of
EsStream>>listen:, by calling #asEsFuture:, or by a previous call to #onDone:
Arguments:
handleDone - <Block> 0-arg block or nil
onError:
Replaces the error event handler of this subscription.
The @handleError block must be able to be called with either
one positional argument, or with two positional arguments
where the seconds is always an <EsAsyncStackTrace>.
The @handleError argument may be `nil`, in which case further
error events are considered *unhandled*, and will be reported to
the EsAsyncUncaughtErrorHandler.
The provided block is called for all error events from the
stream subscription.
This method replaces the current handler set by the invocation of
EsAsyncStream>>listen:, by calling #asEsFuture:, or by a previous call to #onError:.
Arguments:
handleDone - <Block> 2-arg block or nil
pause
Requests that the stream pauses events until further notice.
While paused, the subscription will not fire any events.
If it receives events from its source, they will be buffered until
the subscription is resumed.
For non-broadcast streams, the underlying source is usually informed
about the pause,
so it can stop generating events until the subscription is resumed.
To avoid buffering events on a broadcast stream, it is better to
cancel this subscription, and start to listen again when events
are needed, if the intermediate events are not important.
A call to #resume will also undo a pause.
pause:
Requests that the stream pauses events until further notice.
While paused, the subscription will not fire any events.
If it receives events from its source, they will be buffered until
the subscription is resumed.
For non-broadcast streams, the underlying source is usually informed
about the pause,
so it can stop generating events until the subscription is resumed.
To avoid buffering events on a broadcast stream, it is better to
cancel this subscription, and start to listen again when events
are needed, if the intermediate events are not important.
If @resumeSignal is provided, the stream subscription will undo the pause
when the future completes, as if by a call to #resume:.
If the future completes with an error,
the stream will still resume, but the error will be considered unhandled
and is passed to the EsAsyncUncaughtErrorHandler.
A call to #resume will also undo a pause.
If the subscription is paused more than once, an equal number
of resumes must be performed to resume the stream.
Calls to #resume and the completion of a @resumeSignal are
interchangeable - the #pause: which was passed a @resumeSignal may be
ended by a call to #resume, and completing the @resumeSignal may end a
different #pause:.
It is safe to #resume or complete a @resumeSignal even when the
subscription is not paused, and the resume will have no effect.
Arguments:
resumeSignal - <EsFuture>
resume
Resumes after a pause.
This undoes one previous call to #pause:.
When all previously calls to #pause: have been matched by a calls to
#resume, possibly through a `resumeSignal` passed to #pause:,
the stream subscription may emit events again.
It is safe to #resume: even when the subscription is not paused, and the
resume will have no effect.
Last modified date: 04/21/2022