Flutter异步原理-Future

前言

在 Dart 中，谈到异步就离不开 Future。无论是 .then()、还是 await，它们背后运作的都是一个私有实现类：_Future ，我们平时使用的 Future 只是一个抽象接口，其真正的实现逻辑由_Future 承担。

class _Future<T> implements Future<T> {
  int _state; // 当前状态，如未完成、已完成、链式等待等。
  _Zone _zone; // 创建时绑定的执行 Zone。
  var _resultOrListeners; // 保存完成结果或注册的监听器链表。

  bool get _mayComplete => (_state & _completionStateMask) == _stateIncomplete;
  bool get _isComplete => (_state & (_stateValue | _stateError)) != 0;
  bool get _hasError => (_state & _stateError) != 0;

  void _complete(FutureOr<T> value); // 完成 Future（同步）
  void _asyncComplete(FutureOr<T> value); // 异步完成 Future（microtask）
  
  void _chainCoreFutureSync(_Future source, _Future target); // 同步触发 Future，如果source已完成，则把结果克隆给target，并触发回调。如果source未完成，
  void _chainCoreFutureAsync(Future source); // 异步链接 Future
  void _chainForeignFuture(Future source); // 链接外部 Future
  
  void _propagateToListeners();//将Future的完成结果（值或错误）传播给所有已注册的监听器
  
  void _addListener(_FutureListener listener); //添加 单个 Future 回调到链表头部
  void _prependListeners(_FutureListener? listeners) //将回调链添加到链表头部
  void _removeListeners(); //移除并返回当前Future的所有监听器
  void __reverseListeners(_FutureListener? listeners); //反转链表
  
}

从我们贴出的 _Future 类结构可以看出，它是 Future 真正的底层实现，承担了 Dart 异步机制中绝大部分实际工作。其主要功能可以拆解为以下四个部分：

状态管理
_Future 本质上是一个状态机（state machine）。它管理异步任务的生命周期：未完成 → 完成（成功/失败）→ 回调派发。
1.1 _state
_state 描述了可能出现的状态，包括：

incomplete：Future 尚未完成；
value：Future 已完成，有一个正常结果；
error：Future 已完成，抛出了异常；
chained：Future 自己不持有结果，而是依赖另一个 Future。
并允许组合判断状态：
bool get _isComplete => (_state & (_stateValue | _stateError)) != 0;
bool get _hasError => (_state & _stateError) != 0;
1.2 _resultOrListeners
_resultOrListeners 是 _Future 状态同步的关键容器字段，它的类型是 var，也就是说它可以根据当前状态动态切换存储内容：
Future未完成时：注册的 listener 链表；
已完成，有一个正常结果：完成的值；
Future 已完成，抛出了异常：异常对象 (AsyncError)；
Future 自己不持有结果，而是依赖另一个 Future：链式模式中所依赖的源 _Future。

可以说，_resultOrListeners 是整个 _Future 状态机的“状态内容仓库”，配合 _state 一起完成了状态标志 + 状态数据的组合表达。
2. 链式触发
当我们在一个 Future 上调用 .then()、.catchError() 或 .whenComplete() 时，Dart 会创建一个新的 Future 并注册对应的回调，当原始 Future 完成后触发回调，新的 Future 则根据回调的返回值决定如何完成。如果返回的是普通值，新 Future 立即完成；如果返回的是另一个 Future，则进入链式等待，直到该 Future 完成。

Future<R> then<R>(FutureOr<R> f(T value), {Function? onError}) {
     //...错误处理
    _Future<R> result = new _Future<R>();
    _addListener(new _FutureListener<T, R>.then(result, f, onError));
    return result;
  }

梳理一下then方法执行的过程：

创建一个新的 _Future result；
构造一个 _FutureListener 对象，把回调绑定进去；
把这个 listener 挂在当前 Future（source）上；
当前 Future 完成时，调度执行 listener 的回调；

如果回调返回了另一个 Future（记作 returned），Dart 会调用 _chainCoreFutureSync(returned, result)，让 target 依赖于 returned 的完成状态，构建链式触发关系。

链式（Chain）
chain 的意思是：我这个 Future 不自己决定什么时候完成，而是等另一个 Future 完成，把它的结果“搬过来”当作自己的结果。

那么出现了一个问题：为什么 result 明明是等 source 完成才有结果，但 Dart 不把它们 chain，在回调里返回 Future 的时候却要 chain？
我们来深入分析 _propagateToListeners() 中对回调返回值的判断处理，是如何决定当前 result 的完成方式的。
关键代码如下：

var returned = listener.handleValue(source._resultOrListeners);

if (returned is Future && !identical(returned, listener.result)) {
  // 回调返回了一个 Future（而且不是自己）
  _chainCoreFutureSync(returned, listener.result); // 关键链式触发点
} else {
  // 回调返回的是普通值，直接完成
  listener.result._complete(returned);
}

