Please, clarify description for Stream.timeout() #30163
Description
The description for Stream.timeout() reads:
Stream<T> timeout(
Duration timeLimit, {
void onTimeout(
EventSink<T> sink
)
})
Creates a new stream with the same events as this stream.Whenever more than timeLimit passes between two events from this stream, the onTimeout function is called.
The countdown doesn't start until the returned stream is listened to. The countdown is reset every time an event is forwarded from this stream, or when the stream is paused and resumed.
The onTimeout function is called with one argument: an EventSink that allows putting events into the returned stream. This EventSink is only valid during the call to onTimeout.
If onTimeout is omitted, a timeout will just put a TimeoutException into the error channel of the returned stream.
The returned stream is a broadcast stream if this stream is. If a broadcast stream is listened to more than once, each subscription will have its individually timer that starts counting on listen, and the subscriptions' timers can be paused individually.
- Please, explicitly specify at which moments countdown starts and stops.
For example:
Whenever more than timeLimit passes between two events from this stream, the onTimeout function is called.
The countdown doesn't start until the returned stream is listened to.
It is easy to conclude from this, that countdown starts on first event, which is wrong, I believe.
The countdown is reset every time an event is forwarded from this stream, or when the stream is paused and resumed.
I believe, 'reset' means 'set countdown to initial value (i.e. timeLimit)', but is the countdown stopped or started or it state does not change? especially in cases of stream paused or resumed actions?
What happens with countdown, when it reaches zero? Does countdown stopps or starts again with initial value?
- Please, clarify the case if
onTimeoutthrows error. Is this error added to the returned stream?