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.

Author: chitoyuu

.github/workflows/full-ci.yml

@@ -277,20 +277,32 @@ 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: 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

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_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
+}

gdnative-core/src/init/init_handle.rs

@@ -8,22 +8,24 @@ use std::borrow::Cow;
 use std::ffi::CString;
 use std::ptr;
 
+use super::InitLevel;
+
 /// A handle that can register new classes to the engine during initialization.
 ///
 /// See [`godot_nativescript_init`](macro.godot_nativescript_init.html) and
 /// [`godot_init`](macro.godot_init.html).
 #[derive(Copy, Clone)]
 pub struct InitHandle {
-    #[doc(hidden)]
     handle: *mut libc::c_void,
+    init_level: InitLevel,
 }
 
 #[allow(deprecated)] // Remove once init(), register_properties() and register() have been renamed
 impl InitHandle {
     #[doc(hidden)]
     #[inline]
-    pub unsafe fn new(handle: *mut libc::c_void) -> Self {
-        InitHandle { handle }
+    pub unsafe fn new(handle: *mut libc::c_void, init_level: InitLevel) -> Self {
+        InitHandle { handle, init_level }
     }
 
     /// Registers a new class to the engine.
@@ -75,13 +77,14 @@ impl InitHandle {
     {
         let c_class_name = CString::new(&*name).unwrap();
 
-        if let Some(class_info) = class_registry::register_class_as::<C>(name) {
-            panic!(
-                "`{type_name}` has already been registered as `{old_name}`",
-                type_name = std::any::type_name::<C>(),
-                old_name = class_info.name,
-            );
-        }
+        match class_registry::register_class_as::<C>(name, self.init_level) {
+            Ok(true) => {}
+            Ok(false) => return,
+            Err(e) => {
+                godot_error!("gdnative-core: ignoring new registration: {e}");
+                return;
+            }
+        };
 
         unsafe {
             let base_name = CString::new(C::Base::class_name()).unwrap();

gdnative-core/src/init/macros.rs

@@ -57,7 +57,10 @@ macro_rules! godot_nativescript_init {
             }
 
             $crate::private::report_panics("nativescript_init", || {
-                $callback($crate::init::InitHandle::new(handle));
+                $crate::init::auto_register($crate::init::InitHandle::new(handle, $crate::init::InitLevel::AUTO));
+                $callback($crate::init::InitHandle::new(handle, $crate::init::InitLevel::USER));
+
+                $crate::init::diagnostics::missing_suggested_diagnostics();
             });
         }
     };

gdnative-core/src/init/mod.rs

@@ -40,9 +40,39 @@ mod info;
 mod init_handle;
 mod macros;
 
+pub mod diagnostics;
+
 pub use info::*;
 pub use init_handle::*;
 
+bitflags::bitflags! {
+    /// Initialization level used to distinguish the source of init actions, such as class registration.
+    /// Internal API.
+    #[doc(hidden)]
+    pub struct InitLevel: u8 {
+        /// Init level for automatic registration
+        const AUTO = 1;
+        /// Init level for user code
+        const USER = 2;
+    }
+}
+
+#[doc(hidden)]
+#[cfg(feature = "inventory")]
+#[inline]
+pub fn auto_register(init_handle: InitHandle) {
+    for plugin in inventory::iter::<crate::private::AutoInitPlugin> {
+        (plugin.f)(init_handle);
+    }
+}
+
+#[doc(hidden)]
+#[cfg(not(feature = "inventory"))]
+#[inline]
+pub fn auto_register(_init_handle: InitHandle) {
+    // Nothing to do here.
+}
+
 pub use crate::{
     godot_gdnative_init, godot_gdnative_terminate, godot_init, godot_nativescript_init,
 };