Merge pull request #1325 from godot-rust/feature/singleton-trait

Migrate inherent `singleton()` fn to new `Singleton` trait

Author: Bromeon

godot-codegen/src/generator/classes.rs

@@ -80,10 +80,10 @@ struct GeneratedClassModule {
 }
 
 struct Construction {
-    constructor: TokenStream,
     construct_doc: &'static str,
     final_doc: Option<&'static str>,
     godot_default_impl: TokenStream,
+    singleton_impl: TokenStream,
 }
 
 fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClass {
@@ -102,10 +102,10 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
     };
 
     let Construction {
-        constructor,
         construct_doc,
         final_doc,
         godot_default_impl,
+        singleton_impl,
     } = make_constructor_and_default(class, ctx);
 
     let mut extended_class_doc = construct_doc.replace("Self", &class_name.rust_ty.to_string());
@@ -234,7 +234,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
             #interface_trait
             #notification_enum
             impl #class_name {
-                #constructor
+                // Constructors all through traits: NewGd, NewAlloc, Singleton.
                 #methods
                 #notify_methods
                 #internal_methods
@@ -267,6 +267,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
             )*
 
             #godot_default_impl
+            #singleton_impl
             #deref_impl
             #inherits_macro_code
         }
@@ -424,34 +425,18 @@ fn make_constructor_and_default(class: &Class, ctx: &Context) -> Construction {
     // Note: this could use class_id() but is not yet done due to potential future lazy-load refactoring.
     //let class_name_obj = quote! { <Self as crate::obj::GodotClass>::class_id() };
 
-    let (constructor, construct_doc, has_godot_default_impl);
+    let (construct_doc, has_godot_default_impl);
     if ctx.is_singleton(class_name) {
-        // Note: we cannot return &'static mut Self, as this would be very easy to mutably alias.
-        // &'static Self would be possible, but we would lose the whole mutability information (even if that is best-effort and
-        // not strict Rust mutability, it makes the API much more usable).
-        // As long as the user has multiple Gd smart pointers to the same singletons, only the internal raw pointers are aliased.
-        // See also Deref/DerefMut impl for Gd.
-        constructor = quote! {
-            pub fn singleton() -> Gd<Self> {
-                unsafe {
-                    let __class_name = #godot_class_stringname;
-                    let __object_ptr = sys::interface_fn!(global_get_singleton)(__class_name.string_sys());
-                    Gd::from_obj_sys(__object_ptr)
-                }
-            }
-        };
         construct_doc = "# Singleton\n\n\
-            This class is a singleton. You can get the one instance using [`Self::singleton()`][Self::singleton].";
+            This class is a singleton. You can get the one instance using [`Singleton::singleton()`][crate::obj::Singleton::singleton].";
         has_godot_default_impl = false;
     } else if !class.is_instantiable {
         // Abstract base classes or non-singleton classes without constructor.
-        constructor = TokenStream::new();
         construct_doc = "# Not instantiable\n\nThis class cannot be constructed. Obtain `Gd<Self>` instances via Godot APIs.";
         has_godot_default_impl = false;
     } else {
         // Manually managed classes (Object, Node, ...) as well as ref-counted ones (RefCounted, Resource, ...).
         // The constructors are provided as associated methods in NewGd::new_gd() and NewAlloc::new_alloc().
-        constructor = TokenStream::new();
 
         if class.is_refcounted {
             construct_doc = "# Construction\n\n\
@@ -488,11 +473,25 @@ fn make_constructor_and_default(class: &Class, ctx: &Context) -> Construction {
         TokenStream::new()
     };
 
+    let singleton_impl = if ctx.is_singleton(class_name) {
+        let class_name = &class.name().rust_ty;
+        quote! {
+            impl crate::obj::Singleton for #class_name {
+                fn singleton() -> crate::obj::Gd<Self> {
+                    // SAFETY: Class name matches type T, per code generator.
+                    unsafe { crate::classes::singleton_unchecked(&#godot_class_stringname) }
+                }
+            }
+        }
+    } else {
+        TokenStream::new()
+    };
+
     Construction {
-        constructor,
         construct_doc,
         final_doc,
         godot_default_impl,
+        singleton_impl,
     }
 }
 
@@ -573,8 +572,6 @@ fn make_class_method_definition(
         return FnDefinition::none();
     };
 
-    // Note: parameter type replacements (int -> enum) are already handled during domain mapping.
-
     let rust_class_name = class.name().rust_ty.to_string();
     let rust_method_name = method.name();
     let godot_method_name = method.godot_name();

godot-core/src/builtin/callable.rs

@@ -13,7 +13,7 @@ use sys::{ffi_methods, ExtVariantType, GodotFfi};
 use crate::builtin::{inner, GString, StringName, Variant, VariantArray};
 use crate::meta::{GodotType, ToGodot};
 use crate::obj::bounds::DynMemory;
-use crate::obj::{Bounds, Gd, GodotClass, InstanceId};
+use crate::obj::{Bounds, Gd, GodotClass, InstanceId, Singleton};
 use crate::{classes, meta};
 
 #[cfg(before_api = "4.3")]

godot-core/src/builtin/string/node_path.rs

@@ -8,7 +8,7 @@
 use std::fmt;
 
 use godot_ffi as sys;
-use godot_ffi::{ffi_methods, ExtVariantType, GodotFfi};
+use godot_ffi::{ffi_methods, ExtVariantType, GdextBuild, GodotFfi};
 
 use super::{GString, StringName};
 use crate::builtin::inner;
@@ -160,7 +160,7 @@ impl NodePath {
     pub fn subpath(&self, range: impl SignedRange) -> NodePath {
         let (from, exclusive_end) = range.signed();
         // Polyfill for bug https://github.com/godotengine/godot/pull/100954, fixed in 4.4.
-        let begin = if sys::GdextBuild::since_api("4.4") {
+        let begin = if GdextBuild::since_api("4.4") {
             from
         } else {
             let name_count = self.get_name_count() as i64;

godot-core/src/classes/class_runtime.rs

@@ -13,7 +13,7 @@ use crate::classes::{ClassDb, Object};
 use crate::meta::CallContext;
 #[cfg(debug_assertions)]
 use crate::meta::ClassId;
-use crate::obj::{bounds, Bounds, Gd, GodotClass, InstanceId, RawGd};
+use crate::obj::{bounds, Bounds, Gd, GodotClass, InstanceId, RawGd, Singleton};
 use crate::sys;
 
 pub(crate) fn debug_string<T: GodotClass>(
@@ -181,6 +181,16 @@ where
     obj
 }
 
+/// # Safety
+/// The caller must ensure that `class_name` corresponds to the actual class name of type `T`.
+pub(crate) unsafe fn singleton_unchecked<T>(class_name: &StringName) -> Gd<T>
+where
+    T: GodotClass,
+{
+    let object_ptr = unsafe { sys::interface_fn!(global_get_singleton)(class_name.string_sys()) };
+    Gd::<T>::from_obj_sys(object_ptr)
+}
+
 pub(crate) fn ensure_object_alive(
     instance_id: InstanceId,
     old_object_ptr: sys::GDExtensionObjectPtr,

godot-core/src/meta/property_info.rs

@@ -13,7 +13,7 @@ use crate::meta::{element_godot_type_name, ArrayElement, ClassId, GodotType, Pac
 use crate::obj::{bounds, Bounds, EngineBitfield, EngineEnum, GodotClass};
 use crate::registry::class::get_dyn_property_hint_string;
 use crate::registry::property::{Export, Var};
-use crate::{classes, godot_str, sys};
+use crate::{classes, sys};
 
 /// Describes a property in Godot.
 ///
@@ -298,13 +298,6 @@ impl PropertyHintInfo {
         }
     }
 
-    pub fn type_name_range<T: GodotType + std::fmt::Display>(lower: T, upper: T) -> Self {
-        Self {
-            hint: PropertyHint::RANGE,
-            hint_string: godot_str!("{lower},{upper}"), // also valid for <4.3.
-        }
-    }
-
     /// Use for `#[var]` properties -- [`PROPERTY_HINT_ARRAY_TYPE`](PropertyHint::ARRAY_TYPE) with the type name as hint string.
     pub fn var_array_element<T: ArrayElement>() -> Self {
         Self {

godot-core/src/obj/traits.rs

@@ -684,6 +684,23 @@ pub trait NewAlloc: GodotClass {
     fn new_alloc() -> Gd<Self>;
 }
 
+/// Trait for singleton classes in Godot.
+///
+/// There is only one instance of each singleton class in the engine, accessible through [`singleton()`][Self::singleton].
+pub trait Singleton: GodotClass {
+    // Note: we cannot return &'static mut Self, as this would be very easy to mutably alias. Returning &'static Self is possible,  but we'd
+    // lose the whole mutability information (even if that is best-effort and not strict Rust mutability, it makes the API much more usable).
+    // As long as the user has multiple Gd smart pointers to the same singletons, only the internal raw pointers are aliased.
+    // See also Deref/DerefMut impl for Gd.
+
+    /// Returns the singleton instance.
+    ///
+    /// # Panics
+    /// If called during global init/deinit of godot-rust. Most singletons are only available after the first frame has run.
+    /// See also [`ExtensionLibrary`](../init/trait.ExtensionLibrary.html#availability-of-godot-apis-during-init-and-deinit).
+    fn singleton() -> Gd<Self>;
+}
+
 impl<T> NewAlloc for T
 where
     T: cap::GodotDefault + Bounds<Memory = bounds::MemManual>,

godot-core/src/private.rs

@@ -199,6 +199,8 @@ pub const fn is_editor_plugin<T: crate::obj::Inherits<crate::classes::EditorPlug
 // Starting from 4.3, Godot has "runtime classes"; this emulation is no longer needed.
 #[cfg(before_api = "4.3")]
 pub fn is_class_inactive(is_tool: bool) -> bool {
+    use crate::obj::Singleton;
+
     if is_tool {
         return false;
     }

godot-core/src/registry/class.rs

@@ -15,7 +15,7 @@ use crate::classes::ClassDb;
 use crate::init::InitLevel;
 use crate::meta::error::FromGodotError;
 use crate::meta::ClassId;
-use crate::obj::{cap, DynGd, Gd, GodotClass};
+use crate::obj::{cap, DynGd, Gd, GodotClass, Singleton};
 use crate::private::{ClassPlugin, PluginItem};
 use crate::registry::callbacks;
 use crate::registry::plugin::{DynTraitImpl, ErasedRegisterFn, ITraitImpl, InherentImpl, Struct};