Change NotUniqueError::check() to Gd::try_to_unique()

Author: Bromeon

godot-core/src/meta/error/mod.rs

@@ -9,6 +9,8 @@
 
 mod call_error;
 mod convert_error;
+mod not_unique_error;
 
 pub use call_error::*;
 pub use convert_error::*;
+pub use not_unique_error::*;

godot-core/src/meta/error/not_unique_error.rs

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/// Error caused by a reference-counted [`Gd`] instance which is not unique.
+///
+/// See [`Gd::try_to_unique()`] for futher information.
+#[derive(Debug)]
+pub enum NotUniqueError {
+    /// The instance is shared and has a reference count greater than 1.
+    Shared { ref_count: usize },
+
+    /// The instance is not reference-counted; thus can't determine its uniqueness.
+    NotRefCounted,
+}
+
+impl std::error::Error for NotUniqueError {}
+
+impl std::fmt::Display for NotUniqueError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Shared { ref_count } => {
+                write!(f, "pointer is not unique, reference count: {ref_count}")
+            }
+            Self::NotRefCounted => {
+                write!(f, "pointer is not reference-counted")
+            }
+        }
+    }
+}

godot-core/src/obj/bounds.rs

@@ -175,6 +175,10 @@ pub trait DynMemory: Sealed {
     #[doc(hidden)]
     fn is_ref_counted<T: GodotClass>(obj: &RawGd<T>) -> Option<bool>;
 
+    /// Return the reference count, or `None` if the object is dead or manually managed.
+    #[doc(hidden)]
+    fn get_ref_count<T: GodotClass>(obj: &RawGd<T>) -> Option<usize>;
+
     /// Returns `true` if argument and return pointers are passed as `Ref<T>` pointers given this
     /// [`PtrcallType`].
     ///
@@ -236,6 +240,13 @@ impl DynMemory for MemRefCounted {
         Some(true)
     }
 
+    fn get_ref_count<T: GodotClass>(obj: &RawGd<T>) -> Option<usize> {
+        let ref_count = obj.with_ref_counted(|refc| refc.get_reference_count());
+
+        // TODO find a safer cast alternative, e.g. num-traits crate with ToPrimitive (Debug) + AsPrimitive (Release).
+        Some(ref_count as usize)
+    }
+
     fn pass_as_ref(call_type: sys::PtrcallType) -> bool {
         matches!(call_type, sys::PtrcallType::Virtual)
     }
@@ -244,30 +255,30 @@ impl DynMemory for MemRefCounted {
 /// Memory managed through Godot reference counter, if present; otherwise manual.
 /// This is used only for `Object` classes.
 pub struct MemDynamic {}
+impl MemDynamic {
+    /// Check whether dynamic type is ref-counted.
+    fn inherits_refcounted<T: GodotClass>(obj: &RawGd<T>) -> bool {
+        obj.instance_id_unchecked()
+            .map(|id| id.is_ref_counted())
+            .unwrap_or(false)
+    }
+}
 impl Sealed for MemDynamic {}
 impl DynMemory for MemDynamic {
     fn maybe_init_ref<T: GodotClass>(obj: &mut RawGd<T>) {
         out!("  MemDyn::init  <{}>", std::any::type_name::<T>());
-        if obj
-            .instance_id_unchecked()
-            .map(|id| id.is_ref_counted())
-            .unwrap_or(false)
-        {
+        if Self::inherits_refcounted(obj) {
             // Will call `RefCounted::init_ref()` which checks for liveness.
-            out!("MemDyn -> MemRefc");
+            out!("    MemDyn -> MemRefc");
             MemRefCounted::maybe_init_ref(obj)
         } else {
-            out!("MemDyn -> MemManu");
+            out!("    MemDyn -> MemManu");
         }
     }
 
     fn maybe_inc_ref<T: GodotClass>(obj: &mut RawGd<T>) {
         out!("  MemDyn::inc   <{}>", std::any::type_name::<T>());
-        if obj
-            .instance_id_unchecked()
-            .map(|id| id.is_ref_counted())
-            .unwrap_or(false)
-        {
+        if Self::inherits_refcounted(obj) {
             // Will call `RefCounted::reference()` which checks for liveness.
             MemRefCounted::maybe_inc_ref(obj)
         }
@@ -291,6 +302,14 @@ impl DynMemory for MemDynamic {
         // Return `None` if obj is dead
         obj.instance_id_unchecked().map(|id| id.is_ref_counted())
     }
+
+    fn get_ref_count<T: GodotClass>(obj: &RawGd<T>) -> Option<usize> {
+        if Self::inherits_refcounted(obj) {
+            MemRefCounted::get_ref_count(obj)
+        } else {
+            None
+        }
+    }
 }
 
 /// No memory management, user responsible for not leaking.
@@ -307,6 +326,9 @@ impl DynMemory for MemManual {
     fn is_ref_counted<T: GodotClass>(_obj: &RawGd<T>) -> Option<bool> {
         Some(false)
     }
+    fn get_ref_count<T: GodotClass>(_obj: &RawGd<T>) -> Option<usize> {
+        None
+    }
 }
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------

godot-core/src/obj/gd.rs

@@ -411,7 +411,7 @@ impl<T: GodotClass> Gd<T> {
     #[doc(hidden)]
     pub fn script_sys(&self) -> sys::GDExtensionScriptLanguagePtr
     where
-        T: Inherits<crate::classes::ScriptLanguage>,
+        T: Inherits<classes::ScriptLanguage>,
     {
         self.raw.script_sys()
     }
@@ -553,6 +553,43 @@ where
     }
 }
 
+/// _The methods in this impl block are only available for objects `T` that are reference-counted,
+/// i.e. anything that inherits `RefCounted`._ <br><br>
+impl<T> Gd<T>
+where
+    T: GodotClass + Bounds<Memory = bounds::MemRefCounted>,
+{
+    /// Makes sure that `self` does not share references with other `Gd` instances.
+    ///
+    /// If `self` is unique, i.e. its reference count is 1, then `Ok(self)` is returned.
+    ///
+    /// If `self` is shared or not reference-counted (`T=Object` pointing to a dynamic type that is manually managed),
+    /// then `Err((self, NotUniqueError))` is returned. You can thus reuse the original object (first element in the tuple).
+    ///
+    /// ## Example
+    ///
+    /// ```no_run
+    /// use godot::prelude::*;
+    /// use godot::meta::error::NotUniqueError;
+    ///
+    /// let unique = RefCounted::new_gd();
+    /// assert!(unique.try_to_unique().is_ok());
+    ///
+    /// let shared = RefCounted::new_gd();
+    /// let shared2 = shared.clone();
+    /// assert!(shared.try_to_unique().is_err());
+    /// ```
+    pub fn try_to_unique(mut self) -> Result<Self, (Self, NotUniqueError)> {
+        use crate::obj::bounds::DynMemory as _;
+
+        match <T as Bounds>::DynMemory::get_ref_count(&self.raw) {
+            Some(1) => Ok(self),
+            Some(ref_count) => Err((self, NotUniqueError::Shared { ref_count })),
+            None => Err((self, NotUniqueError::NotRefCounted)),
+        }
+    }
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Trait impls
 
@@ -737,83 +774,5 @@ impl<T: GodotClass> std::hash::Hash for Gd<T> {
 impl<T: GodotClass> std::panic::UnwindSafe for Gd<T> {}
 impl<T: GodotClass> std::panic::RefUnwindSafe for Gd<T> {}
 
-/// Error stemming from the non-uniqueness of the [`Gd`] instance.
-///
-/// Keeping track of the uniqueness of references can be crucial in many applications, especially if we want to ensure
-/// that the passed [`Gd`] reference will be possessed by only one different object instance or function in its lifetime.
-///
-/// Only applicable to [`GodotClass`] objects that inherit from [`RefCounted`](crate::gen::classes::RefCounted). To check the
-/// uniqueness, call the `check()` associated method.
-///
-/// ## Example
-///
-/// ```no_run
-/// use godot::prelude::*;
-/// use godot::obj::NotUniqueError;
-///
-/// let shared = RefCounted::new_gd();
-/// let cloned = shared.clone();
-/// let result = NotUniqueError::check(shared);
-///
-/// assert!(result.is_err());
-///
-/// if let Err(error) = result {
-///     assert_eq!(error.get_reference_count(), 2)
-/// }
-/// ```
-#[derive(Debug)]
-pub struct NotUniqueError {
-    reference_count: i32,
-}
-
-impl NotUniqueError {
-    /// check [`Gd`] reference uniqueness.
-    ///
-    /// Checks the [`Gd`] of the [`GodotClass`](crate::obj::GodotClass) that inherits from [`RefCounted`](crate::gen::classes::RefCounted)
-    /// if it is an unique reference to the object.
-    ///
-    /// ## Example
-    ///
-    /// ```no_run
-    /// use godot::prelude::*;
-    /// use godot::obj::NotUniqueError;
-    ///
-    /// let unique = RefCounted::new_gd();
-    /// assert!(NotUniqueError::check(unique).is_ok());
-    ///
-    /// let shared = RefCounted::new_gd();
-    /// let cloned = shared.clone();
-    /// assert!(NotUniqueError::check(shared).is_err());
-    /// assert!(NotUniqueError::check(cloned).is_err());
-    /// ```
-    pub fn check<T>(rc: Gd<T>) -> Result<Gd<T>, Self>
-    where
-        T: Inherits<crate::gen::classes::RefCounted>,
-    {
-        let rc = rc.upcast::<crate::gen::classes::RefCounted>();
-        let reference_count = rc.get_reference_count();
-
-        if reference_count != 1 {
-            Err(Self { reference_count })
-        } else {
-            Ok(rc.cast::<T>())
-        }
-    }
-
-    /// Get the detected reference count
-    pub fn get_reference_count(&self) -> i32 {
-        self.reference_count
-    }
-}
-
-impl std::error::Error for NotUniqueError {}
-
-impl std::fmt::Display for NotUniqueError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(
-            f,
-            "pointer is not unique, current reference count: {}",
-            self.reference_count
-        )
-    }
-}
+#[deprecated = "Moved to `godot::meta::error`"]
+pub use crate::meta::error::NotUniqueError;

godot-core/src/tools/io_error.rs

@@ -85,9 +85,9 @@ impl IoError {
             });
         }
 
-        match NotUniqueError::check(file_access) {
+        match file_access.try_to_unique() {
             Ok(gd) => Ok(gd),
-            Err(err) => Err(Self {
+            Err((_, err)) => Err(Self {
                 data: ErrorData::GFile(GFileError {
                     kind: GFileErrorKind::NotUniqueRef(err),
                     path: path.to_string(),

itest/rust/src/object_tests/object_test.rs

@@ -14,8 +14,8 @@ use godot::classes::{
     RefCounted,
 };
 use godot::global::instance_from_id;
-use godot::meta::GodotType;
-use godot::meta::{FromGodot, ToGodot};
+use godot::meta::error::NotUniqueError;
+use godot::meta::{FromGodot, GodotType, ToGodot};
 use godot::obj::{Base, Gd, Inherits, InstanceId, NewAlloc, NewGd, RawGd};
 use godot::register::{godot_api, GodotClass};
 use godot::sys::{self, interface_fn, GodotFfi};
@@ -841,6 +841,29 @@ fn object_get_scene_tree(ctx: &TestContext) {
     assert_eq!(count, 1);
 } // implicitly tested: node does not leak
 
+#[itest]
+fn object_try_to_unique() {
+    let a = RefCounted::new_gd();
+    let id = a.instance_id();
+    let a = a.try_to_unique().expect("a.try_to_unique()");
+    assert_eq!(a.instance_id(), id);
+
+    let b = a.clone();
+    let (b, err) = b.try_to_unique().expect_err("b.try_to_unique()");
+    assert_eq!(b.instance_id(), id);
+    assert!(matches!(err, NotUniqueError::Shared { ref_count: 2 }));
+
+    /* Re-enable if DynMemory is fixed.
+
+    let c = Object::new_alloc(); // manually managed
+    let id = c.instance_id();
+    let (c, err) = c.try_to_unique().expect_err("c.try_to_unique()");
+    assert_eq!(c.instance_id(), id);
+    assert!(matches!(err, NotUniqueError::NotRefCounted));
+    c.free();
+    */
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
 #[derive(GodotClass)]
@@ -1053,21 +1076,3 @@ fn double_use_reference() {
 #[derive(GodotClass)]
 #[class(no_init, base = EditorPlugin, editor_plugin, tool)]
 struct CustomEditorPlugin;
-
-// ----------------------------------------------------------------------------------------------------------------------------------------------
-
-#[itest]
-fn non_unique_error_works() {
-    use godot::classes::RefCounted;
-    use godot::obj::NotUniqueError;
-
-    let unique = RefCounted::new_gd();
-    assert!(NotUniqueError::check(unique).is_ok());
-
-    let shared = RefCounted::new_gd();
-    let cloned = shared.clone();
-    match NotUniqueError::check(cloned) {
-        Err(error) => assert_eq!(error.get_reference_count(), 2),
-        Ok(_) => panic!("NotUniqueError::check must not succeed"),
-    }
-}