Finalizer<T> 类 抽象 最终

可以附加到 Dart 对象的终结器。

终结器可以通过调用 attach 并传入值、一个 最终化令牌 和可选的 附加键（这些是附加内容的一部分），在终结器与任意数量的 Dart 值之间创建关联。

当 Dart 值对程序不可用时，任何当前与该值关联的终结器都可能调用其回调函数，并传递附加的最终化令牌。

示例

class Database {
  // Keeps the finalizer itself reachable, otherwise it might be disposed
  // before the finalizer callback gets a chance to run.
  static final Finalizer<DBConnection> _finalizer =
      Finalizer((connection) => connection.close());

  final DBConnection _connection;

  Database._fromConnection(this._connection);

  factory Database.connect() {
    // Wraps the connection in a nice user API,
    // *and* closes connection if the user forgets to.
    final connection = DBConnection.connect();
    final wrapper = Database._fromConnection(connection);
    // Get finalizer callback when `wrapper` is no longer reachable.
    _finalizer.attach(wrapper, connection, detach: wrapper);
    return wrapper;
  }

  void close() {
    // User requested close.
    _connection.close();
    // Detach from finalizer, no longer needed.
    _finalizer.detach(this);
  }

  // Some useful methods.
}

此示例包含一个外部资源，需要清理。当 API 的使用者不再拥有对该连接的访问权限时，使用终结器来清理外部连接。示例使用相同的对象作为附加对象和分离开键，这在每个附加对象可以分别分离的情况下是一种有用的方法。作为分离键不会使对象保持活动状态。

不保证回调将始终被调用。唯一保证的是，如果终结器的回调作为一个特定的最终化令牌的参数被调用，那么至少有一个附加了该令牌的终结器，该值已经不再对程序可见。

如果终结器 本身 变得无法访问，它可能被垃圾回收，并且不会触发任何进一步的回调。始终确保在需要时保持终结器自身可访问。

如果多个终结器附着在单个对象上，或者相同的终结器多次附加到对象上，并且该对象对程序不可用，那么这些附加中的任何数量（包括零）都可能触发其关联的终结器的回调。不一定所有或没有的都会触发。

最终化回调将以 事件 的形式发生。它们不会在其他代码执行期间发生，也不会作为微任务发生，而是作为类似于定时器事件的高级事件。

最终化回调不得抛出异常。

当在 Dart 原生运行时运行时，并且回调是本地函数而不是 Dart 函数时，请使用 dart:ffi 的 NativeFinalizer。