Merge #999

999: Implement automatic `NativeClass` registration via inventory. Implement mix-ins. r=chitoyuu a=chitoyuu

## Implement automatic NativeClass registration via inventory

This adds the optional `inventory` feature, which allows `NativeClass` types to be automatically registered on supported platforms (everything that OSS Godot currently supports except WASM).

Run-time diagnostic functions are added to help debug missing registration problems that are highly likely to arise when porting `inventory`-enabled projects to WASM.

An internal `cfg_ex` attribute macro is added to help manage cfg conditions.

Close #350. Note that the standalone registration attribute syntax proposed by the original issue isn't implemented, for the limited usefulness -- there are much fewer cases where manual `NativeClass` impls are necessary thanks to all the improvements since the original issue.

## Implement mix-in `#[methods]` blocks

Adds the `#[methods(mixin = "Name")]` syntax for declaring mix-in blocks. Mix-in blocks have a many-to-many relationship with `NativeClass` types. Both `impl Type` and `impl Trait for Type` blocks are accepted.

The argument name is changed from `as` in the original proposal to `mixin`, because we might still want to keep universal `#[methods]` blocks in the future for ease of use with WASM. `#[methods(mixin)]` makes a lot more sense for a future auto-registered mixin block than `#[methods(as /* as what? */)]`.

All mix-in blocks have to be manually registered for gdnative v0.11.x. Some difficulty was encountered when trying to make auto-mixins compatible with existing code. It might still be possible with some tricks like autoref-specialization, but that might be too much effort given that we likely want to re-design much of the hierarchy for 0.12.

Close #984.

## Allow `#[register_with]` for `#[monomorphize]`

Enables `#[monomorphize]` to take the same standalone `#[register_with]` attribute as `#[derive(NativeClass)]`. This is chosen for short term consistency, but will probably change in a later version w/ #848, which might not still get implemented for a fair bit of time.


Co-authored-by: Chitose Yuuzaki <[email protected]>

Author: bors[bot]

.github/workflows/full-ci.yml

@@ -277,20 +277,38 @@ jobs:
             godot: "3.5.1-stable"
             postfix: ' (ptrcall)'
             build_args: '--features ptrcall'
+          - rust: stable
+            godot: "3.5.1-stable"
+            postfix: ' (inventory)'
+            build_args: '--features inventory'
+          - rust: stable
+            godot: "3.5.1-stable"
+            postfix: ' (inventory)'
+            # Limiting no-manual-register tests to stable as to not slow down CI too far -- if inventory is
+            # working across all 3 Rust versions, this is likely to be as well.
+            build_args: '--features inventory,no-manual-register'
           - rust: nightly
             godot: "3.5.1-stable"
             postfix: ' (nightly)'
           - rust: nightly
             godot: "3.5.1-stable"
             postfix: ' (nightly, ptrcall)'
             build_args: '--features ptrcall'
+          - rust: nightly
+            godot: "3.5.1-stable"
+            postfix: ' (nightly, inventory)'
+            build_args: '--features inventory'
           - rust: '1.63'
             godot: "3.5.1-stable"
             postfix: ' (msrv 1.63)'
           - rust: '1.63'
             godot: "3.5.1-stable"
             postfix: ' (msrv 1.63, ptrcall)'
             build_args: '--features ptrcall'
+          - rust: '1.63'
+            godot: "3.5.1-stable"
+            postfix: ' (msrv 1.63, inventory)'
+            build_args: '--features inventory'
 
           # Test with oldest supported engine version
           - rust: stable

check.sh

@@ -62,7 +62,8 @@ function findGodot() {
     fi
 }
 
-features="gdnative/async,gdnative/serde"
+features="gdnative/async,gdnative/serde,gdnative/inventory"
+itest_toggled_features="no-manual-register"
 cmds=()
 
 for arg in "${args[@]}"; do
@@ -81,6 +82,9 @@ for arg in "${args[@]}"; do
         cmds+=("cargo build --manifest-path test/Cargo.toml --features $features")
         cmds+=("cp target/debug/*gdnative_test* test/project/lib/")
         cmds+=("$godotBin --path test/project")
