Cache autoloads once resolved

Author: Bromeon

godot-core/src/init/mod.rs

@@ -232,6 +232,7 @@ fn gdext_on_level_deinit(level: InitLevel) {
         // No business logic by itself, but ensures consistency if re-initialization (hot-reload on Linux) occurs.
 
         crate::task::cleanup();
+        crate::tools::cleanup();
 
         // Garbage-collect various statics.
         // SAFETY: this is the last time meta APIs are used.

godot-core/src/tools/autoload.rs

@@ -5,16 +5,24 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+use std::cell::RefCell;
+use std::collections::HashMap;
+
+use sys::is_main_thread;
+
 use crate::builtin::NodePath;
 use crate::classes::{Engine, Node, SceneTree};
 use crate::meta::error::ConvertError;
 use crate::obj::{Gd, Inherits, Singleton};
+use crate::sys;
 
-/// Retrieves an autoload by its name.
+/// Retrieves an autoload by name.
 ///
 /// See [Godot docs] for an explanation of the autoload concept. Godot sometimes uses the term "autoload" interchangeably with "singleton";
 /// we strictly refer to the former to separate from [`Singleton`][crate::obj::Singleton] objects.
 ///
+/// If the autoload can be resolved, it will be cached and returned very quickly the second time.
+///
 /// [Godot docs]: https://docs.godotengine.org/en/stable/tutorials/scripting/singletons_autoload.html
 ///
 /// # Panics
@@ -48,6 +56,8 @@ where
 /// Autoloads are accessed via the `/root/{name}` path in the scene tree. The name is the one you used to register the autoload in
 /// `project.godot`. By convention, it often corresponds to the class name, but does not have to.
 ///
+/// If the autoload can be resolved, it will be cached and returned very quickly the second time.
+///
 /// See also [`get_autoload_by_name()`] for simpler function expecting the class name and non-fallible invocation.
 ///
 /// This function returns `Err` if:
@@ -76,6 +86,16 @@ pub fn try_get_autoload_by_name<T>(autoload_name: &str) -> Result<Gd<T>, Convert
 where
     T: Inherits<Node>,
 {
+    ensure_main_thread()?;
+
+    // Check cache first.
+    let cached = AUTOLOAD_CACHE.with(|cache| cache.borrow().get(autoload_name).cloned());
+
+    if let Some(cached_node) = cached {
+        return cast_autoload(cached_node, autoload_name);
+    }
+
+    // Cache miss - fetch from scene tree.
     let main_loop = Engine::singleton()
         .get_main_loop()
         .ok_or_else(|| ConvertError::new("main loop not available"))?;
@@ -90,10 +110,68 @@ where
         .get_root()
         .ok_or_else(|| ConvertError::new("scene tree root not available"))?;
 
-    root.try_get_node_as::<T>(&autoload_path).ok_or_else(|| {
-        let class = T::class_id();
+    let autoload_node = root
+        .try_get_node_as::<Node>(&autoload_path)
+        .ok_or_else(|| ConvertError::new(format!("autoload `{autoload_name}` not found")))?;
+
+    // Store in cache as Gd<Node>.
+    AUTOLOAD_CACHE.with(|cache| {
+        cache
+            .borrow_mut()
+            .insert(autoload_name.to_string(), autoload_node.clone());
+    });
+
+    // Cast to requested type.
+    cast_autoload(autoload_node, autoload_name)
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Cache implementation
+
+thread_local! {
+    /// Cache for autoloads. Maps autoload name to `Gd<Node>`.
+    ///
+    /// Uses `thread_local!` because `Gd<T>` is not `Send`/`Sync`. Since all Godot objects must be accessed
+    /// from the main thread, this is safe. We enforce main-thread access via `ensure_main_thread()`.
+    static AUTOLOAD_CACHE: RefCell<HashMap<String, Gd<Node>>> = RefCell::new(HashMap::new());
+}
+
+/// Verifies that the current thread is the main thread.
+///
+/// Returns an error if called from a thread other than the main thread. This is necessary because `Gd<T>` is not thread-safe.
+fn ensure_main_thread() -> Result<(), ConvertError> {
+    if is_main_thread() {
+        Ok(())
+    } else {
+        Err(ConvertError::new(
+            "Autoloads must be fetched from main thread, as Gd<T> is not thread-safe",
+        ))
+    }
+}
+
+/// Casts an autoload node to the requested type, with descriptive error message on failure.
+fn cast_autoload<T>(node: Gd<Node>, autoload_name: &str) -> Result<Gd<T>, ConvertError>
+where
+    T: Inherits<Node>,
+{
+    node.try_cast::<T>().map_err(|node| {
+        let expected = T::class_id();
+        let actual = node.get_class();
+
         ConvertError::new(format!(
-            "autoload `{autoload_name}` not found or has wrong type (expected {class})",
+            "autoload `{autoload_name}` has wrong type (expected {expected}, got {actual})",
         ))
     })
 }
+
+/// Clears the autoload cache (called during shutdown).
+///
+/// # Panics
+/// Panics if called from a thread other than the main thread.
+pub(crate) fn clear_autoload_cache() {
+    ensure_main_thread().expect("clear_autoload_cache() must be called from the main thread");
+
+    AUTOLOAD_CACHE.with(|cache| {
+        cache.borrow_mut().clear();
+    });
+}

godot-core/src/tools/mod.rs

@@ -19,3 +19,9 @@ pub use autoload::*;
 pub use gfile::*;
 pub use save_load::*;
 pub use translate::*;
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+pub(crate) fn cleanup() {
+    clear_autoload_cache();
+}

itest/rust/src/engine_tests/autoload_test.rs

@@ -9,7 +9,7 @@ use godot::classes::Node;
 use godot::prelude::*;
 use godot::tools::{get_autoload_by_name, try_get_autoload_by_name};
 
-use crate::framework::itest;
+use crate::framework::{itest, quick_thread};
 
 #[derive(GodotClass)]
 #[class(init, base=Node)]
@@ -65,3 +65,28 @@ fn autoload_try_get_named_bad_type() {
     let result = try_get_autoload_by_name::<Node2D>("MyAutoload");
     result.expect_err("autoload of incompatible node type");
 }
+
+#[itest]
+fn autoload_from_other_thread() {
+    use std::sync::{Arc, Mutex};
+
+    // We can't return the Result from the thread because Gd<T> is not Send, so we extract the error message instead.
+    let outer_error = Arc::new(Mutex::new(String::new()));
+    let inner_error = Arc::clone(&outer_error);
+
+    quick_thread(move || {
+        let result = try_get_autoload_by_name::<AutoloadClass>("MyAutoload");
+        match result {
+            Ok(_) => panic!("autoload access from non-main thread should fail"),
+            Err(err) => {
+                *inner_error.lock().unwrap() = err.to_string();
+            }
+        }
+    });
+
+    let msg = outer_error.lock().unwrap();
+    assert_eq!(
+        *msg,
+        "Autoloads must be fetched from main thread, as Gd<T> is not thread-safe"
+    );
+}