[objective_c] Add autoReleasePool API (#2658)

Author: liamappelbe

pkgs/objective_c/CHANGELOG.md

@@ -4,6 +4,7 @@
 - Fix missing `NSNumber` category includes in iOS and macOS `objective_c.m`
   files.
 - Add `NSBundle` and `NSNull` to the bindings.
+- Add `autoReleasePool` function.
 - Fix a [bug](https://github.com/dart-lang/native/issues/2627) where
   `NSMutableDictionary.of` returned a `NSDictionary`.
 

pkgs/objective_c/ffigen_c.yaml

@@ -48,6 +48,8 @@ functions:
     'object_getClass': 'getObjectClass'
     'objc_copyClassList': 'copyClassList'
     'objc_getProtocol': 'getProtocol'
+    'objc_autoreleasePoolPush': 'autoreleasePoolPush'
+    'objc_autoreleasePoolPop': 'autoreleasePoolPop'
     'protocol_getMethodDescription': 'getMethodDescription'
     'protocol_getName': 'getProtocolName'
 globals:

pkgs/objective_c/lib/objective_c.dart

@@ -3,6 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 export 'package:pub_semver/pub_semver.dart' show Version;
+export 'src/autorelease.dart';
 export 'src/block.dart';
 export 'src/c_bindings_generated.dart'
     show

pkgs/objective_c/lib/src/autorelease.dart

@@ -0,0 +1,45 @@
+// Copyright (c) 2025, 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.
+
+import 'c_bindings_generated.dart';
+
+/// Creates an Objective-C autorelease pool, runs [function], then releases the
+/// pool.
+///
+/// ```
+/// while (longRunningCondiditon) {
+///   // When writing ObjC interop code inside a long running loop, it's a good
+///   // idea to use an autorelease pool to clean up autoreleased references.
+///   autoReleasePool(() {
+///     // Interacting with most ObjC APIs autoreleases a lot of internal refs.
+///     final someObjCObject = fooObjCApi.loadNextObject();
+///     someObjCObject.greet('Hello'.toNSString());
+///     barObjCApi.sendObject(someObjCObject);
+///   });
+/// }
+/// ```
+///
+/// This is analogous to the Objective-C `@autoreleasepool` block:
+/// ```
+/// while (longRunningCondiditon) {
+///   @autoreleasepool {
+///     SomeObjCObject *someObjCObject = [fooObjCApi loadNextObject];
+///     [someObjCObject greet:@"Hello"];
+///     [barObjCApi sendObject:someObjCObject];
+///   }
+/// }
+/// ```
+///
+/// [function] is executed synchronously. Do not try to pass an async function
+/// here (the [Future] it returns will not be awaited). Objective-C autorelease
+/// pools form a strict stack, and allowing async execution gaps inside the pool
+/// scope could easily break this nesting, so async functions are not supported.
+void autoReleasePool(void Function() function) {
+  final pool = autoreleasePoolPush();
+  try {
+    function();
+  } finally {
+    autoreleasePoolPop(pool);
+  }
+}

pkgs/objective_c/lib/src/c_bindings_generated.dart

@@ -42,6 +42,18 @@ external ffi.Array<ffi.Pointer<ffi.Void>> NSConcreteMallocBlock;
 @ffi.Native<ffi.Array<ffi.Pointer<ffi.Void>>>(symbol: '_NSConcreteStackBlock')
 external ffi.Array<ffi.Pointer<ffi.Void>> NSConcreteStackBlock;
 
+@ffi.Native<ffi.Void Function(ffi.Pointer<ffi.Void>)>(
+  symbol: 'objc_autoreleasePoolPop',
+  isLeaf: true,
+)
+external void autoreleasePoolPop(ffi.Pointer<ffi.Void> pool);
+
+@ffi.Native<ffi.Pointer<ffi.Void> Function()>(
+  symbol: 'objc_autoreleasePoolPush',
+  isLeaf: true,
+)
+external ffi.Pointer<ffi.Void> autoreleasePoolPush();
+
 @ffi.Native<ffi.Void Function(ffi.Pointer<ffi.Void>)>(
   symbol: 'DOBJC_awaitWaiter',
 )

pkgs/objective_c/lib/src/ns_input_stream.dart

@@ -6,18 +6,6 @@ import '../objective_c.dart';
 
 import 'objective_c_bindings_generated.dart';
 
-@Native<Pointer<Void> Function()>(
-  isLeaf: true,
-  symbol: 'objc_autoreleasePoolPush',
-)
-external Pointer<Void> _autoreleasePoolPush();
-
-@Native<Void Function(Pointer<Void>)>(
-  isLeaf: true,
-  symbol: 'objc_autoreleasePoolPop',
-)
-external void _autoreleasePoolPop(Pointer<Void> pool);
-
 extension NSInputStreamStreamExtension on Stream<List<int>> {
   /// Return a [NSInputStream] that, when read, will contain the contents of
   /// the [Stream].
@@ -46,25 +34,22 @@ extension NSInputStreamStreamExtension on Stream<List<int>> {
 
     final port = ReceivePort();
 
-    final DartInputStreamAdapter inputStream;
-    final DartInputStreamAdapterWeakHolder weakInputStream;
+    late final DartInputStreamAdapter inputStream;
+    late final DartInputStreamAdapterWeakHolder weakInputStream;
 
     // Only hold a weak reference to the returned `inputStream` so that there is
     // no unbreakable reference cycle between Dart and Objective-C. When the
     // `inputStream`'s `dealloc` method is called then it sends this code a
     // message saying that it was closed.
-    final pool = _autoreleasePoolPush();
-    try {
+    autoReleasePool(() {
       inputStream = DartInputStreamAdapter.inputStreamWithPort(
         port.sendPort.nativePort,
       );
       weakInputStream =
           DartInputStreamAdapterWeakHolder.holderWithInputStreamAdapter(
             inputStream,
           );
-    } finally {
-      _autoreleasePoolPop(pool);
-    }
+    });
 
     late final StreamSubscription<dynamic> dataSubscription;
 

pkgs/objective_c/src/objective_c_runtime.h

@@ -24,6 +24,8 @@ void objc_release(ObjCObject *object);
 ObjCObject *objc_autorelease(ObjCObject *object);
 ObjCObject *object_getClass(ObjCObject *object);
 ObjCObject** objc_copyClassList(unsigned int* count);
+void *objc_autoreleasePoolPush(void);
+void objc_autoreleasePoolPop(void *pool);
 
 // The signature of this function is just a placeholder. This function is used
 // by every method invocation, and is cast to every signature we need.

pkgs/objective_c/test/autorelease_test.dart

@@ -0,0 +1,63 @@
+// Copyright (c) 2025, 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.
+
+// Objective C support is only available on mac.
+@TestOn('mac-os')
+library;
+
+import 'dart:ffi';
+
+import 'package:objective_c/objective_c.dart';
+import 'package:test/test.dart';
+
+import 'util.dart';
+
+void main() {
+  group('autoReleasePool', () {
+    setUpAll(() {
+      // TODO(https://github.com/dart-lang/native/issues/1068): Remove this.
+      DynamicLibrary.open(testDylib);
+    });
+
+    test('basics', () async {
+      late Pointer<ObjCObject> pointer;
+      autoReleasePool(() {
+        {
+          final object = NSObject();
+          pointer = object.ref.autorelease();
+        }
+        doGC();
+        expect(objectRetainCount(pointer), greaterThan(0));
+      });
+
+      doGC();
+      await Future<void>.delayed(Duration.zero);
+      doGC();
+
+      expect(objectRetainCount(pointer), 0);
+    });
+
+    test('exception safe', () async {
+      late Pointer<ObjCObject> pointer;
+      expect(
+        () => autoReleasePool(() {
+          {
+            final object = NSObject();
+            pointer = object.ref.autorelease();
+          }
+          doGC();
+          expect(objectRetainCount(pointer), greaterThan(0));
+          throw Exception();
+        }),
+        throwsException,
+      );
+
+      doGC();
+      await Future<void>.delayed(Duration.zero);
+      doGC();
+
+      expect(objectRetainCount(pointer), 0);
+    });
+  });
+}

pkgs/objective_c/test/ns_input_stream_test.dart

@@ -325,21 +325,23 @@ void main() {
         await completionPort.first;
       });
       test('with self delegate', () async {
-        final pool = autoreleasePoolPush();
-        DartInputStreamAdapter? inputStream =
-            Stream.fromIterable([
-                  [1, 2, 3],
-                ]).toNSInputStream()
-                as DartInputStreamAdapter;
-
-        expect(inputStream.delegate, inputStream);
-
-        final ptr = inputStream.ref.pointer;
-        autoreleasePoolPop(pool);
+        late DartInputStreamAdapter? inputStream;
+        late Pointer<ObjCObject> ptr;
+        autoReleasePool(() {
+          inputStream =
+              Stream.fromIterable([
+                    [1, 2, 3],
+                  ]).toNSInputStream()
+                  as DartInputStreamAdapter;
+
+          expect(inputStream!.delegate, inputStream);
+
+          ptr = inputStream!.ref.pointer;
+        });
         expect(objectRetainCount(ptr), greaterThan(0));
 
-        inputStream.open();
-        inputStream.close();
+        inputStream!.open();
+        inputStream!.close();
         inputStream = null;
 
         doGC();
@@ -350,22 +352,24 @@ void main() {
       });
 
       test('with non-self delegate', () async {
-        final pool = autoreleasePoolPush();
-        DartInputStreamAdapter? inputStream =
-            Stream.fromIterable([
-                  [1, 2, 3],
-                ]).toNSInputStream()
-                as DartInputStreamAdapter;
-
-        inputStream.delegate = NSStreamDelegate.castFrom(NSObject());
-        expect(inputStream.delegate, isNot(inputStream));
-
-        final ptr = inputStream.ref.pointer;
-        autoreleasePoolPop(pool);
+        late DartInputStreamAdapter? inputStream;
+        late Pointer<ObjCObject> ptr;
+        autoReleasePool(() {
+          inputStream =
+              Stream.fromIterable([
+                    [1, 2, 3],
+                  ]).toNSInputStream()
+                  as DartInputStreamAdapter;
+
+          inputStream!.delegate = NSStreamDelegate.castFrom(NSObject());
+          expect(inputStream!.delegate, isNot(inputStream));
+
+          ptr = inputStream!.ref.pointer;
+        });
         expect(objectRetainCount(ptr), greaterThan(0));
 
-        inputStream.open();
-        inputStream.close();
+        inputStream!.open();
+        inputStream!.close();
         inputStream = null;
 
         doGC();