Flutter 中的异步事件处理之StreamController源码解析(二)

StreamController

同步流、异步流

scss 复制代码
/// A controller with a [stream] that supports only one single subscriber.
///
/// If [sync] is true, the returned stream controller is a
/// [SynchronousStreamController], and must be used with the care
/// and attention necessary to not break the [Stream] contract. If in doubt,
/// use the non-sync version.
///
/// Using an asynchronous controller will never give the wrong
/// behavior, but using a synchronous controller incorrectly can cause
/// otherwise correct programs to break.
///
/// A synchronous controller is only intended for optimizing event
/// propagation when one asynchronous event immediately triggers another.
/// It should not be used unless the calls to [add] or [addError]
/// are guaranteed to occur in places where it won't break `Stream` invariants.
///
/// Use synchronous controllers only to forward (potentially transformed)
/// events from another stream or a future.
///
/// A Stream should be inert until a subscriber starts listening on it (using
/// the [onListen] callback to start producing events). Streams should not
/// leak resources (like websockets) when no user ever listens on the stream.
///
/// The controller buffers all incoming events until a subscriber is
/// registered, but this feature should only be used in rare circumstances.
///
/// 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 [onCancel] needs to perform an asynchronous operation,
/// [onCancel] should return a future that completes when the cancel operation
/// is done.
///
/// If the stream is canceled before the controller needs data the
/// [onResume] call might not be executed.
factory StreamController(
    {void onListen()?,
    void onPause()?,
    void onResume()?,
    FutureOr<void> onCancel()?,
    bool sync = false}) {
  return sync
      ? _SyncStreamController<T>(onListen, onPause, onResume, onCancel)
      : _AsyncStreamController<T>(onListen, onPause, onResume, onCancel);
}
  • 一个带有 stream 的控制器,仅支持单个订阅者。
  • 如果 sync 为 true,返回的流控制器是一个 SynchronousStreamController,必须小心谨慎地使用,以确保不破坏 Stream 契约。如果有疑虑,应使用非同步版本。
  • 使用异步控制器永远不会导致错误行为,但不正确地使用同步控制器可能会导致 其他正确的程序出现问题。
  • 同步控制器仅用于在一个异步事件立即触发另一个事件的情况下优化事件传播。
  • 除非可以确保 add 或 addError 调用发生在不会破坏 Stream 不变式的地方,否则不应使用同步控制器。
  • 只有在将(可能经过转换)事件从另一个流或 Future 转发时,才应使用同步控制器。
  • 直到有订阅者开始监听流(使用 onListen 回调来开始生成事件)之前,流应该是不活动的。流不应在没有用户监听流的情况下泄露资源(例如 WebSockets)。
  • 控制器会缓冲所有传入的事件,直到注册订阅者,但这个功能只应在极少数情况下使用。
  • 当流暂停时,onPause 函数将被调用。当流恢复时,onResume 将被调用。
  • 当流接收到其监听器时,将调用 onListen 回调,并在监听器结束其订阅时调用 onCancel。
  • 如果 onCancel 需要执行异步操作,onCancel 应该返回一个在取消操作完成时完成的 future。
  • 如果流在控制器需要数据之前被取消,onResume 调用可能不会执行。
  • sync:是否创建同步控制器,默认为 false。
相关推荐
程序员大阳20 分钟前
副队长Vue3教程(2)--Vite 搭建 Vue 项目,认识目录结构
前端·javascript·vue.js·vite·创建项目·目录结构·项目结构
濮水大叔28 分钟前
Cabloy/Zova 与 Next.js 的 SSR 水合差异
前端·typescript·next.js
SoaringHeart1 小时前
Flutter最佳实践:用 flutter_html 渲染富文本
前端·flutter
Flynt2 小时前
Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食
前端·chrome·ai编程
北城笑笑3 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
程序员韩星3 小时前
OpenAI 兼容接口返回 404,先查请求地址,再查模型名
前端·人工智能·http
Patrick_Wilson3 小时前
构建通过了,为什么有些浏览器还会白屏?
前端·javascript·浏览器
其实防守也摸鱼4 小时前
用 Claude Code 重构遗留系统:从评估到落地的完整指南
前端·网络·人工智能·chrome·安全·重构
七仔啊4 小时前
CNC计算机数控加工模拟器
前端
张一凡935 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent