NativeFinalizer 类 抽象 终极

可以附加到 Dart 对象上的本地终止器。

当 附加 到 Dart 对象时，该终止器的本地回调将在 Dart 对象被垃圾回收或由于其他原因不可访问后调用。

回调将尽可能早地发生，在对象变得对程序不可访问时发生，也可能在程序执行期间任何时候发生。最晚，在隔离器组关闭时，确保对每个隔离器组中的对象调用该回调。

与来自 dart:core 的 Finalizer 相比，它不承诺始终调用附加的回调，本机终止器承诺在隔离器组关闭之前，所有附加的终止器都将至少调用一次，并且一旦对象被视为不可访问，回调就尽可能快地调用。

请注意，隔离器组不一定保证正常关闭，因为整个进程可能崩溃或被如 exit 之类的函数突然终止。这意味着 NativeFinalizer 不能依赖于在程序退出时执行操作。

当回调是 Dart 函数而不是本地函数时，使用 Finalizer。

本地终止器可以用来关闭本地资源。请看以下示例。

/// [Database] enables interacting with the native database.
///
/// After [close] is called, cannot be used to [query].
///
/// If a [Database] is garbage collected, it is automatically closed by
/// means of a native finalizer. Prefer closing manually for timely
/// release of native resources.
///
/// Note this class is incomplete and for illustration purposes only.
class Database implements Finalizable {
  /// The native finalizer runs [_closeDatabasePointer] on [_nativeDatabase]
  /// if the object is garbage collected.
  ///
  /// Keeps the finalizer itself reachable, otherwise it might be disposed
  /// before the finalizer callback gets a chance to run.
  static final _finalizer =
      NativeFinalizer(_nativeDatabaseBindings.closeDatabaseAddress.cast());

  /// The native resource.
  ///
  /// Should be closed exactly once with [_closeDatabase] or
  /// [_closeDatabasePointer].
  Pointer<_NativeDatabase> _nativeDatabase;

  /// Used to prevent double close and usage after close.
  bool _closed = false;

  Database._(this._nativeDatabase);

  /// Open a database.
  factory Database.open() {
    final nativeDatabase = _nativeDatabaseBindings.openDatabase();
    final database = Database._(nativeDatabase);
    _finalizer.attach(database, nativeDatabase.cast(), detach: database);
    return database;
  }

  /// Closes this database.
  ///
  /// This database cannot be used anymore after it is closed.
  void close() {
    if (_closed) {
      return;
    }
    _closed = true;
    _finalizer.detach(this);
    _nativeDatabaseBindings.closeDatabase(_nativeDatabase);
  }

  /// Query the database.
  ///
  /// The database should not have been closed.
  void query() {
    if (_closed) {
      throw StateError('The database has been closed.');
    }

    // Query the database.
  }
}

final _nativeDatabaseBindings = _NativeDatabaseLib(DynamicLibrary.process());

// The following classes are typically generated with `package:ffigen`.
// Use `symbol-address` to expose the address of the close function.
class _NativeDatabaseLib {
  final DynamicLibrary _library;

  _NativeDatabaseLib(this._library);

  late final openDatabase = _library.lookupFunction<
      Pointer<_NativeDatabase> Function(),
      Pointer<_NativeDatabase> Function()>('OpenDatabase');
  late final closeDatabaseAddress =
      _library.lookup<NativeFunction<Void Function(Pointer<_NativeDatabase>)>>(
          'CloseDatabase');
  late final closeDatabase = closeDatabaseAddress
      .asFunction<void Function(Pointer<_NativeDatabase>)>();
}

final class _NativeDatabase extends Opaque {}