A finalizer which can be attached to Dart objects.

A finalizer can create attachments betweenthe finalizer and any number of Dart values,by callingattach with the value, along with afinalization token and an optionalattach key,which are part of the attachment.

When a Dart value becomes inaccessible to the program,any finalizer that currently has an attachment tothe valuemay have its callback function calledwith the attachment's finalization token.

Example:

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.}

This example has an example of an external resource that needs clean-up.The finalizer is used to clean up an external connection when theuser of the API no longer has access to that connection.The example uses the same object as attached object and detach key,which is a useful approach when each attached object can be detachedindividually. Being a detachment key doesn't keep an object alive.

No promises are made that the callback will ever be called.The only thing that is guaranteed is that if a finalizer's callbackis called with a specific finalization token as argument,then at least one value with an attachment to the finalizerthat has that finalization token,is no longer accessible to the program.

If the finalizeritself becomes unreachable,it's allowed to be garbage collectedand then it won't trigger any further callbacks.Always make sure to keep the finalizer itself reachable while it's needed.

If multiple finalizers are attached to a single object,or the same finalizer is attached multiple times to an object,and that object becomes inaccessible to the program,then any number (including zero) of those attachments may triggertheir associated finalizer's callback.It will not necessarily be all or none of them.

Finalization callbacks will happen asevents.They will not happen during execution of other code,and not as a microtask,but as high-level events similar to timer events.

Finalization callbacks must not throw.

When running on the Dart native runtime, and the callback is a nativefunction rather than a Dart function, usedart:ffi'sNativeFinalizerinstead.

Annotations

• @Since.new("2.17")

Constructors

Finalizer(voidcallback(T))

Creates a finalizer with the given finalization callback.

factory

Properties

hashCode→int

The hash code for this object.

no setterinherited

runtimeType→Type

A representation of the runtime type of the object.

no setterinherited

Methods

attach(Objectvalue,TfinalizationToken, {Object?detach})→ void

Attaches this finalizer tovalue.

detach(Objectdetach)→ void

Detaches this finalizer from values attached withdetach.

noSuchMethod(Invocationinvocation)→ dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString()→String

A string representation of this object.

inherited

Operators

operator ==(Objectother)→bool

The equality operator.

inherited