+        cmds+=("cargo build --manifest-path test/Cargo.toml --features $features,$itest_toggled_features")
+        cmds+=("cp target/debug/*gdnative_test* test/project/lib/")
+        cmds+=("$godotBin --path test/project")
         ;;
     doc)
         cmds+=("cargo doc --lib -p gdnative --no-deps --features $features")

gdnative-core/Cargo.toml

@@ -30,6 +30,7 @@ libc = "0.2"
 once_cell = "1"
 parking_lot = "0.12"
 serde = { version = "1", features = ["derive"], optional = true }
+inventory = { version = "0.3", optional = true }
 
 [dev-dependencies]
 gdnative = { path = "../gdnative" } # for doc-tests

gdnative-core/src/export/class.rs

@@ -99,13 +99,20 @@ pub trait NativeClass: Sized + 'static {
 
 /// A NativeScript "class" that is statically named. [`NativeClass`] types that implement this
 /// trait can be registered using  [`InitHandle::add_class`].
+///
+/// This trait will be renamed to [`Monomorphized`] in a future version since its purpose has
+/// grown beyond simply providing a static type name.
 pub trait StaticallyNamed: NativeClass {
     /// The name of the class.
     ///
     /// This name must be unique for the dynamic library. For generic or library code where this
     /// is hard to satisfy, consider using [`InitHandle::add_class_as`] to provide a name
     /// at registration time instead.
     const CLASS_NAME: &'static str;
+
+    /// Function that registers methods specific to this monomorphization.
+    #[inline]
+    fn nativeclass_register_monomorphized(_builder: &ClassBuilder<Self>) {}
 }
 
 /// Trait used to provide information of Godot-exposed methods of a script class.

gdnative-core/src/export/class_builder.rs

@@ -1,3 +1,6 @@
+use std::any::TypeId;
+use std::cell::RefCell;
+use std::collections::HashSet;
 use std::ffi::CString;
 use std::marker::PhantomData;
 use std::ptr;
@@ -20,6 +23,7 @@ use crate::private::get_api;
 pub struct ClassBuilder<C> {
     pub(super) init_handle: *mut libc::c_void,
     pub(super) class_name: CString,
+    mixins: RefCell<HashSet<TypeId, ahash::RandomState>>,
     _marker: PhantomData<C>,
 }
 
@@ -28,6 +32,7 @@ impl<C: NativeClass> ClassBuilder<C> {
         Self {
             init_handle,
             class_name,
+            mixins: RefCell::default(),
             _marker: PhantomData,
         }
     }
@@ -241,4 +246,48 @@ impl<C: NativeClass> ClassBuilder<C> {
             );
         }
     }
+
+    /// Add a mixin to the class being registered.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use gdnative::prelude::*;
+    ///
+    /// #[derive(NativeClass)]
+    /// #[inherit(Node)]
+    /// #[register_with(my_register)]
+    /// #[no_constructor]
+    /// struct MyType {}
+    ///
+    /// // This creates a opaque type `MyMixin` in the current scope that implements
+    /// // the `Mixin` trait. Mixin types have no public interface or stable layout.
+    /// #[methods(mixin = "MyMixin")]
+    /// impl MyType {
+    ///     #[method]
+    ///     fn my_method(&self) -> i64 { 42 }
+    /// }
+    ///
+    /// fn my_register(builder: &ClassBuilder<MyType>) {
+    ///     builder.mixin::<MyMixin>();
+    /// }
+    /// ```
+    #[inline]
+    pub fn mixin<M: Mixin<C>>(&self) {
+        if self.mixins.borrow_mut().insert(TypeId::of::<M>()) {
+            M::register(self);
+        }
+    }
+}
+
+/// Trait for mixins, manually registered `#[methods]` blocks that may be applied to multiple types.
+///
+/// This trait is implemented on generated types by the `#[methods]` proc-macro only, and has no public interface.
+/// Use [`ClassBuilder::mixin`] to register mixins to [`NativeClass`] types.    
+pub trait Mixin<C>: crate::private::mixin::Sealed + 'static
+where
+    C: NativeClass,
+{
+    #[doc(hidden)]
+    fn register(builder: &ClassBuilder<C>);
 }

gdnative-core/src/export/class_registry.rs

@@ -1,17 +1,22 @@
 use std::any::TypeId;
 use std::borrow::Cow;
