The callback may return either
void or a future.
- A controller with the stream it controls.
- Controller allows sending data, error and done events on its [stream].
- Possible to check whether the stream is paused or not, and whether it has subscribers or not, as well as getting a callback when either of these change.
A controller with a [stream] that supports only one single subscriber.
- If [sync] is true, the returned stream controller is a [SynchronousStreamController], and must be used with the care and attention necessary to not break the [Stream] contract. If in doubt, use the non-sync version.
- Using an asynchronous controller will never give the wrong behavior, but using a synchronous controller incorrectly can cause otherwise correct programs to break.
- A synchronous controller is only intended for optimizing event propagation when one asynchronous event immediately triggers another. It should not be used unless the calls to [add] or [addError] are guaranteed to occur in places where it won’t break
- Use synchronous controllers only to forward (potentially transformed) events from another stream or a future.
- A Stream should be inert until a subscriber starts listening on it (using the [onListen] callback to start producing events). Streams should not leak resources (like websockets) when no user ever listens on the stream.
- The controller buffers all incoming events until a subscriber is registered, but this feature should only be used in rare circumstances.
- The [onPause] function is called when the stream becomes paused. [onResume] is called when the stream resumed.
- The [onListen] callback is called when the stream receives its listener and [onCancel] when the listener ends its subscription. If [onCancel] needs to perform an asynchronous operation, [onCancel] should return a future that completes when the cancel operation is done.
- If the stream is canceled before the controller needs new data the [onResume] call might not be executed.
A controller where [stream] can be listened to more than once.
- The [Stream] returned by [stream] is a broadcast stream. It can be listened to more than once.
- Broadcast streams do not buffer events when there is no listener.
- Each listener subscription is handled independently, and if one pauses, only the pausing listener is affected. A paused listener will buffer events internally until unpaused or canceled.
- Receives events from [source] and puts them into this controller’s stream.
- Events must not be added directly to this controller using [add], [addError], [close] or [addStream], until the returned future is complete.
- Data and error events are forwarded to this controller’s stream. A done event on the source will end the
addStreamoperation and complete the returned future.
- If [cancelOnError] is true, only the first error on [source] is forwarded to the controller’s stream, and the
addStreamends after this. If [cancelOnError] is false, all errors are forwarded and only a done event will end the
addStream. If [cancelOnError] is omitted, it defaults to false.