A stream controller that delivers its events synchronously.
A synchronous stream controller is intended for cases wherean already asynchronous event triggers an event on a stream.
Instead of adding the event to the stream in a later microtask,causing extra latency, the event is instead fired immediately by thesynchronous stream controller, as if the stream event wasthe current event or microtask.
The synchronous stream controller can be used to break the contractonStream, and it must be used carefully to avoid doing so.
The only advantage to using aSynchronousStreamController over anormalStreamController is the improved latency.Only use the synchronous version if the improvement is significant,and if its use is safe. Otherwise just use a normal stream controller,which will always have the correct behavior for aStream, and won'taccidentally break other code.
Adding events to a synchronous controller should only happen as thevery last part of the handling of the original event.At that point, adding an event to the stream is equivalent toreturning to the event loop and adding the event in the next microtask.
Each listener callback will be run as if it was a top-level eventor microtask. This means that if it throws, the error will be reported asuncaught as soon as possible.This is one reason to add the event as the last thing in the original eventhandler – any action done after adding the event will delay the report oferrors in the event listener callbacks.
If an event is added in a setting that isn't known to be another event,it may cause the stream's listener to get that event before the listeneris ready to handle it. We promise that after callingStream.listen,you won't get any events until the code doing the listen has completed.Callingadd in response to a function call of unknown origin may breakthat promise.
AnonListen callback from the controller isnot an asynchronous event,and adding events to the controller in theonListen callback is alwayswrong. The events will be delivered before the listener has even receivedthe subscription yet.
The synchronous broadcast stream controller also has a restrictions that anormal stream controller does not:Theadd,addError,close andaddStream methodsmust not becalled while an event is being delivered.That is, if a callback on a subscription on the controller's stream causesa call to any of the functions above, the call will fail.A broadcast stream may have more than one listener, and if anevent is added synchronously while another is being also in the processof being added, the latter event might reach some listeners beforethe former. To prevent that, an event cannot be added while a previousevent is being fired.This guarantees that an event is fully delivered when thefirstadd,addError orclose returns,and further events will be delivered in the correct order.
This still only guarantees that the event is delivered to the subscription.If the subscription is paused, the actual callback may still happen later,and the event will instead be buffered by the subscription.Barring pausing, and the following buffered events that haven't beendelivered yet, callbacks will be called synchronously when an event is added.
Adding an event to a synchronous non-broadcast stream controller whileanother event is in progress may cause the second event to be delayedand not be delivered synchronously, and until that event is delivered,the controller will not act synchronously.
- Implemented types
Properties
- done→Future
- A future which is completed when the stream controller is donesending events.no setterinherited
- hashCode→int
- The hash code for this object.no setterinherited
- hasListener→bool
- Whether there is a subscriber on theStream.no setterinherited
- isClosed→bool
- Whether the stream controller is closed for adding more events.no setterinherited
- isPaused→bool
- Whether the subscription would need to buffer events.no setterinherited
- onCancel↔FutureOr<
void> Function()? - The callback which is called when the stream is canceled.getter/setter pairinherited
- onListen↔ void Function()?
- The callback which is called when the stream is listened to.getter/setter pairinherited
- onPause↔ void Function()?
- The callback which is called when the stream is paused.getter/setter pairinherited
- onResume↔ void Function()?
- The callback which is called when the stream is resumed.getter/setter pairinherited
- runtimeType→Type
- A representation of the runtime type of the object.no setterinherited
- sink→StreamSink<
T> - Returns a view of this object that only exposes theStreamSink interface.no setterinherited
- stream→Stream<
T> - The stream that this controller is controlling.no setterinherited
Methods
- add(
Tdata)→ void - Adds event to the controller's stream.override
- addError(
Objecterror, [StackTrace?stackTrace])→ void - Adds error to the controller's stream.override
- addStream(
Stream< T> source, {bool?cancelOnError})→Future - Receives events from
sourceand puts them into this controller's stream.inherited - close(
)→Future - Closes the controller's stream.override
- noSuchMethod(
Invocationinvocation)→ dynamic - Invoked when a nonexistent method or property is accessed.inherited
- toString(
)→String - A string representation of this object.inherited
Operators
- operator ==(
Objectother)→bool - The equality operator.inherited