Use NonNull for C++ references

- Make feature disabled by default until usability concerns are resolved.
- Add test for --nonnull-references argument

Signed-off-by: Tin Švagelj <[email protected]>

Author: Caellian

bindgen-tests/tests/expectations/tests/references.rs

@@ -0,0 +1,17 @@
+// bindgen-flags: --nonnull-references
+
+struct Container {
+  int *normalPointer;
+  const int *constPointer;
+  int &normalRef;
+  const int &constRef;
+  int *&pointerRef;
+  const int *&constPointerRef;
+};
+
+int &refReturningFunction();
+
+void functionConsumingRef(int &someRef, float normalArgument,
+                          const int &constRef);
+
+void functionConsumingPointerRef(int* &pointerRef);

bindgen-tests/tests/headers/references.hpp

@@ -4384,6 +4384,12 @@ impl TryToRustTy for Type {
                 if inner_ty.canonical_type(ctx).is_function() || is_objc_pointer
                 {
                     Ok(ty)
+                } else if ctx.options().generate_cxx_nonnull_references
+                    && matches!(self.kind(), TypeKind::Reference(_))
+                {
+                    // It's UB to pass null values in place of C++ references
+                    let prefix = ctx.trait_prefix();
+                    Ok(syn::parse_quote! { ::#prefix::ptr::NonNull<#ty> })
                 } else {
                     Ok(ty.to_ptr(is_const))
                 }

bindgen/codegen/mod.rs

@@ -258,6 +258,9 @@ struct BindgenCommand {
     /// Use extern crate instead of use for objc.
     #[arg(long)]
     objc_extern_crate: bool,
+    /// Use `NonNull` in place of raw pointer for C++ references.
+    #[arg(long)]
+    nonnull_references: bool,
     /// Generate block signatures instead of void pointers.
     #[arg(long)]
     generate_block: bool,
@@ -590,6 +593,7 @@ where
         no_doc_comments,
         no_recursive_allowlist,
         objc_extern_crate,
+        nonnull_references,
         generate_block,
         generate_cstr,
         block_extern_crate,
@@ -921,6 +925,7 @@ where
             no_doc_comments => |b, _| b.generate_comments(false),
             no_recursive_allowlist => |b, _| b.allowlist_recursively(false),
             objc_extern_crate,
+            nonnull_references => |b, _| b.generate_cxx_nonnull_references(true),
             generate_block,
             generate_cstr,
             block_extern_crate,

bindgen/options/cli.rs

@@ -1474,6 +1474,26 @@ options! {
         },
         as_args: |value, args| (!value).as_args(args, "--no-doc-comments"),
     },
+    /// Whether to generate [`NonNull`] pointers for C++ references.
+    ///
+    /// [`NonNull`]: core::ptr::NonNull
+    generate_cxx_nonnull_references: bool {
+        default: false,
+        methods: {
+            /// Generate `NonNull` pointers in place of raw pointers for C++
+            /// references.
+            ///
+            /// This option is disabled by default:
+            ///
+            /// Enabling it erases information about constness in generated
+            /// code, and `NonNull` is more cumbersome to use than raw pointers.
+            pub fn generate_cxx_nonnull_references(mut self, doit: bool) -> Self {
+                self.options.generate_cxx_nonnull_references = doit;
+                self
+            }
+        },
+        as_args: |value, args| value.as_args(args, "--nonnull-references"),
+    },
     /// Whether to generate inline functions.
     generate_inline_functions: bool {
         methods: {