问题就变成了：当source Future执行完成时，如果回调函数的返回值是数值就去执行_complete()方法，结束result Future, 如果返回值类型是Future类型会将新的Future(returned) 与result Future的生命周期绑定。这两种不都是一个结束另一个也结束吗？

主要问题在于：情况1 的Future A结束，B也结束，并不是同时完成的，换句话说，Future A结束只是通过回调去通知 B去执行并变成完成状态，而情况2 是B 完全放弃自己的生命周期管理，将自己的回调节点完全转移到A的回调链上。
其实情况1 更符合我们认知的chain的概念，但是情况2是Future设计的精髓，await 关键词将修饰的Future与异步函数返回的Future绑定本质是也是通过chain实现。
Chain 建立流程
下面我们看一下chain建立的过程
2.1 监听器转移机制：

当调用 _setChained 建立链式关系时，会将当前Future的监听器转移到源Future

// 在_chainCoreFutureSync中

_FutureListener ? listeners = target.

_resultOrListeners;

target. _setChained ( source ) ;

source. _prependListeners ( listeners ) ; // 将监听器转移到源Future

这个过程表示：
target 自己不执行任何回调了，而是“把所有后续操作都挂到 source（returned）上”，由它完成后再向下传播。

2.2 完成传播路径：
当源 Future（比如某个回调返回的 Future）完成后：

会调用 _propagateToListeners()，遍历并通知其所有监听器；
如果这些监听器来自于一个链式 Future（如上面的 target），它们会被特殊处理：
- 通过 _FutureListener 的子类包装，确保在值传递的同时更新目标 result 的状态；
- 例如 .then() 的监听器会调用 handleValue()，并可能再触发 _complete() 或新的 chain。

2.3 状态检查：
Dart 会通过以下两个方式标识和追踪链式状态：
_isChained

这是 target 的状态位；
当 target._setChained(source) 被调用时会设置；
表示当前 Future 并不自己持有结果，而是依赖另一个 Future；
它的 _resultOrListeners 字段也被设置为 source，表示链的指向。

_chainSource

提供链式结构中当前 Future 所依赖的源 Future；
如果是链式 Future，_chainSource 返回的是 _resultOrListeners 中的源 Future；
可以用于调试、诊断依赖结构，或从链式 Future 中找出最初的结果拥有者。

总结
当 Dart 判断一个 Future 需要被 chain（即回调返回了另一个 Future），它会让当前 Future 的回调挂到 returned Future 上，完成后再统一传播，并通过 _isChained 和 _resultOrListeners 标记整个依赖关系。
3. 异步调度

- _Completer<T> / _AsyncCompleter<T> / _SyncCompleter<T>：提供手动完成 Future 的机制。
- _complete / _asyncComplete ：完成Future的方法
 _Completer<T>及其子类

abstract class _Completer<T> implements Completer<T> {
  final _Future<T> future = _Future<T>();
  void complete([FutureOr<T>? value]);
  void completeError(Object error, [StackTrace? stackTrace]);
}

class _AsyncCompleter<T> extends _Completer<T> { /* microtask完成Future */ }
class _SyncCompleter<T> extends _Completer<T> { /* 同步立即完成Future */ }

用法区别：

Completer() = _AsyncCompleter（异步完成，本质是调用_asyncComplete）
Completer.sync() = _SyncCompleter（同步完成,本质是调用_complete）

_complete() & _asyncComplete()
Future 支持“立即完成”与“异步完成”两种模式。这一机制由 _complete() 与 _asyncComplete() 方法控制，调用者可以通过不同方式选择调度路径。

_complete()：同步完成

void _complete(FutureOr<T> value) {
    assert(!_isComplete);
    if (value is Future<T>) {
      if (value is _Future<T>) {
        _chainCoreFutureSync(value, this);
      } else {
        _chainForeignFuture(value);
      }
    } else {
      _FutureListener? listeners = _removeListeners();
      _setValue(value);
      _propagateToListeners(this, listeners);
    }
  }

直接完成当前 Future，立即更新状态并分发监听器；
不进入 microtask 队列，适合需要同步完成的场景；
用于 Completer.sync() 创建的同步 Completer。

_asyncComplete()：异步完成

void _asyncComplete(FutureOr<T> value) {
  assert(!_isComplete); // 保证当前 Future 还没完成

  if (value is Future<T>) {
    _chainFuture(value); // 如果是 Future，立即链式绑定
    return;
  }

  _asyncCompleteWithValue(value); // 如果是数值，推入微任务中完成
}

将 _complete() 推入 microtask 队列中异步执行；
保证 Future 的完成不会打断当前同步代码执行栈；
是 Completer() 默认使用的路径。

回调管理
_FutureListener<S, T>

_FutureListener<S, T>：监听回调单元，代表 .then()、.catchError()、.whenComplete() 等注册。

class _FutureListener<S, T> {
  final _Future<T> result; // 回调结果将赋值到的新 Future。
  final int state; // 掩码标记当前 listener 类型。
  final Function? callback; // 正常回调
  final Function? errorCallback; // 错误回调

