[vm/ffi] Example with deeply-immutable Finalizable and dart_api_dl

A test exercising isolate group finalizers with `Finalizable` and
`pragma('vm:deeply-immutable')`.

Note that we cannot fully do without C code due to the signature of
`Dart_HandleFinalizer` which also passes a
`void* isolate_callback_data` in addition to the peer.

TEST=tests/ffi/deeply_immutable_c_api_finalizer_test.dart

Bug: #55062
Bug: #55120
Change-Id: Ibaf4899ca678ffb0c5d227ac4f10deb38d49fe6f
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/356720
Reviewed-by: Martin Kustermann <[email protected]>
Reviewed-by: Hossein Yousefi <[email protected]>
Commit-Queue: Daco Harkes <[email protected]>

Author: dcharkes

runtime/bin/ffi_test/ffi_test_functions_vmspecific.cc

@@ -617,7 +617,7 @@ DART_EXPORT void ExecuteCallback(Work* work_ptr) {
 
 Dart_Port send_port_;
 
-static void FreeFinalizer(void*, void* value) {
+DART_EXPORT void FreeFinalizer(void*, void* value) {
   free(value);
 }
 

tests/ffi/deeply_immutable_c_api_finalizer_test.dart

@@ -0,0 +1,114 @@
+// Copyright (c) 2024, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+// SharedObjects=ffi_test_functions
+
+import 'dart:async';
+import 'dart:ffi';
+import 'dart:isolate';
+
+import 'package:ffi/ffi.dart';
+
+import 'dylib_utils.dart';
+
+void main() async {
+  final myFinalizable2 = await Isolate.run(() => MyFinalizable());
+  print(myFinalizable2);
+  print(myFinalizable2.pointer);
+  // This would crash if a NativeFinalizer would have been attached and run
+  // eagerly on `Isolate.exit`.
+  print(myFinalizable2.pointer.value);
+}
+
+@pragma('vm:deeply-immutable')
+final class MyFinalizable implements Finalizable {
+  final Pointer<Int> pointer;
+
+  MyFinalizable._(this.pointer);
+
+  factory MyFinalizable() {
+    final pointer = calloc<Int>(10);
+    pointer.value = 123;
+    final result = MyFinalizable._(pointer);
+    newFinalizableHandle(
+      result,
+      pointer.cast(),
+      0,
+      freeFinalizer, // Not the signature of `free`!
+    );
+    return result;
+  }
+}
+
+final freeFinalizer = dlopenPlatformSpecific("ffi_test_functions")
+    .lookup<NativeFunction<Dart_HandleFinalizerFunction>>('FreeFinalizer');
+
+final Dart_FinalizableHandle Function(
+  Object,
+  Pointer<Void>,
+  int,
+  Dart_HandleFinalizer,
+) newFinalizableHandle = _findDartApiFunction('Dart_NewFinalizableHandle')
+    .cast<
+        NativeFunction<
+            Dart_FinalizableHandle Function(
+              Handle,
+              Pointer<Void>,
+              IntPtr,
+              Dart_HandleFinalizer,
+            )>>()
+    .asFunction();
+
+final void Function(
+  Dart_FinalizableHandle,
+  Object,
+) deleteFinalizableHandle = _findDartApiFunction('Dart_DeleteFinalizableHandle')
+    .cast<
+        NativeFunction<
+            Void Function(
+              Dart_FinalizableHandle,
+              Handle,
+            )>>()
+    .asFunction();
+
+Pointer<Void> _findDartApiFunction(String name) {
+  final dartApi = NativeApi.initializeApiDLData.cast<DartApi>();
+  var entry = dartApi.ref.functions;
+  while (true) {
+    final entryName = entry.ref.name.cast<Utf8>().toDartString();
+    if (entryName == name) {
+      return entry.ref.function;
+    }
+    if (name == 'Dart_Null') {
+      throw StateError('Dart API function with $name not found.');
+    }
+    entry++;
+  }
+}
+
+final class DartApi extends Struct {
+  @Int()
+  external int major;
+
+  @Int()
+  external int minor;
+
+  external Pointer<DartApiEntry> functions;
+}
+
+final class DartApiEntry extends Struct {
+  external Pointer<Char> name;
+
+  external Pointer<Void> function;
+}
+
+final class _Dart_FinalizableHandle extends Opaque {}
+
+typedef Dart_HandleFinalizer
+    = Pointer<NativeFunction<Dart_HandleFinalizerFunction>>;
+typedef Dart_HandleFinalizerFunction = Void Function(
+    Pointer<Void> isolate_callback_data, Pointer<Void> peer);
+typedef DartDart_HandleFinalizerFunction = void Function(
+    Pointer<Void> isolate_callback_data, Pointer<Void> peer);
+typedef Dart_FinalizableHandle = Pointer<_Dart_FinalizableHandle>;