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);
    // Calls 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。