Use Gd::null_arg(), consistent with Variant::nil()

Author: Bromeon

godot-core/src/builtin/variant/mod.rs

@@ -29,6 +29,9 @@ pub struct Variant {
 
 impl Variant {
     /// Create an empty variant (`null` value in GDScript).
+    ///
+    /// If a Godot engine API accepts object (not variant) parameters and you'd like to pass `null`, use
+    /// [`Gd::null_arg()`][crate::obj::Gd::null_arg] instead.
     pub fn nil() -> Self {
         Self::default()
     }

godot-core/src/obj/gd.rs

@@ -31,8 +31,8 @@ use crate::{classes, out};
 /// This smart pointer can only hold _objects_ in the Godot sense: instances of Godot classes (`Node`, `RefCounted`, etc.)
 /// or user-declared structs (declared with `#[derive(GodotClass)]`). It does **not** hold built-in types (`Vector3`, `Color`, `i32`).
 ///
-/// `Gd<T>` never holds null objects. If you need nullability, use `Option<Gd<T>>`. To pass null objects to engine APIs, use
-/// [`NullArg`][crate::obj::NullArg].
+/// `Gd<T>` never holds null objects. If you need nullability, use `Option<Gd<T>>`. To pass null objects to engine APIs, you can
+/// additionally use [`Gd::null_arg()`] as a shorthand.
 ///
 /// # Memory management
 ///
@@ -466,26 +466,7 @@ impl<T: GodotClass> Gd<T> {
     {
         self.raw.script_sys()
     }
-}
-
-impl<T: GodotClass> Deref for Gd<T> {
-    // Target is always an engine class:
-    // * if T is an engine class => T
-    // * if T is a user class => T::Base
-    type Target = GdDerefTarget<T>;
 
-    fn deref(&self) -> &Self::Target {
-        self.raw.as_target()
-    }
-}
-
-impl<T: GodotClass> DerefMut for Gd<T> {
-    fn deref_mut(&mut self) -> &mut Self::Target {
-        self.raw.as_target_mut()
-    }
-}
-
-impl<T: GodotClass> Gd<T> {
     /// Runs `init_fn` on the address of a pointer (initialized to null). If that pointer is still null after the `init_fn` call,
     /// then `None` will be returned; otherwise `Gd::from_obj_sys(ptr)`.
     ///
@@ -635,9 +616,56 @@ where
     }
 }
 
+impl<T> Gd<T>
+where
+    T: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
+{
+    /// Represents `null` when passing an object argument to Godot.
+    ///
+    /// This expression is only intended for function argument lists. It can be used whenever a Godot signature accepts
+    /// [`AsObjectArg<T>`][crate::obj::AsObjectArg]. `Gd::null_arg()` as an argument is equivalent to `Option::<Gd<T>>::None`, but less wordy.
+    ///
+    /// To work with objects that can be null, use `Option<Gd<T>>` instead. For APIs that accept `Variant`, you can pass [`Variant::nil()`].
+    ///
+    /// # Nullability
+    /// <div class="warning">
+    /// The GDExtension API does not inform about nullability of its function parameters. It is up to you to verify that the arguments you pass
+    /// are only null when this is allowed. Doing this wrong should be safe, but can lead to the function call failing.
+    /// </div>
+    ///
+    /// # Example
+    /// ```no_run
+    /// # fn some_shape() -> Gd<GltfPhysicsShape> { unimplemented!() }
+    /// use godot::prelude::*;
+    /// use godot::classes::GltfPhysicsShape;
+    ///
+    /// let mut shape: Gd<GltfPhysicsShape> = some_shape();
+    /// shape.set_importer_mesh(Gd::null_arg());
+    pub fn null_arg() -> crate::obj::ObjectNullArg<T> {
+        crate::obj::ObjectNullArg(std::marker::PhantomData)
+    }
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Trait impls
 
+impl<T: GodotClass> Deref for Gd<T> {
+    // Target is always an engine class:
+    // * if T is an engine class => T
+    // * if T is a user class => T::Base
+    type Target = GdDerefTarget<T>;
+
+    fn deref(&self) -> &Self::Target {
+        self.raw.as_target()
+    }
+}
+
+impl<T: GodotClass> DerefMut for Gd<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        self.raw.as_target_mut()
+    }
+}
+
 impl<T: GodotClass> GodotConvert for Gd<T> {
     type Via = Gd<T>;
 }

godot-core/src/obj/mod.rs

@@ -11,22 +11,22 @@
 //! * [`GodotClass`], which is implemented for every class that Godot can work with (either engine- or user-provided).
 //! * [`Gd`], a smart pointer that manages instances of Godot classes.
 
-mod as_object_arg;
 mod base;
 mod gd;
 mod guards;
 mod instance_id;
+mod object_arg;
 mod onready;
 mod raw_gd;
 mod traits;
 
 pub(crate) mod rtti;
 
-pub use as_object_arg::*;
 pub use base::*;
 pub use gd::*;
 pub use guards::{BaseMut, BaseRef, GdMut, GdRef};
 pub use instance_id::*;
