[jni] Store and display stack trace of release point for debugging (#2851)

- Added `Jni.captureStackTraceOnRelease` which defaults to `false`. When this is
  set, the stack traces of the release points will be stored for `JObject`s to
  help debug `DoubleReleaseError` and `UseAfterReleaseError`s. This includes the
  points where `JObject`s have been registered to be released by an `arena` via
  `JObject.releaseBy`.
- Changed the behavior of `JObject.releasedBy`. It now does not throw a
  `DoubleReleaseError` if the object was manually released before the end of
  arena.

Author: HosseinYousefi

pkgs/jni/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.15.3-wip
+
+- Added `Jni.captureStackTraceOnRelease` which defaults to `false`. When this is
+  set, the stack traces of the release points will be stored for `JObject`s to
+  help debug `DoubleReleaseError` and `UseAfterReleaseError`s. This includes the
+  points where `JObject`s have been registered to be released by an `arena` via
+  `JObject.releaseBy`.
+- Changed the behavior of `JObject.releasedBy`. It now does not throw a
+  `DoubleReleaseError` if the object was manually released before the end of
+  arena.
+
 ## 0.15.2
 
 - Do not fail `flutter build` if JDK is not found for desktop.

pkgs/jni/ffigen.yaml

@@ -26,6 +26,9 @@ enums:
     'JniType': 'JniCallType'
     'jobjectRefType': 'JObjectRefType'
 functions:
+  rename:
+    'FindClass': 'JniFindClass'
+    'GetJavaVM': 'JniGetJavaVM'
   exclude:
     # Exclude init functions supposed to be defined in loaded DLL, not JNI
     - 'JNI_.*'

pkgs/jni/lib/src/errors.dart

@@ -11,17 +11,41 @@ import 'third_party/generated_bindings.dart';
 // TODO(#567): Add the fact that [JException] is now a [JObject] to the
 // CHANGELOG.
 
-final class UseAfterReleaseError extends StateError {
-  UseAfterReleaseError() : super('Use after release error');
+mixin _ExplainsRelease on StateError {
+  String? get releaseStackTrace;
+
+  @override
+  String toString() {
+    final sb = StringBuffer(super.toString());
+    if (releaseStackTrace != null) {
+      sb.write('\n');
+      sb.write(releaseStackTrace);
+    } else {
+      sb.writeln('\nTo see where the object was released, '
+          'set `Jni.captureStackTraceOnRelease = true`.');
+    }
+    return sb.toString();
+  }
+}
+
+final class UseAfterReleaseError extends StateError with _ExplainsRelease {
+  @override
+  final String? releaseStackTrace;
+
+  UseAfterReleaseError([this.releaseStackTrace])
+      : super('Use after release error');
 }
 
 // TODO(#567): Use NullPointerError once it's available.
 final class JNullError extends StateError {
   JNullError() : super('The reference was null');
 }
 
-final class DoubleReleaseError extends StateError {
-  DoubleReleaseError() : super('Double release error');
+final class DoubleReleaseError extends StateError with _ExplainsRelease {
+  @override
+  final String? releaseStackTrace;
+
+  DoubleReleaseError([this.releaseStackTrace]) : super('Double release error');
 }
 
 /// Represents JNI errors that might be returned by methods like `CreateJavaVM`.

pkgs/jni/lib/src/jni.dart

@@ -70,6 +70,18 @@ abstract final class Jni {
     }
   }
 
+  /// Whether to capture the stack trace when an object is released.
+  ///
+  /// This is useful for debugging [DoubleReleaseError] and
+  /// [UseAfterReleaseError].
+  ///
+  /// Defaults to `false`.
+  static bool get captureStackTraceOnRelease =>
+      _bindings.getCaptureStackTraceOnRelease() != 0;
+
+  static set captureStackTraceOnRelease(bool value) =>
+      _bindings.setCaptureStackTraceOnRelease(value ? 1 : 0);
+
   /// Spawn an instance of JVM using JNI. This method should be called at the
   /// beginning of the program with appropriate options, before other isolates
   /// are spawned.
@@ -170,15 +182,15 @@ abstract final class Jni {
 
   /// Returns pointer to current JNI JavaVM instance
   Pointer<JavaVM> getJavaVM() {
-    return _bindings.GetJavaVM();
+    return _bindings.JniGetJavaVM();
   }
 
   /// Finds the class from its [name].
   ///
   /// Uses the correct class loader on Android.
   /// Prefer this over `Jni.env.FindClass`.
   static JClassPtr findClass(String name) {
-    return using((arena) => _bindings.FindClass(name.toNativeChars(arena)))
+    return using((arena) => _bindings.JniFindClass(name.toNativeChars(arena)))
         .checkedClassRef;
   }
 
@@ -365,6 +377,14 @@ extension InternalJniExtension on Jni {
     return Jni._bindings.newBooleanFinalizableHandle(object, reference);
   }
 
+  static Dart_FinalizableHandle newStackTraceFinalizableHandle(
+    Object object,
+    Pointer<Char> reference,
+  ) {
+    ProtectedJniExtensions.ensureInitialized();
+    return Jni._bindings.newStackTraceFinalizableHandle(object, reference);
+  }
+
   static void deleteFinalizableHandle(
       Dart_FinalizableHandle finalizableHandle, Object object) {
     ProtectedJniExtensions.ensureInitialized();

pkgs/jni/lib/src/jobject.dart

@@ -210,7 +210,19 @@ class JObject {
   bool get isReleased => reference.isReleased;
 
   /// Registers this object to be released at the end of [arena]'s lifetime.
-  void releasedBy(Arena arena) => arena.onReleaseAll(release);
+  void releasedBy(Arena arena) {
+    assert(() {
+      if (Jni.captureStackTraceOnRelease && reference is JGlobalReference) {
+        (reference as JGlobalReference).registeredInArena();
+      }
+      return true;
+    }());
+    arena.onReleaseAll(() {
+      if (!isReleased) {
+        release();
+      }
+    });
+  }
 }
 
 extension JObjectUseExtension<T extends JObject?> on T {

pkgs/jni/lib/src/jreference.dart

@@ -83,33 +83,80 @@ final class JGlobalReference extends JReference {
   /// The finalizable handle that deletes [_JFinalizable.pointer].
   final Dart_FinalizableHandle _jobjectFinalizableHandle;
   final Pointer<Bool> _isReleased;
+  final Pointer<Pointer<Char>> _releasedStackTracePointer;
 
-  JGlobalReference._(
-      super.finalizable, this._jobjectFinalizableHandle, this._isReleased)
+  JGlobalReference._(super.finalizable, this._jobjectFinalizableHandle,
+      this._isReleased, this._releasedStackTracePointer)
       : super._();
 
   factory JGlobalReference(Pointer<Void> pointer) {
     final finalizable = _JFinalizable(pointer);
     final isReleased = calloc<Bool>();
+    var releasedStackTracePointer = nullptr.cast<Pointer<Char>>();
     final jobjectFinalizableHandle =
         InternalJniExtension.newJObjectFinalizableHandle(
             finalizable, finalizable.pointer, JObjectRefType.JNIGlobalRefType);
     InternalJniExtension.newBooleanFinalizableHandle(finalizable, isReleased);
-    return JGlobalReference._(
-        finalizable, jobjectFinalizableHandle, isReleased);
+    assert(() {
+      releasedStackTracePointer = calloc<Pointer<Char>>();
+      InternalJniExtension.newStackTraceFinalizableHandle(
+          finalizable, releasedStackTracePointer.cast());
+      return true;
+    }());
+    return JGlobalReference._(finalizable, jobjectFinalizableHandle, isReleased,
+        releasedStackTracePointer);
   }
 
   @override
   bool get isNull => pointer == nullptr;
 
+  @override
+  JObjectPtr get pointer {
+    if (isReleased) {
+      throw UseAfterReleaseError(_releasedStackTrace);
+    }
+    return _finalizable.pointer;
+  }
+
+  void _appendToStackTrace(String stackTrace) {
+    final previousStackTrace = _releasedStackTrace ?? '';
+    final nativeStr = '$previousStackTrace$stackTrace'.toNativeUtf8();
+    if (_releasedStackTracePointer != nullptr) {
+      malloc.free(_releasedStackTracePointer.value);
+    }
+    _releasedStackTracePointer.value = nativeStr.cast();
+  }
+
   @override
   void _setAsReleased() {
     if (isReleased) {
-      throw DoubleReleaseError();
+      throw DoubleReleaseError(_releasedStackTrace);
     }
     _isReleased.value = true;
     InternalJniExtension.deleteFinalizableHandle(
         _jobjectFinalizableHandle, _finalizable);
+    assert(() {
+      if (Jni.captureStackTraceOnRelease) {
+        _appendToStackTrace('Object was released at:\n${StackTrace.current}\n');
+      }
+      return true;
+    }());
+  }
+
+  @internal
+  void registeredInArena() {
+    if (Jni.captureStackTraceOnRelease) {
+      _appendToStackTrace(
+          'Object was registered to be released by an arena at:\n'
+          '${StackTrace.current}\n');
+    }
+  }
+
+  String? get _releasedStackTrace {
+    if (_releasedStackTracePointer.value != nullptr) {
+      return _releasedStackTracePointer.value.cast<Utf8>().toDartString();
+    }
+    return null;
   }
 
   @override