A controller with the stream it controls.

This controller allows sending data, error and done events on its stream. This class can be used to create a simple stream that others can listen on, and to push events to that stream.

It's 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.

If the stream starts or stops having listeners (first listener subscribing, last listener unsubscribing), the onSubscriptionStateChange callback is notified as soon as possible. If the subscription stat changes during an event firing or a callback being executed, the change will not be reported until the current event or callback has finished. If the pause state has also changed during an event or callback, only the subscription state callback is notified.

If the subscriber state has not changed, but the pause state has, the onPauseStateChange callback is notified as soon as possible, after firing a current event or completing another callback. This happens if the stream is not paused, and a listener pauses it, or if the stream has been resumed from pause and has no pending events. If the listeners resume a paused stream while it still has queued events, the controller will still consider the stream paused until all queued events have been dispatched.

Whether to invoke a callback depends only on the state before and after a stream action, for example firing an event. If the state changes multiple times during the action, and then ends up in the same state as before, no callback is performed.

If listeners are added after the stream has completed (sent a "done" event), the listeners will be sent a "done" event eventually, but they won't affect the stream at all, and won't trigger callbacks. From the controller's point of view, the stream is completely inert when has completed.

abstract class StreamController<T> implements EventSink<T> {
 /** The stream that this controller is controlling. */
 Stream<T> get stream;

 /**
  * A controller with a [stream] that supports only one single subscriber.
  *
  * If [sync] is true, events may be passed directly to the stream's listener
  * during an [add], [addError] or [close] call. If [sync] is false, the event
  * will be passed to the listener at a later time, after the code creating
  * the event has returned.
  *
  * The controller will buffer all incoming events until the subscriber is
  * registered.
  *
  * 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 the stream is canceled before the controller needs new data the
  * [onResume] call might not be executed.
  */
 factory StreamController({void onListen(),
                           void onPause(),
                           void onResume(),
                           void onCancel(),
                           bool sync: false})
     => sync
        ? new _SyncStreamController<T>(onListen, onPause, onResume, onCancel)
        : new _AsyncStreamController<T>(onListen, onPause, onResume, onCancel);

 /**
  * 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.
  *
  * The controller distributes any events to all currently subscribed
  * listeners.
  * It is not allowed to call [add], [addError], or [close] before a previous
  * call has returned.
  *
  * If [sync] is true, events may be passed directly to the stream's listener
  * during an [add], [addError] or [close] call. If [sync] is false, the event
  * will be passed to the listener at a later time, after the code creating
  * the event has returned.
  *
  * Each listener is handled independently, and if they pause, only the pausing
  * listener is affected. A paused listener will buffer events internally until
  * unpaused or canceled.
  *
  * If [sync] is false, no guarantees are given with regard to when
  * multiple listeners get the events, except that each listener will get
  * all events in the correct order. If two events are sent on an async
  * controller with two listeners, one of the listeners may get both events
  * before the other listener gets any.
  * A listener must be subscribed both when the event is initiated (that is,
  * when [add] is called) and when the event is later delivered, in order to
  * get the event.
  *
  * The [onListen] callback is called when the first listener is subscribed,
  * and the [onCancel] is called when there are no longer any active listeners.
  * If a listener is added again later, after the [onCancel] was called,
  * the [onListen] will be called again.
  */
 factory StreamController.broadcast({void onListen(),
                                     void onCancel(),
                                     bool sync: false}) {
   return sync
       ? new _SyncBroadcastStreamController<T>(onListen, onCancel)
       : new _AsyncBroadcastStreamController<T>(onListen, onCancel);
 }

 /**
  * Returns a view of this object that only exposes the [EventSink] interface.
  */
 EventSink<T> get sink;

 /**
  * Whether the stream is closed for adding more events.
  *
  * If true, the "done" event might not have fired yet, but it has been
  * scheduled, and it is too late to add more events.
  */
 bool get isClosed;

 /**
  * Whether the subscription would need to buffer events.
  *
  * This is the case if the controller's stream has a listener and it is
  * paused, or if it has not received a listener yet. In that case, the
  * controller is considered paused as well.
  *
  * A broadcast stream controller is never considered paused. It always
  * forwards its events to all uncanceled listeners, if any, and let them
  * handle their own pausing.
  */
 bool get isPaused;

 /** Whether there is a subscriber on the [Stream]. */
 bool get hasListener;

 /**
  * Send or enqueue an error event.
  *
  * Also allows an objection stack trace object, on top of what [EventSink]
  * allows.
  */
 void addError(Object error, [Object stackTrace]);
}