+use std::collections::hash_map::Entry;
 use std::collections::HashMap;
+use std::fmt;
 
 use once_cell::sync::Lazy;
 use parking_lot::RwLock;
 
 use crate::export::NativeClass;
+use crate::init::InitLevel;
 
 static CLASS_REGISTRY: Lazy<RwLock<HashMap<TypeId, ClassInfo>>> =
     Lazy::new(|| RwLock::new(HashMap::new()));
 
+#[derive(Clone, Debug)]
 pub(crate) struct ClassInfo {
     pub name: Cow<'static, str>,
+    pub init_level: InitLevel,
 }
 
 /// Access the [`ClassInfo`] of the class `C`.
@@ -40,12 +45,89 @@ pub(crate) fn class_name_or_default<C: NativeClass>() -> Cow<'static, str> {
     class_name::<C>().unwrap_or_else(|| Cow::Borrowed(std::any::type_name::<C>()))
 }
 
-/// Registers the class `C` in the class registry, using a custom name.
-/// Returns the old `ClassInfo` if `C` was already added.
+/// Registers the class `C` in the class registry, using a custom name at the given level.
+/// Returns `Ok(true)` if FFI registration needs to be performed. `Ok(false)` if the class has
+/// already been registered on another level.
+/// Returns an error with the old `ClassInfo` if a conflicting entry for `C` was already added.
 #[inline]
-pub(crate) fn register_class_as<C: NativeClass>(name: Cow<'static, str>) -> Option<ClassInfo> {
+pub(crate) fn register_class_as<C: NativeClass>(
+    name: Cow<'static, str>,
+    init_level: InitLevel,
+) -> Result<bool, RegisterError> {
     let type_id = TypeId::of::<C>();
-    CLASS_REGISTRY.write().insert(type_id, ClassInfo { name })
+    let mut registry = CLASS_REGISTRY.write();
+    match registry.entry(type_id) {
+        Entry::Vacant(entry) => {
+            entry.insert(ClassInfo { name, init_level });
+            Ok(true)
+        }
+        Entry::Occupied(entry) => {
+            let class_info = entry.get();
+            let kind = if class_info.name != name {
+                Some(RegisterErrorKind::ConflictingName)
+            } else if class_info.init_level.intersects(init_level) {
+                Some(RegisterErrorKind::AlreadyOnSameLevel)
+            } else {
+                None
+            };
+
+            if let Some(kind) = kind {
+                Err(RegisterError {
+                    class_info: class_info.clone(),
+                    type_name: std::any::type_name::<C>(),
+                    kind,
+                })
+            } else {
+                Ok(false)
+            }
+        }
+    }
+}
+
+#[inline]
+#[allow(dead_code)] // Currently unused on platforms with inventory support
+pub(crate) fn types_with_init_level(allow: InitLevel, deny: InitLevel) -> Vec<Cow<'static, str>> {
+    let registry = CLASS_REGISTRY.read();
+    let mut list = registry
+        .values()
+        .filter_map(|class_info| {
+            (class_info.init_level.intersects(allow) && !class_info.init_level.intersects(deny))
+                .then(|| class_info.name.clone())
+        })
+        .collect::<Vec<_>>();
+
+    list.sort_unstable();
+    list
+}
+
+#[derive(Debug)]
+pub(crate) struct RegisterError {
+    pub type_name: &'static str,
+    pub class_info: ClassInfo,
+    pub kind: RegisterErrorKind,
+}
+
+#[derive(Debug)]
+pub(crate) enum RegisterErrorKind {
+    ConflictingName,
+    AlreadyOnSameLevel,
+}
+
+impl fmt::Display for RegisterError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self.kind {
+            RegisterErrorKind::ConflictingName => {
+                write!(
+                    f,
+                    "`{}` has already been registered as `{}`",
+                    self.type_name, self.class_info.name
+                )
+            }
+            RegisterErrorKind::AlreadyOnSameLevel => {
+                write!(f, "`{}` has already been registered", self.type_name)
+            }
+        }
+    }
 }
 
 /// Clears the registry

gdnative-core/src/init/diagnostics.rs