+pub use object_arg::*;
 pub use onready::*;
 pub use raw_gd::*;
 pub use traits::*;

godot-core/src/obj/as_object_arg.rs renamed to godot-core/src/obj/object_arg.rs

@@ -18,7 +18,7 @@ use std::ptr;
 /// This trait is implemented for the following types:
 /// - [`Gd<T>`] and `&Gd<T>`, to pass objects. Subclasses of `T` are explicitly supported.
 /// - [`Option<Gd<T>>`] and `Option<&Gd<T>>`, to pass optional objects. `None` is mapped to a null argument.
-/// - [`NullArg`], to pass `null` arguments without using `Option`.
+/// - [`Gd::null_arg()`], to pass `null` arguments without using `Option`.
 ///
 /// # Nullability
 /// <div class="warning">
@@ -49,7 +49,9 @@ where
     U: Inherits<T>,
 {
     fn as_object_arg(&self) -> ObjectArg<T> {
-        ObjectArg::from_raw_gd(&self.raw)
+        // SAFETY: In the context where as_object_arg() is called (a Godot engine call), the original Gd is guaranteed to remain valid.
+        // This function is not part of the public API.
+        unsafe { ObjectArg::from_raw_gd(&self.raw) }
     }
 }
 
@@ -64,7 +66,7 @@ where
     }
 }
 
-impl<T> AsObjectArg<T> for NullArg
+impl<T> AsObjectArg<T> for ObjectNullArg<T>
 where
     T: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
 {
@@ -75,30 +77,8 @@ where
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-/// Represents `null` when passing an object argument to Godot.
-///
-/// This can be used whenever a Godot signature accepts [`AsObjectArg<T>`].
-/// Using `NullArg` is equivalent to passing `Option::<Gd<T>>::None`, but less wordy.
-///
-/// This expression is only intended for function argument lists. To work with objects that can be null, use `Option<Gd<T>>` instead.
-///
-/// For APIs that accept `Variant`, you can pass [`Variant::nil()`] instead.
-///
-/// # Nullability
-/// <div class="warning">
-/// The GDExtension API does not inform about nullability of its function parameters. It is up to you to verify that the arguments you pass
-/// are only null when this is allowed. Doing this wrong should be safe, but can lead to the function call failing.
-/// </div>
-///
-/// # Example
-/// ```no_run
-/// # fn some_shape() -> Gd<GltfPhysicsShape> { unimplemented!() }
-/// use godot::prelude::*;
-/// use godot_core::classes::GltfPhysicsShape;
-///
-/// let mut shape: Gd<GltfPhysicsShape> = some_shape();
-/// shape.set_importer_mesh(NullArg);
-pub struct NullArg;
+#[doc(hidden)]
+pub struct ObjectNullArg<T>(pub(crate) std::marker::PhantomData<*mut T>);
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
@@ -118,7 +98,9 @@ impl<T> ObjectArg<T>
 where
     T: GodotClass,
 {
-    pub fn from_raw_gd<Derived>(obj: &RawGd<Derived>) -> Self
+    /// # Safety
+    /// The referenced `RawGd` must remain valid for the lifetime of this `ObjectArg`.
+    pub unsafe fn from_raw_gd<Derived>(obj: &RawGd<Derived>) -> Self
     where
         Derived: Inherits<T>,
     {

godot/src/prelude.rs

@@ -26,7 +26,7 @@ pub use super::global::{
 pub use super::tools::{load, save, try_load, try_save, GFile};
 
 pub use super::init::{gdextension, ExtensionLibrary, InitLevel};
-pub use super::obj::{Base, Gd, GdMut, GdRef, GodotClass, Inherits, InstanceId, NullArg, OnReady};
+pub use super::obj::{Base, Gd, GdMut, GdRef, GodotClass, Inherits, InstanceId, OnReady};
 
 // Make trait methods available.
 pub use super::obj::EngineBitfield as _;

itest/rust/src/object_tests/object_arg_test.rs

@@ -8,7 +8,7 @@
 use godot::builtin::Variant;
 use godot::classes::{ClassDb, Node};
 use godot::global;
-use godot::obj::{Gd, NewAlloc, NullArg};
+use godot::obj::{Gd, NewAlloc};
 
 use crate::framework::itest;
 use crate::object_tests::object_test::{user_refc_instance, RefcPayload};
@@ -71,10 +71,10 @@ fn object_arg_option_none() {
 fn object_arg_null_arg() {
     // Will emit errors but should not crash.
     let db = ClassDb::singleton();
-    let error = db.class_set_property(NullArg, "name".into(), Variant::from("hello"));
+    let error = db.class_set_property(Gd::null_arg(), "name".into(), Variant::from("hello"));
     assert_eq!(error, global::Error::ERR_UNAVAILABLE);
 
-    let error = db.class_set_property(NullArg, "value".into(), Variant::from(-123));
+    let error = db.class_set_property(Gd::null_arg(), "value".into(), Variant::from(-123));
     assert_eq!(error, global::Error::ERR_UNAVAILABLE);
 }