Stream API does not document whether listeners can process events synchronously upon listen

[LewisHolliday]

Whether through stream.listen or other methods of Stream, listeners should not appear to have processed events in the current microtask. At least, that's what I think the design intends.

Evidence of that can be found throughout the API docs of StreamController and SynchronousStreamController: streamController.add StreamController() StreamController-class

I do not think the invariants mentioned in those links are well defined in the Stream API documentation. Stream's class documentation's first line: "A source of asynchronous data events." might be the closest it gets.

Also, I think the docs should clarify whether listeners of a given stream may appear to process any events in a microtask where a streamSubscription.resume of said stream was called.

[lrhn]

Correct. No event should be fired in direct response to StreamSubscription.resume or Stream.listen. Events should be fired as if they are separate asynchronous events, coming from the microtask event queue or top-level event loop.

The SynchronousStreamController can be used to break this contract. If it does so, all bets are off on whether library operations will even work for that stream. It's unspecified behavior, basically. The synchronous controller should only be used to emit events from code that is already running as an event, which onResume and onListen are not.

It could probably be expressed more directly than it is today.