@@ -0,0 +1,15 @@
+//! Run-time tracing functions to help debug the init process.
+//!
+//! The provided functions are designed to convey any issues found through human-readable
+//! error output, while programmatically providing only an overall indication of whether
+//! any problems were found. This is so that they can be freely improved without compatibility
+//! concerns.
+
+mod missing_manual_registration;
+mod missing_suggested_diagnostics;
+
+#[doc(inline)]
+pub use missing_manual_registration::missing_manual_registration;
+
+#[doc(inline)]
+pub use missing_suggested_diagnostics::missing_suggested_diagnostics;

gdnative-core/src/init/diagnostics/missing_manual_registration.rs

@@ -0,0 +1,61 @@
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use gdnative_impl_proc_macros::cfg_ex;
+
+pub static CHECKED: AtomicBool = AtomicBool::new(false);
+
+/// Checks for any `NativeClass` types that are registered automatically, but not manually.
+/// Returns `true` if the test isn't applicable, or if no such types were found.
+///
+/// Some platforms may not have support for automatic registration. On such platforms, only
+/// manually registered classes are visible at run-time.
+///
+/// Please refer to [the `rust-ctor` README][ctor-repo] for an up-to-date listing of platforms
+/// that *do* support automatic registration.
+///
+/// [ctor-repo]: https://github.com/mmastrac/rust-ctor
+#[inline]
+pub fn missing_manual_registration() -> bool {
+    CHECKED.store(true, Ordering::Release);
+    check_missing_manual_registration()
+}
+
+#[cfg_ex(not(all(feature = "inventory", gdnative::inventory_platform_available)))]
+fn check_missing_manual_registration() -> bool {
+    true
+}
+
+#[cfg_ex(all(feature = "inventory", gdnative::inventory_platform_available))]
+fn check_missing_manual_registration() -> bool {
+    use crate::init::InitLevel;
+
+    let types =
+        crate::export::class_registry::types_with_init_level(InitLevel::AUTO, InitLevel::USER);
+
+    if types.is_empty() {
+        return true;
+    }
+
+    let mut message = format!(
+        "gdnative-core: {} NativeScript(s) are not manually registered: ",
+        types.len()
+    );
+
+    let mut first = true;
+    for name in types {
+        if first {
+            first = false;
+        } else {
+            message.push_str(", ");
+        }
+        message.push_str(&name);
+    }
+
+    godot_warn!("{message}");
+    godot_warn!(concat!(
+        "gdnative-core: Types that are not manually registered will not be available on platforms ",
+        "where automatic registration is unavailable.",
+    ));
+
+    false
+}

gdnative-core/src/init/diagnostics/missing_suggested_diagnostics.rs

@@ -0,0 +1,42 @@
+use gdnative_impl_proc_macros::cfg_ex;
+
+/// Checks if all suggested diagnostics have been ran depending on the current platform, at
+/// the point of invocation. This is automatically ran as part of the init macro, and do not
+/// usually need to be manually invoked.
+///
+/// Returns `true` in a release build, or if no such diagnostics were found.
+#[inline]
+pub fn missing_suggested_diagnostics() -> bool {
+    check_missing_suggested_diagnostics()
+}
+
+#[cfg(not(debug_assertions))]
+fn check_missing_suggested_diagnostics() -> bool {
+    true
+}
+
+#[cfg(debug_assertions)]
+fn check_missing_suggested_diagnostics() -> bool {
+    check_missing_suggested_diagnostics_inventory_unavailable()
+}
+
+#[cfg_ex(all(feature = "inventory", not(gdnative::inventory_platform_available)))]
+fn check_missing_suggested_diagnostics_inventory_unavailable() -> bool {
+    if !super::missing_manual_registration::CHECKED.load(std::sync::atomic::Ordering::Acquire) {
+        godot_warn!(concat!(
+            "gdnative-core: `gdnative` was compiled with the `inventory` feature, but the current platform ",
+            "does not support automatic registration. As such, only manually registered types will be available.\n",
+            "Call `gdnative::init::diagnostics::missing_manual_registration()` at the end your init callback to "
+            "suppress this message."
+        ));
+
+        false
+    } else {
+        true
+    }
+}
+
+#[cfg_ex(not(all(feature = "inventory", not(gdnative::inventory_platform_available))))]
+fn check_missing_suggested_diagnostics_inventory_unavailable() -> bool {
+    true
+}