Merge pull request #737 from godot-rust/qol/remove-not-unique-error

Remove `NotUniqueError`

Author: Bromeon

godot-core/src/obj/bounds.rs

@@ -7,7 +7,7 @@
 
 //! Different ways how bounds of a `GodotClass` can be checked.
 //!
-//! This module contains three traits that can be used to check the characteristics of a `GodotClass` type:
+//! This module contains multiple traits that can be used to check the characteristics of a `GodotClass` type:
 //!
 //! 1. [`Declarer`] tells you whether the class is provided by the engine or user-defined.
 //!    - [`DeclEngine`] is used for all classes provided by the engine (e.g. `Node3D`).
@@ -19,15 +19,16 @@
 //!    - [`MemRefCounted`] is used for `RefCounted` classes and derived.
 //!    - [`MemManual`] is used for `Object` and all inherited classes, which are not `RefCounted` (e.g. `Node`).<br><br>
 //!
-//! 3. [`DynMemory`] is used to check the memory strategy of the **dynamic** type.
-//!
-//!    When you operate on methods of `T` or `Gd<T>` and are interested in instances, you can use this.
-//!    Most of the time, this is not what you want -- just use `Memory` if you want to know if a type is manually managed or ref-counted.
-//!    - [`MemRefCounted`] is used for `RefCounted` classes and derived. These are **always** reference-counted.
-//!    - [`MemManual`] is used instances inheriting `Object`, which are not `RefCounted` (e.g. `Node`). Excludes `Object` itself. These are
-//!      **always** manually managed.
-//!    - [`MemDynamic`] is used for `Object` instances. `Gd<Object>` can point to objects of any possible class, so whether we are dealing with
-//!      a ref-counted or manually-managed object is determined only at runtime.
+// FIXME excluded because broken; see below.
+// 3. [`DynMemory`] is used to check the memory strategy of the **dynamic** type.
+//
+//    When you operate on methods of `T` or `Gd<T>` and are interested in instances, you can use this.
+//    Most of the time, this is not what you want -- just use `Memory` if you want to know if a type is manually managed or ref-counted.
+//    - [`MemRefCounted`] is used for `RefCounted` classes and derived. These are **always** reference-counted.
+//    - [`MemManual`] is used instances inheriting `Object`, which are not `RefCounted` (e.g. `Node`). Excludes `Object` itself. These are
+//      **always** manually managed.
+//    - [`MemDynamic`] is used for `Object` instances. `Gd<Object>` can point to objects of any possible class, so whether we are dealing with
+//      a ref-counted or manually-managed object is determined only at runtime.
 //!
 //!
 //! # Example
@@ -44,7 +45,7 @@
 //! }
 //! ```
 //!
-//! Note that depending on if you want to exclude `Object`, you should use `DynMemory` instead of `Memory`.
+// Note that depending on if you want to exclude `Object`, you should use `DynMemory` instead of `Memory`.
 
 use crate::obj::cap::GodotDefault;
 use crate::obj::{Bounds, Gd, GodotClass, RawGd};
@@ -86,6 +87,10 @@ pub(super) mod private {
         /// Defines the memory strategy of the static type.
         type Memory: Memory;
 
+        // FIXME: this is broken as a bound: one cannot use T: Bounds<DynMemory = MemRefCounted> to include Object AND RefCounted,
+        // since Object itself has DynMemory = MemDynamic. Needs to either use traits like in gdnative, or more types to account for
+        // different combinations (as only positive ones can be expressed, not T: Bounds<Memory != MemManual>).
+        #[doc(hidden)]
         /// Defines the memory strategy of the instance (at runtime).
         type DynMemory: DynMemory;
 
@@ -146,6 +151,7 @@ pub trait Memory: Sealed {}
 /// Specifies the memory strategy of the dynamic type.
 ///
 /// For `Gd<Object>`, it is determined at runtime whether the instance is manually managed or ref-counted.
+#[doc(hidden)]
 pub trait DynMemory: Sealed {
     /// Initialize reference counter
     #[doc(hidden)]
@@ -175,6 +181,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,38 +246,46 @@ 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)
     }
 }
 
 /// Memory managed through Godot reference counter, if present; otherwise manual.
 /// This is used only for `Object` classes.
+#[doc(hidden)]
 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 +309,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 +333,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,44 @@ 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.
+    ///
+    /// Succeeds if the reference count is 1.
+    /// Otherwise, returns the shared object and its reference count.
+    ///
+    /// ## Example
+    ///
+    /// ```no_run
+    /// use godot::prelude::*;
+    ///
+    /// let obj = RefCounted::new_gd();
+    /// match obj.try_to_unique() {
+    ///    Ok(unique_obj) => {
+    ///        // No other Gd<T> shares a reference with `unique_obj`.
+    ///    },
+    ///    Err((shared_obj, ref_count)) => {
+    ///        // `shared_obj` is the original object `obj`.
+    ///        // `ref_count` is the total number of references (including one held by `shared_obj`).
+    ///    }
+    /// }
+    /// ```
+    pub fn try_to_unique(self) -> Result<Self, (Self, usize)> {
+        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, ref_count)),
+            None => unreachable!(),
+        }
+    }
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Trait impls
 
@@ -737,83 +775,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 = "Removed; see `Gd::try_to_unique()`"]
+pub type NotUniqueError = ();