[ffigen] Cpp unique ptr ownership

pkgs/ffigen/lib/src/code_generator/cpp_class.dart

@@ -194,6 +194,17 @@ class $name implements $ffiPrefix.Finalizable {
     _activeFinalizerFn = null;
   }
 
+  /// Detaches the finalizer and invalidates this object, returning the
+  /// underlying C++ pointer.
+  ///
+  /// Throws a [StateError] if the object has already been disposed, or if
+  /// this object does not own the pointer.
+  $ptrVoid detachPointer() {
+    final rawPtr = _ptr;
+    releaseOwnership();
+    _ptr = $ffiPrefix.nullptr;
+    return rawPtr;
+  }
 ''');
 
     for (final ctor in constructors) {
@@ -202,22 +213,42 @@ class $name implements $ffiPrefix.Finalizable {
 
       final dartParams = dartParamList(ctor.parameters);
 
+      final ownedParams = ctor.parameters
+          .where((p) => p.type is CppUniquePtrType)
+          .toList();
+
       final localVars = LocalVariables(ctor.localScope);
+
+      final rawPtrVars = <String, String>{};
+      for (final p in ownedParams) {
+        rawPtrVars[p.name] = '_raw_${p.name}';
+      }
+
       final callArgs = ctor.parameters
-          .map(
-            (p) => p.type.convertDartTypeToFfiDartType(
+          .map((p) {
+            if (rawPtrVars.containsKey(p.name)) {
+              return rawPtrVars[p.name]!;
+            }
+            return p.type.convertDartTypeToFfiDartType(
               ctx,
               p.name,
               objCRetain: false,
               objCAutorelease: false,
               localVariables: localVars,
-            ),
-          )
+            );
+          })
           .join(', ');
 
+      final ownershipChecks = StringBuffer();
+      for (final p in ownedParams) {
+        final raw = rawPtrVars[p.name]!;
+        ownershipChecks.write('    final $raw = ${p.name}.detachPointer();\n');
+      }
+
       s.write('''
   factory $name($dartParams) {
     ${localVars.generateDeclarations()}
+    ${ownershipChecks.toString().trimLeft()}
     return $name.fromPointer($privateName($callArgs), takeOwnership: true);
   }
 ''');
@@ -228,18 +259,31 @@ class $name implements $ffiPrefix.Finalizable {
       final dartReturn = method.returnType.getDartType(ctx);
       final dartParams = dartParamList(method.parameters);
 
+      final ownedParams = method.parameters
+          .where((p) => p.type is CppUniquePtrType)
+          .toList();
+
       final localVars = LocalVariables(method.localScope);
+
+      final rawPtrVars = <String, String>{};
+      for (final p in ownedParams) {
+        rawPtrVars[p.name] = '_raw_${p.name}';
+      }
+
       final callArgs = [
         if (!method.isStatic) '_ptr',
-        ...method.parameters.map(
-          (p) => p.type.convertDartTypeToFfiDartType(
+        ...method.parameters.map((p) {
+          if (rawPtrVars.containsKey(p.name)) {
+            return rawPtrVars[p.name]!;
+          }
+          return p.type.convertDartTypeToFfiDartType(
             ctx,
             p.name,
             objCRetain: false,
             objCAutorelease: false,
             localVariables: localVars,
-          ),
-        ),
+          );
+        }),
       ].join(', ');
       final decls = localVars.generateDeclarations();
 
@@ -249,21 +293,38 @@ class $name implements $ffiPrefix.Finalizable {
         objCRetain: false,
       );
 
+      // Build the ownership-transfer preamble for owned parameters.
+      final ownershipChecks = StringBuffer();
+      for (final p in ownedParams) {
+        final raw = rawPtrVars[p.name]!;
+        ownershipChecks.write('    final $raw = ${p.name}.detachPointer();\n');
+      }
+
+      final hasReturn = method.returnType != voidType;
+
       if (method.isStatic) {
+        final callLine = hasReturn
+            ? 'return $returnExpr;'
+            : '$glue($callArgs);';
         s.write('''\
   static $dartReturn ${method.originalName}($dartParams) {
     $decls
-    return $returnExpr;
+    ${ownershipChecks.toString().trimLeft()}
+    $callLine
   }
 ''');
       } else {
+        final callLine = hasReturn
+            ? 'return $returnExpr;'
+            : '$glue($callArgs);';
         s.write('''\
   $dartReturn ${method.originalName}($dartParams) {
     if (_ptr == $ffiPrefix.nullptr) {
       throw StateError('This object has already been disposed.');
     }
     $decls
-    return $returnExpr;
+    ${ownershipChecks.toString().trimLeft()}
+    $callLine
   }
 ''');
       }
@@ -365,12 +426,13 @@ FFIGEN_EXPORT void ${name}_delete($originalName* self) {
     final methodBindings = methods
         .map((method) {
           final symbol = method.name.name;
-          final callArgs = method.parameters.map((p) => p.name).join(', ');
 
           final String returnTypeString;
           final String params;
           final String body;
 
+          final callArgs = method.parameters.map(_cppCallArg).join(', ');
+
           if (method.isConstructor) {
             returnTypeString = '$originalName*';
             params = method.parameters.map(paramDecl).join(', ');
@@ -396,7 +458,11 @@ FFIGEN_EXPORT void ${name}_delete($originalName* self) {
                 selfType = originalName;
               }
               params = ['$selfType* self', ...otherParams].join(', ');
-              body = '${returnPrefix}self->${method.originalName}($callArgs);';
+              final methodName = method.originalName;
+              final suffix = method.returnType is CppUniquePtrType
+                  ? '.release()'
+                  : '';
+              body = '${returnPrefix}self->$methodName($callArgs)$suffix;';
             }
           }
 
@@ -436,3 +502,12 @@ FFIGEN_EXPORT $returnTypeString $symbol($params) {
     visitor.visit(ffiImport);
   }
 }
+
+String _cppCallArg(Parameter p) {
+  final type = p.type;
+  if (type is CppUniquePtrType) {
+    final className = type.cppClass.originalName;
+    return 'std::unique_ptr<$className>(${p.name})';
+  }
+  return p.name;
+}

pkgs/ffigen/lib/src/code_generator/pointer.dart

@@ -255,8 +255,6 @@ class ObjCObjectPointerWithProtocols extends ObjCObjectPointer {
 }
 
 /// A pointer to a C++ class wrapper object.
-/// Returned pointers are always unowned by default. The developer must call
-/// `retainOwnership()` explicitly if ownership has been transferred.
 class CppClassPointerType extends PointerType {
   final CppClass cppClass;
 
@@ -314,3 +312,22 @@ class CppClassPointerType extends PointerType {
     visitor.visit(ffiImport);
   }
 }
+
+/// A type representing `std::unique_ptr<T>` ownership transfer.
+class CppUniquePtrType extends CppClassPointerType {
+  CppUniquePtrType(super.cppClass);
+
+  @override
+  String convertFfiDartTypeToDartType(
+    Context context,
+    String value, {
+    required bool objCRetain,
+    String? objCEnclosingClass,
+  }) => '${cppClass.name}.fromPointer($value, takeOwnership: true)';
+
+  @override
+  String toString() => 'unique_ptr<${cppClass.name}>';
+
+  @override
+  String cacheKey() => 'unique_ptr<${cppClass.cacheKey()}>';
+}

pkgs/ffigen/lib/src/code_generator/writer.dart

@@ -419,6 +419,7 @@ id objc_retainBlock(id);
   String? generateCpp(String outFilename) {
     final s = StringBuffer();
     final outDir = p.dirname(outFilename);
+    s.write('#include <memory>\n');
     // Emit each entry-point header exactly once.
     for (final header in context.config.headers.entryPoints) {
       s.write('#include "${p.relative(header.toFilePath(), from: outDir)}"\n');

pkgs/ffigen/lib/src/header_parser/clang_bindings/clang_bindings.dart

@@ -470,6 +470,19 @@ class Clang {
   late final _clang_Type_getNumObjCProtocolRefs =
       _clang_Type_getNumObjCProtocolRefsPtr.asFunction<int Function(CXType)>();
 
+  /// Returns the number of template arguments for given template
+  /// specialization, or -1 if type \c T is not a template specialization.
+  int clang_Type_getNumTemplateArguments(CXType T) {
+    return _clang_Type_getNumTemplateArguments(T);
+  }
+
+  late final _clang_Type_getNumTemplateArgumentsPtr =
+      _lookup<ffi.NativeFunction<ffi.Int Function(CXType)>>(
+        'clang_Type_getNumTemplateArguments',
+      );
+  late final _clang_Type_getNumTemplateArguments =
+      _clang_Type_getNumTemplateArgumentsPtr.asFunction<int Function(CXType)>();
+
   /// Retrieves the base type of the ObjCObjectType.
   ///
   /// If the type is not an ObjC object, an invalid type is returned.
@@ -501,6 +514,23 @@ class Clang {
       _clang_Type_getObjCProtocolDeclPtr
           .asFunction<CXCursor Function(CXType, int)>();
 
+  /// Returns the type template argument of a template class specialization
+  /// at given index.
+  ///
+  /// This function only returns template type arguments and does not handle
+  /// template template arguments or variadic packs.
+  CXType clang_Type_getTemplateArgumentAsType(CXType T, int i) {
+    return _clang_Type_getTemplateArgumentAsType(T, i);
+  }
+
+  late final _clang_Type_getTemplateArgumentAsTypePtr =
+      _lookup<ffi.NativeFunction<CXType Function(CXType, ffi.UnsignedInt)>>(
+        'clang_Type_getTemplateArgumentAsType',
+      );
+  late final _clang_Type_getTemplateArgumentAsType =
+      _clang_Type_getTemplateArgumentAsTypePtr
+          .asFunction<CXType Function(CXType, int)>();
+
   /// Provides a shared context for creating translation units.
   ///
   /// It provides two options:

pkgs/ffigen/lib/src/header_parser/type_extractor/extractor.dart

@@ -43,6 +43,27 @@ Type getCodeGenType(
     return getCodeGenType(context, clang.clang_Type_getNamedType(cxtype));
   }
 
+  // Handle C++ templates like std::unique_ptr.
+  if (context.config.cpp?.classes != null) {
+    final numTemplateArgs = clang.clang_Type_getNumTemplateArguments(cxtype);
+    if (numTemplateArgs >= 1) {
+      final declCursor = clang.clang_getTypeDeclaration(cxtype);
+      final usr = clang.clang_getCursorUSR(declCursor).toStringAndDispose();
+      final isStdUniquePtr = usr.contains('std@') && usr.contains('unique_ptr');
+      if (isStdUniquePtr) {
+        final spelling = clang
+            .clang_getTypeSpelling(cxtype)
+            .toStringAndDispose();
+        return _extractUniquePtrType(
+          context,
+          cxtype,
+          numTemplateArgs,
+          spelling,
+        );
+      }
+    }
+  }
+
   // These basic Objective C types skip the cache, and are conditional on the
   // language flag.
   if (context.config.objectiveC != null) {
@@ -287,6 +308,41 @@ Type? _extractfromRecord(
   return UnimplementedType('${cxtype.kindSpelling()} not implemented');
 }
 
+Type _extractUniquePtrType(
+  Context context,
+  clang_types.CXType cxtype,
+  int numTemplateArgs,
+  String spelling,
+) {
+  final logger = context.logger;
+
+  if (numTemplateArgs != 1) {
+    logger.warning(
+      'std::unique_ptr with a custom deleter is not supported '
+      '($numTemplateArgs template args in "$spelling"). Skipping.',
+    );
+    return UnimplementedType('unique_ptr with custom deleter not supported');
+  }
+
+  final innerCXType = clang.clang_Type_getTemplateArgumentAsType(cxtype, 0);
+  final innerType = getCodeGenType(context, innerCXType);
+
+  if (innerType is CppClass) {
+    logger.fine(
+      '  unique_ptr<${innerType.originalName}> is an owned CppUniquePtrType',
+    );
+    return CppUniquePtrType(innerType);
+  }
+
+  logger.warning(
+    'std::unique_ptr inner type is not a known C++ class '
+    '(got ${innerType.runtimeType} from "$spelling"). Skipping.',
+  );
+  return UnimplementedType(
+    'unique_ptr inner type is not a supported C++ class',
+  );
+}
+
 // Used for function pointer arguments.
 Type _extractFromFunctionProto(
   Context context,

pkgs/ffigen/test/native_cpp_test/cpp_class_test_bindings.dart

@@ -89,6 +89,18 @@ class Animal implements ffi.Finalizable {
     _activeFinalizerFn = null;
   }
 
+  /// Detaches the finalizer and invalidates this object, returning the
+  /// underlying C++ pointer.
+  ///
+  /// Throws a [StateError] if the object has already been disposed, or if
+  /// this object does not own the pointer.
+  ffi.Pointer<ffi.Void> detachPointer() {
+    final rawPtr = _ptr;
+    releaseOwnership();
+    _ptr = ffi.nullptr;
+    return rawPtr;
+  }
+
   factory Animal(int age) {
     return Animal.fromPointer(_Animal_new(age), takeOwnership: true);
   }
@@ -97,7 +109,7 @@ class Animal implements ffi.Finalizable {
       throw StateError('This object has already been disposed.');
     }
 
-    return _Animal_speak(_ptr);
+    _Animal_speak(_ptr);
   }
 
   int getAge() {
@@ -113,11 +125,11 @@ class Animal implements ffi.Finalizable {
   }
 
   static void Animal_new() {
-    return _Animal_Animal_new();
+    _Animal_Animal_new();
   }
 
   static void Animal_delete() {
-    return _Animal_Animal_delete();
+    _Animal_Animal_delete();
   }
 
   bool isMammalClass() {
@@ -296,6 +308,18 @@ class FinalizerTestSubject implements ffi.Finalizable {
     _activeFinalizerFn = null;
   }
 
+  /// Detaches the finalizer and invalidates this object, returning the
+  /// underlying C++ pointer.
+  ///
+  /// Throws a [StateError] if the object has already been disposed, or if
+  /// this object does not own the pointer.
+  ffi.Pointer<ffi.Void> detachPointer() {
+    final rawPtr = _ptr;
+    releaseOwnership();
+    _ptr = ffi.nullptr;
+    return rawPtr;
+  }
+
   factory FinalizerTestSubject(ffi.Pointer<ffi.Int> counter) {
     return FinalizerTestSubject.fromPointer(
       _FinalizerTestSubject_new(counter),