Merge pull request #1327 from godot-rust/qol/run-deferred

Split `apply_deferred()` -> `run_deferred()` + `run_deferred_gd()`

Author: Bromeon

godot-core/src/obj/call_deferred.rs

@@ -9,6 +9,7 @@ use std::fmt::{Debug, Display, Formatter, Result as FmtResult};
 use std::ops::{Deref, DerefMut};
 
 use godot_ffi as sys;
+use godot_ffi::is_main_thread;
 use sys::{static_assert_eq_size_align, SysPtr as _};
 
 use crate::builtin::{Callable, GString, NodePath, StringName, Variant};
@@ -19,7 +20,7 @@ use crate::meta::{
 };
 use crate::obj::{
     bounds, cap, Bounds, DynGd, GdDerefTarget, GdMut, GdRef, GodotClass, Inherits, InstanceId,
-    OnEditor, RawGd, WithSignals,
+    OnEditor, RawGd, WithBaseField, WithSignals,
 };
 use crate::private::{callbacks, PanicPayload};
 use crate::registry::class::try_dynify_object;
@@ -665,6 +666,55 @@ impl<T: GodotClass> Gd<T> {
         // Do not increment ref-count; assumed to be return value from FFI.
         sys::ptr_then(object_ptr, |ptr| Gd::from_obj_sys_weak(ptr))
     }
+
+    /// Defers the given closure to run during [idle time](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-call-deferred).
+    ///
+    /// This is a type-safe alternative to [`Object::call_deferred()`][crate::classes::Object::call_deferred]. The closure receives
+    /// `&mut Self` allowing direct access to Rust fields and methods.
+    ///
+    /// This method is only available for user-defined classes with a `Base<T>` field.
+    /// For engine classes, use [`run_deferred_gd()`][Self::run_deferred_gd] instead.
+    ///
+    /// See also [`WithBaseField::run_deferred()`] if you are within an `impl` block and have access to `self`.
+    ///
+    /// # Panics
+    /// If called outside the main thread.
+    pub fn run_deferred<F>(&mut self, mut_self_method: F)
+    where
+        T: WithBaseField,
+        F: FnOnce(&mut T) + 'static,
+    {
+        self.run_deferred_gd(move |mut gd| {
+            let mut guard = gd.bind_mut();
+            mut_self_method(&mut *guard);
+        });
+    }
+
+    /// Defers the given closure to run during [idle time](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-call-deferred).
+    ///
+    /// This is a type-safe alternative to [`Object::call_deferred()`][crate::classes::Object::call_deferred]. The closure receives
+    /// `Gd<T>`, which can be used to call engine methods or [`bind()`][Gd::bind]/[`bind_mut()`][Gd::bind_mut] to access the Rust object.
+    ///
+    /// See also [`WithBaseField::run_deferred_gd()`] if you are within an `impl` block and have access to `self`.
+    ///
+    /// # Panics
+    /// If called outside the main thread.
+    pub fn run_deferred_gd<F>(&mut self, gd_function: F)
+    where
+        F: FnOnce(Gd<T>) + 'static,
+    {
+        let obj = self.clone();
+        assert!(
+            is_main_thread(),
+            "`run_deferred` must be called on the main thread"
+        );
+
+        let callable = Callable::from_once_fn("run_deferred", move |_| {
+            gd_function(obj);
+            Ok(Variant::nil())
+        });
+        callable.call_deferred(&[]);
+    }
 }
 
 /// _The methods in this impl block are only available for objects `T` that are manually managed,

godot-core/src/obj/gd.rs

@@ -12,7 +12,6 @@
 //! * [`Gd`], a smart pointer that manages instances of Godot classes.
 
 mod base;
-mod call_deferred;
 mod casts;
 mod dyn_gd;
 mod gd;
@@ -27,7 +26,6 @@ mod traits;
 pub(crate) mod rtti;
 
 pub use base::*;
-pub use call_deferred::WithDeferredCall;
 pub use dyn_gd::DynGd;
 pub use gd::*;
 pub use guards::{BaseMut, BaseRef, DynGdMut, DynGdRef, GdMut, GdRef};

godot-core/src/obj/mod.rs

@@ -540,6 +540,40 @@ pub trait WithBaseField: GodotClass + Bounds<Declarer = bounds::DeclUser> {
         // Narrows lifetime again from 'static to 'self.
         BaseMut::new(passive_gd, guard)
     }
+
+    /// Defers the given closure to run during [idle time](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-call-deferred).
+    ///
+    /// This is a type-safe alternative to [`Object::call_deferred()`][crate::classes::Object::call_deferred]. The closure receives
+    /// `&mut Self` allowing direct access to Rust fields and methods.
+    ///
+    /// See also [`Gd::run_deferred()`] to defer logic outside of `self`.
+    ///
+    /// # Panics
+    /// If called outside the main thread.
+    fn run_deferred<F>(&mut self, mut_self_method: F)
+    where
+        F: FnOnce(&mut Self) + 'static,
+    {
+        // We need to copy the Gd, because the lifetime of `&mut self` does not extend throughout the closure, which will only be called
+        // deferred. It might even be freed in-between, causing panic on bind_mut().
+        self.to_gd().run_deferred(mut_self_method)
+    }
+
+    /// Defers the given closure to run during [idle time](https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-call-deferred).
+    ///
+    /// This is a type-safe alternative to [`Object::call_deferred()`][crate::classes::Object::call_deferred]. The closure receives
+    /// `Gd<Self>`, which can be used to call engine methods or [`bind()`][Gd::bind]/[`bind_mut()`][Gd::bind_mut] to access the Rust object.
+    ///
+    /// See also [`Gd::run_deferred_gd()`] to defer logic outside of `self`.
+    ///
+    /// # Panics
+    /// If called outside the main thread.
+    fn run_deferred_gd<F>(&mut self, gd_function: F)
+    where
+        F: FnOnce(Gd<Self>) + 'static,
+    {
+        self.to_gd().run_deferred_gd(gd_function)
+    }
 }
 
 /// Implemented for all classes with registered signals, both engine- and user-declared.

