Expose WeakRef and finalization tracking APIs in Dart

[jacob314]

Admin comment by @mit-mit:

This request is being tracked as a feature via issue dart-lang/sdk#47772.

For details, see the working proposal feature specification:
https://github.com/dart-lang/language/blob/master/accepted/future-releases/1847%20-%20FinalizationRegistry/proposal.md

---

Original feature request by @jacob314:

The C API for Dart has always exposed this functionality but it was not exposed in the Dart core libraries because it could not be implemented in JavaScript.
The WeakRef proposal has now landed in JavaScript so WeakRef and finalization tracking could now supported in debug Dart builds on all platforms.
Support is available in all major browsers but Safari so the feature would need to be prohibited in release builds until that changes.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry
https://github.com/tc39/proposal-weakrefs

Providing this APIs would allow Dart memory leak detection tools to work on both the Dart VM and JavaScript and would simplify integration of leak detection tools into unittests on the VM. For example, without this API, the VMService must be used to detect leaked objects with some performance overhead to find all instances of the LeakedObject class.

The apis could reasonably be exposed in dart:core, dart:collection (as an iterable WeakMap), or dart:developer.
It could make sense to expose this in dart:developer as that would make it less surprising if the APIs work in debug environments but not production environments.

[leafpetersen]

cc @lrhn @natebosch @srujzs @sigmundch @nshahan @sigmundch

[mraleph]

This feature is also beneficial for dart:ffi use cases - it would allow us to have finalization mechanism without designing a custom one /cc @dcharkes @mkustermann

[jacob314]

Fyi @ferhatb who may have an idea when Safari will support this functionality.

[nshahan]

This sounds like it could be a useful addition to dart:developer. Adding to dart:core or dart:collection makes it harder for dart2js if the support from safari is still not there.

Are you proposing the same API as the JavaScript version or some other API that we need to adapt to what is now available in JavaScript?

[mraleph]

Safari Technology Preview 14.1 Release 118 has the support for both WeakRef and FinalizationRegistry. So we are almost there.

[jacob314]

I don't see any reason to make the WeakRef API more than a strongly typed extension of the JS APIs. FinalizationRegistry could alternately be implemented by support destructors/finalizers in the Dart language but given we don't want to encourage widespread use of destructors as part of normal object lifecycles, supporting via an api like FinalizationRegistry seems cleaner.

The JS APIs with reified types added seems like a reasonable enough way to implement this barring a case that would make it inefficient to implement on the VM.

Strawman Dart API:

Reference TypeScript API:
https://github.com/microsoft/TypeScript/blob/master/lib/lib.esnext.weakref.d.ts

// This does not have a generic type T in JavaScript but does in TypeScript.
class WeakRef<T> { 
  T? deref();
}

 // This class does not have a generic type in JavaScript or TypeScript. The unregister token could also be given a type but that seems overkill.
class FinalizationRegistry<T, V> {
  FinalizationRegistry(void Function(V value) callback);
  void register(T target, V heldValue, {Object unregisterToken}); // made unregisterToken a named parameter.
  void unregister(Object unregisterToken object): void;
}

[mraleph]

Notes on the VM requirements for the finalization API.

When VM team was discussing finalizers in the context of FFI one of the main concerns we have spent time trying to address was around premature finalization. The problem can be illustrated by the following example:

/// Class Foo holds native [resource] and registers
/// its instances with a FinalizationRegistry which
/// destroys corresponding resources when instance
/// becomes unreachable.
class Foo {
  /// Native resource held by the wrapper - lifetime
  /// of the wrapper determines lifetime of the [_resource].
  final _resource;
  void methodSync() {
    // [this] might be reclaimed by GC after evaluating
    // [this.resource] because it is never used again
    // and not kept live
    useResource(this._resource, gc());
  }

  void methodAsync() async {
    // [this] might be reclaimed by GC after evaluating
    // [this.resource] because it is never used again
    // and not kept live
    useResource(this._resource, await gc());
  }
} 

We want to guarantee that it is always safe to interact with _resource within methods of Foo.

The problem in both methodSync and methodAsync above is that this._resource is evaluated before gc occurs and there is nothing else in the method bodies which guarantees liveness of the object pointed by this variable (as the variable itself is never accessed after this._resource is evaluated and thus can be considered dead by the optimizing compiler).

We think this lack of liveness guarantees makes rather hard to write reliable code.

This problem can be addressed in several ways:

