What's the difference between a broadcast StreamController and a single-subscription one?
Short Answer
A single-subscription StreamController allows only one listener ever, and buffers events until that listener subscribes; a broadcast StreamController allows multiple simultaneous listeners but doesn't buffer events for listeners that subscribe late.
By default, StreamController() creates a single-subscription stream — appropriate for a one-time file read or a single HTTP response stream. Calling .listen() a second time throws a StateError.
StreamController.broadcast() supports any number of listeners, fitting use cases like a global event bus or a WebSocket connection multiple widgets observe. The tradeoff: broadcast streams don't buffer events — if a listener subscribes after an event was already emitted, it simply misses that event. Choosing the right controller type upfront matters, since converting between them later requires re-architecting how the stream is consumed.
Code Example
// Single-subscription — one listener only
final controller = StreamController<int>();
// Broadcast — many listeners, no buffering
final broadcastController = StreamController<int>.broadcast();Common Mistakes
- ×Calling .listen() twice on a single-subscription stream and being surprised by the StateError.
- ×Assuming a broadcast stream replays past events to a newly-added listener — it doesn't.