StreamController<T>.broadcast 构造函数

StreamController<T>.broadcast({
  1. void onListen()?,
  2. void onCancel()?,
  3. bool sync = false,
})

一个可以多次监听的控制器。

由 stream 返回的 Stream 是一个广播流。它可以被多次监听。

Stream 应该在没有任何订阅者监听它时保持惰性(使用 onListen 回调来开始产生事件)。当没有任何用户监听 stream 时,Streams 应该不泄漏资源(如 websockets)。

广播流在没有监听者时不会缓冲事件。

控制器在调用 addaddErrorclose 时将任何事件分发给所有当前已订阅的监听者。不允许在先前的调用返回之前调用 addaddErrorclose。控制器没有事件内部队列,如果在事件或错误添加时没有监听者,它将直接被丢弃。

每个监听者订阅是独立处理的,如果一个暂停了,只有暂停的监听者受到影响。一个暂停的监听者将内部缓冲事件,直到取消暂停或取消订阅。

如果 sync 为 true,事件可以在 addaddErrorclose 调用期间由流订阅直接触发。返回的流控制器是一个 SynchronousStreamController,必须谨慎使用,并注意不要破坏 Stream 合约。有关同步调度的使用说明,请参阅 Completer.sync。如果有疑问,请保持控制器非同步。

如果 sync 为 false,事件将在添加事件的代码完成后在稍后的时间触发。在这种情况下,关于多个监听者何时接收到事件没有保证,除了每个监听者都将按正确顺序接收到所有事件。每个订阅独立处理事件。如果在异步控制器上发送两个事件并有两个监听者,一个监听者可能先于另一个监听者接收到两个事件。一个监听者必须在事件被启动(即,当 add 被调用)时订阅,并在稍后的事件交付时订阅,才能接收到该事件。

当第一个监听者订阅时,将调用 onListen 回调,当没有更多活动监听者时,将调用 onCancel。如果之后再次添加监听者,在 onCancel 被调用后,将再次调用 onListen

实现

factory StreamController.broadcast(
    {void onListen()?, void onCancel()?, bool sync = false}) {
  return sync
      ? _SyncBroadcastStreamController<T>(onListen, onCancel)
      : _AsyncBroadcastStreamController<T>(onListen, onCancel);
}