1. Following ECMAScript specification we could specify that finalization callbacks are not allowed to interrupt execution of the synchronous code (see https://tc39.es/ecma262/2021/#sec-host-cleanup-finalization-registry). This would address the problem with methodSync, but methodAsync would still remain broken. Additionally this would prevent users from using FinalizationRegistry for automatically managing reclamation of native resources in their synchronous code - which seems to be a rather strong drawback.
2. We could extend dart:core library with an auxiliary function reachabilityFence(x) which does nothing but tells compiler to treat x as live at least until after the invocation of reachabilityFence(x). Developer would then have to correctly place reachability fences in their code, e.g. modify methodSync like so:

   void methodSync() {
     useResource(this._resource, gc());
     reachabilityFence(this);
   }

   This addresses the problem, but requires tedious manual work from developers.
3. We could introduce a marker interface Finalizable (name subject to discussion), which comes with the following guarantee:

   /// Marker interface for objects which can be placed in FinalizationRegistry.
   /// If a class implements this interface then within any method
   /// of that class or its subclasses the receiver object is guranteed to be kept 
   /// alive at least until the end of that method.  
   abstract class Finalizable {
   }
   
   abstract class FinalizationRegistry<T extends Finalizable, V> {
   }

   Note that FinalizationRegistry is restricted to only Finalizable objects.

VM team is strongly in favor of design number 3.

As @jacob314 has pointed out this design does not actually prevent developers from using FinalizationRegistries with non-Finalizable objects, because the following work-around is possible:

final finalizationToken = Expando<Finalizable>();

class _Token implements Finalizable {}

void addToRegistry<V>(FinalizationRegistry<Finalizable, V> r, Object o, V v) {
  finalizationToken[o] ??=  _Token();
  r.register(finalizationToken[o], v);
}

[jacob314]

What are the next steps to move forward with implementation on the VM and the Web. I'd like to use this functionality for leak detection tooling so I can warn about leaks without computing a snapshot. The current proposal of providing a Finalizable interface seems fine. If we later decide it is not needed, we can always relax the addToRegistry api to accept any type rather than just Finalizable.

[yjbanov]

Not all browsers support this so it would be nice if this could be feature-detectable. We use FinalizerRegistry with feature-detection through JS-interop in the Flutter Web Engine. It's working fine for us, but it's web-only and not very discoverable for the larger Flutter/Dart community.

dart:developer is probably not the best place for this, as this API is useful in production code, not just during development. It should be part of dart:core as it's a core language/runtime feature.

[natebosch]

@sigmundch @rakudrama - can you comment on the feasibility of implementing any of the above proposals in dart2js?

[sigmundch]

I think it's doable on the web. Obviously the easiest option for us is (1) since it's provided for us by the JS engines. I also think (3) may be doable.

To my surprise, dart2js today may be accidentally already ensuring the Finalizable constraints as defined in (3) above. We lower async methods to a single closure modeling the state machine for the entire async method. The closure captures the receiver, and in doing so, it keeps it alive until the closure is tossed after the entire async method completes.

I do have a question about API (3), though

@mraleph - can you clarify why you only need the liveness within instance methods of the receiver? As defined above it seems you are only concerned with retaining the receiver in the middle of a method within its class (subclasses), and I'm curious why wouldn't we need a similar guarantees within other async methods. For example:

class Foo implements Finalizable {
  final resource;
  ...
}

lastUse() async {
  var f = Foo();
  useResource(f.resource, await gc()); // last-use of f
}

Here dart2js will not capture f. We save resource in a captured local, but f is ephemeral wont be available after the await. Couldn't this lead us to a premature finalization?

In summary - I'd be fine adopting API (3) with the current definition, but if we need to generalize it further, I need to take a closer look to see how feasible it is to do it this Q. However, I'm also fine moving forward with a variant of (3) and document that the web may have unspecified behavior around async code at first.

@natebosch @lrhn - any thoughts on where the API should live? I share @yjbanov opinion that this should not be in dart:developer, since I expect this to be used in production as well. That said, I hesitate to add anything to dart:core.

[mraleph]

@sigmundch

@mraleph - can you clarify why you only need the liveness within instance methods of the receiver? As defined above it seems you are only concerned with retaining the receiver in the middle of a method within its class (subclasses), and I'm curious why wouldn't we need a similar guarantees within other async methods.

The assumption is that native resource is private to the wrapper and never leaks outside, so it can only be interacted with inside the method itself. I will update the code example above. We want to provide some safety and not universal safety - so that users can reason about the liveness of the wrappers (they never die while their methods are on the stack), but not provide any stronger guarantees than that. /cc @alexmarkov @dcharkes @mkustermann

[sigmundch]

Thanks, makes sense!

We are clear to go with approach (3) at this point.

[alexmarkov]

/cc @rmacnak-google @a-siva

[dcharkes]

This feature is also beneficial for dart:ffi use cases - it would allow us to have finalization mechanism without designing a custom one.

For cross referencing, once this is implemented, dart-lang/sdk#35770 is obsolete.

3. We could introduce a marker interface Finalizable (name subject to discussion), which comes with the following guarantee:

   /// Marker interface for objects which can be placed in FinalizationRegistry.
   /// If a class implements this interface then within any method
   /// of that class or its subclasses the receiver object is guranteed to be kept 
   /// alive at least until the end of that method.  
   abstract class Finalizable {
   }
   
   abstract class FinalizationRegistry<T extends Finalizable, V> {
   }

   Note that FinalizationRegistry is restricted to only Finalizable objects.

@mraleph what is V here? Should that have a specific function signature for finalization?

In my exploration with a Finalizable interface I ran into the case where I was using two objects that both implemented the Finalizable interface. This required either using double dispatch or a reachability fence (prototype NativeResource=Finalizable).

We could consider keeping the receiver and parameters that are a subtype of Finalizable alive. (That would be both the Utf8Resource and the DatabaseResource in method prepare in the prototype.) Alternatively, we should document the double-dispatch or manual reachability fence patterns.