godot-core/src/obj/traits.rs

@@ -422,7 +422,7 @@ fn make_signal_symbols(
     // Earlier implementation generated a simplified code when no #[signal] was declared: only WithSignals/WithUserSignals impl, but no own
     // collection, instead the associated type pointing to the base class. This has however some problems:
     // * Part of the reason for user-defined collection is to store UserSignalObject instead of Gd, which can store &mut self.
-    //   This is necessary for self.signals().some_base_signal().emit(), if such a signal is connected to Self::method_mut;
+    //   This is necessary for self.signals().some_base_signal().emit(), if such a signal is connected to Self::connect*() taking &mut self;
     //   Gd would cause a borrow error.
     // * Once we add Rust-Rust inheritance, we'd need to differentiate case again, which can be tricky since #[godot_api] has no information
     //   about the base class.

godot-macros/src/class/data_models/signal.rs

@@ -33,8 +33,7 @@ mod trait_reexports {
     pub use crate::obj::EngineEnum as _;
     pub use crate::obj::NewAlloc as _;
     pub use crate::obj::NewGd as _;
-    pub use crate::obj::WithBaseField as _; // base(), base_mut(), to_gd()
-    pub use crate::obj::WithDeferredCall as _; // apply_deferred()
+    pub use crate::obj::WithBaseField as _; // base(), base_mut(), to_gd(), run_deferred(), run_deferred_gd()
     pub use crate::obj::WithSignals as _; // Gd::signals()
     pub use crate::obj::WithUserSignals as _; // self.signals()
 }

godot/src/prelude.rs

@@ -31,6 +31,10 @@ impl DeferredTestNode {
         self.base_mut().set_name(ACCEPTED_NAME);
     }
 
+    fn accept_gd(mut this: Gd<Self>) {
+        this.set_name(ACCEPTED_NAME);
+    }
+
     fn create_assertion_task(&mut self) -> TaskHandle {
         assert_ne!(
             self.base().get_name().to_string(),
@@ -69,42 +73,43 @@ fn call_deferred_untyped(ctx: &crate::framework::TestContext) -> TaskHandle {
     // Called through Godot and therefore requires #[func] on the method.
     test_node.call_deferred("accept", &[]);
 
-    let mut gd_mut = test_node.bind_mut();
-    gd_mut.create_assertion_task()
+    let mut guard = test_node.bind_mut();
+    guard.create_assertion_task()
 }
 
 #[itest(async)]
-fn call_deferred_godot_class(ctx: &crate::framework::TestContext) -> TaskHandle {
+fn run_deferred_user_class(ctx: &crate::framework::TestContext) -> TaskHandle {
     let mut test_node = DeferredTestNode::new_alloc();
     ctx.scene_tree.clone().add_child(&test_node);
 
-    let mut gd_mut = test_node.bind_mut();
+    let mut guard = test_node.bind_mut();
+
     // Explicitly check that this can be invoked on &mut T.
-    let godot_class_ref: &mut DeferredTestNode = gd_mut.deref_mut();
-    godot_class_ref.apply_deferred(DeferredTestNode::accept);
+    let godot_class_ref: &mut DeferredTestNode = guard.deref_mut();
+    godot_class_ref.run_deferred(DeferredTestNode::accept);
 
-    gd_mut.create_assertion_task()
+    guard.create_assertion_task()
 }
 
 #[itest(async)]
-fn call_deferred_gd_user_class(ctx: &crate::framework::TestContext) -> TaskHandle {
+fn run_deferred_gd_user_class(ctx: &crate::framework::TestContext) -> TaskHandle {
     let mut test_node = DeferredTestNode::new_alloc();
     ctx.scene_tree.clone().add_child(&test_node);
 
-    test_node.apply_deferred(DeferredTestNode::accept);
+    test_node.run_deferred_gd(DeferredTestNode::accept_gd);
 
-    let mut gd_mut = test_node.bind_mut();
-    gd_mut.create_assertion_task()
+    let mut guard = test_node.bind_mut();
+    guard.create_assertion_task()
 }
 
 #[itest(async)]
-fn call_deferred_gd_engine_class(ctx: &crate::framework::TestContext) -> TaskHandle {
+fn run_deferred_engine_class(ctx: &crate::framework::TestContext) -> TaskHandle {
     let mut test_node = DeferredTestNode::new_alloc();
     ctx.scene_tree.clone().add_child(&test_node);
 
     let mut node = test_node.clone().upcast::<Node>();
-    node.apply_deferred(|that_node| that_node.set_name(ACCEPTED_NAME));
+    node.run_deferred_gd(|mut that_node| that_node.set_name(ACCEPTED_NAME));
 
-    let mut gd_mut = test_node.bind_mut();
-    gd_mut.create_assertion_task()
+    let mut guard = test_node.bind_mut();
+    guard.create_assertion_task()
 }