  FutureOr<T> handleValue(S value); // 成功回调执行
  FutureOr<T> handleError(AsyncError asyncError); // 错误回调执行
  dynamic handleWhenComplete(); // 完成回调执行
}

state取值如下：

stateThen：处理成功值
stateCatchError：处理异常
stateWhenComplete：处理 finally 场景

Listener 链组织结构：单链表

所有 _FutureListener 是以单向链表结构串接的：

每个 _Future 拥有一个 _resultOrListeners 字段；
在未完成状态时，这个字段保存的是 listener 链的头节点；
每次调用 .then() 或 .catchError() 都会创建一个 _FutureListener，并通过 _addListener() 加入链头；
执行完成后，listener 会被 _removeListeners() 清空。

操作方法
_addListener(_FutureListener listener)

将 listener 添加到链表头部；
如果当前 Future 已完成，则立即派发执行；

_prependListeners(_FutureListener? listeners)

将一整段 listener 链表接到当前 listener 链的头部；
用于链式传播中 listener 的转移，例如在 _chainCoreFutureSync() 中：

final listeners = target._removeListeners();
target._setChained(source);
source._prependListeners(listeners);

_removeListeners()

将当前 Future 所有 listener 移除并返回（用于调度）；
移除后 _resultOrListeners 置为 null 或结果值；

__reverseListeners(_FutureListener? listeners)

于反转链表顺序；
保证按注册顺序依次触发，而不是后注册先触发；

完整流程
Future 调用 .then() 注册回调，创建 _FutureListener，加入链表；
Future 完成后，调用 _propagateToListeners()：

遍历 listener 链；
区分状态执行 handleValue / handleError / handleWhenComplete；
将回调返回结果赋值到 listener.result；

若返回的是 Future，则触发 _chainCoreFutureSync()，建立链式；
_propagateToListeners

static void _propagateToListeners(_Future source, _FutureListener? listeners) {
  while (true) {
    if (listeners == null) {
      if (source._hasError && !source._ignoreError) {
        source._zone.handleUncaughtError(source._error);
      }
      return;
    }

    final listener = listeners;
    listeners = listener._nextListener;

    // 执行handleXXX回调
    if (listener.handlesComplete) {
      listener.handleWhenComplete();
    } else if (!source._hasError) {
      listener.handleValue(source._resultOrListeners);
    } else {
      listener.handleError(source._error);
    }

    // 链式传播或继续下一个 listener
  }
}

功能：

调用合适的回调（handleValue/handleError/handleWhenComplete）
把回调结果继续传播给下一个 Future

_chainCoreFutureSync

static void _chainCoreFutureSync(_Future source, _Future target) {
  if (source._isComplete) {
    target._cloneResult(source);
    _propagateToListeners(target, target._removeListeners());
  } else {
    target._setChained(source);
    source._prependListeners(target._removeListeners());
  }
}

功能：

如果 source Future 已完成，直接拷贝它的结果。
如果 source Future 未完成，把 target 链到 source 上等待其完成。

错误信息管理

AsyncError：统一封装错误与堆栈信息。
Zone：隔离执行上下文，管理回调与未捕获异常。
2.4 AsyncError

class AsyncError {
  final Object error;
  final StackTrace stackTrace;
}

标准错误封装，用于 Future 错误状态记录与传播。

2.5 Zone相关

所有 Future 回调 (then/catchError/whenComplete) 都在注册时的 Zone 执行。
Future 完成时如果未捕获错误，通过 Zone 的 handleUncaughtError 抛出。

Flutter异步原理-Future

相关文章

TRAE 配置blender MCP AI自动3D建模

VUE2课程计划表练习

2025年软件工程与数据挖掘国际会议(SEDM 2025)

.NET高频技术点（持续更新中）

pandas中的数据聚合函数：`pivot_table` 和 `groupby`有啥不同？

对golang中CSP的理解

【LunarVim】CMake LSP配置

Mkdocs页面如何嵌入PDF

融合静态图与动态智能：重构下一代智能系统架构

WORD压缩两个免费方法

skywalking服务安装与启动

Qt 中信号与槽（signal-slot）机制支持多种连接方式（ConnectionType）

Midjourney-V7：支持参考图片头像或背景生成新保真图

耀圣-气动带刮刀硬密封法兰球阀：攻克颗粒高粘度介质的自清洁 “利器”

Google云计算原理和应用之分布式锁服务Chubby

SM2Utils NoSuchMethodError: org.bouncycastle.math.ec.ECFieldElement$Fp.＜init

《100天精通Python——基础篇 2025 第16天：异常处理与调试机制详解》

动态创建链表（头插法、尾插法）

利用混合磁共振成像 - 显微镜纤维束成像技术描绘结构连接组|文献速递-深度学习医疗AI最新文献

安全监控之Linux核心资产SSH连接监测邮件