dart:core

Finalizer<T> class

Финализатор, который можно прикреплять к объектам Dart.

Финализатор может создавать связи между собой и любым количеством значений Dart, вызывая attach с этим значением, а также токеном финализации и необязательным ключом прикрепления, которые являются частью связи.

Когда значение 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 Native, если функция обратного вызова является нативной, а не функцией Dart, используйте NativeFinalizer из dart:ffi.

Аннотации

• @Since("2.17")

Конструкторы

Finalizer(void callback(T))

фабричный

Создаёт финализатор с указанной функцией обратного вызова финализации.

Свойства

hashCode → int

только для чтенияунаследовано

Хеш-код этого объекта.

runtimeType → Type

только для чтенияунаследовано

Представление типа объекта во время выполнения.

Методы

attach(Object value, T finalizationToken, {Object? detach}) → void

Прикрепляет этот финализатор к value.

detach(Object detach) → void

Отсоединяет этот финализатор от значений, прикреплённых с помощью detach.

noSuchMethod(Invocation invocation) → dynamic

унаследовано

Вызывается при обращении к несуществующему методу или свойству.

toString() → String

унаследовано

Строковое представление этого объекта.

Операторы

operator ==(Object other) → bool

унаследовано

Оператор равенства.