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

Also make methods inherent on `Gd`, not through dubious `UniformObjectDeref` + `ToSignalObj` trait impls.

Author: Bromeon

godot-core/src/obj/call_deferred.rs

@@ -5,64 +5,95 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use std::ops::DerefMut;
-
-use godot_ffi::is_main_thread;
-
-use crate::builtin::{Callable, Variant};
-use crate::meta::UniformObjectDeref;
-use crate::obj::bounds::Declarer;
-use crate::obj::GodotClass;
-use crate::registry::signal::ToSignalObj;
+use crate::obj::{Gd, GodotClass, WithBaseField};
 
 // TODO(v0.4): seal this and similar traits.
 
-/// Enables `Gd::apply_deferred()` for type-safe deferred calls.
+/// Enables deferred execution for user classes containing a `Base<T>` field.
+///
+/// This trait provides `run_deferred()` and `run_deferred_gd()` methods for user class instances.
+/// For `Gd<T>` instances, use the inherent methods [`Gd::run_deferred()`] and [`Gd::run_deferred_gd()`] instead.
 ///
-/// The trait is automatically available for all engine-defined Godot classes and user classes containing a `Base<T>` field.
+/// The trait is automatically available for user classes containing a `Base<T>` field.
 ///
 /// # Usage
 ///
 /// ```no_run
 /// # use godot::prelude::*;
-/// # use std::f32::consts::PI;
-/// fn some_fn(mut node: Gd<Node2D>) {
-///     node.apply_deferred(|n: &mut Node2D| n.rotate(PI))
+/// #
+/// #[derive(GodotClass)]
+/// #[class(init, base=Node2D)]
+/// struct MyNode {
+///     base: Base<Node2D>,
+/// }
+///
+/// #[godot_api]
+/// impl MyNode {
+///     fn some_method(&mut self) {
+///         self.run_deferred(|this: &mut MyNode| {
+///             // Direct access to Rust struct.
+///         });
+///
+///         self.run_deferred_gd(|gd: Gd<MyNode>| {
+///             // Access to Gd. Needs bind/bind_mut for struct access.
+///         });
+///     }
 /// }
 /// ```
-pub trait WithDeferredCall<T: GodotClass> {
+pub trait WithDeferredCall: GodotClass + WithBaseField {
     /// 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.
+    ///
     /// # Panics
     /// If called outside the main thread.
+    fn run_deferred<F>(&mut self, mut_self_method: F)
+    where
+        F: FnOnce(&mut Self) + 'static;
+
+    /// 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.
+    ///
+    /// # Panics
+    /// If called outside the main thread.
+    fn run_deferred_gd<F>(&mut self, gd_function: F)
+    where
+        F: FnOnce(Gd<Self>) + 'static;
+
+    #[deprecated(
+        since = "0.4.0",
+        note = "Split into `run_deferred()` + `run_deferred_gd`"
+    )]
     fn apply_deferred<F>(&mut self, rust_function: F)
     where
-        F: FnOnce(&mut T) + 'static;
+        F: FnOnce(&mut Self) + 'static,
+    {
+        self.run_deferred(rust_function)
+    }
 }
 
-impl<T, S, D> WithDeferredCall<T> for S
+impl<T> WithDeferredCall for T
 where
-    T: UniformObjectDeref<D, Declarer = D>,
-    S: ToSignalObj<T>,
-    D: Declarer,
+    T: WithBaseField,
 {
-    fn apply_deferred<'a, F>(&mut self, rust_function: F)
+    fn run_deferred<F>(&mut self, mut_self_method: F)
     where
-        F: FnOnce(&mut T) + 'static,
+        F: FnOnce(&mut Self) + 'static,
     {
-        assert!(
-            is_main_thread(),
-            "`apply_deferred` must be called on the main thread"
-        );
+        // 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)
+    }
 
-        let mut this = self.to_signal_obj().clone();
-        let callable = Callable::from_once_fn("apply_deferred", move |_| {
-            let mut this_mut = T::object_as_mut(&mut this);
-            rust_function(this_mut.deref_mut());
-            Ok(Variant::nil())
-        });
-        callable.call_deferred(&[]);
+    fn run_deferred_gd<F>(&mut self, gd_function: F)
+    where
+        F: FnOnce(Gd<Self>) + 'static,
+    {
+        self.to_gd().run_deferred_gd(gd_function)
     }
 }

godot-core/src/obj/gd.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,54 @@ 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 T` 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.
+    ///
+    /// # 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 a `Gd<T>` which can be used to call engine methods.
+    /// This method works for any Godot class (engine or user-defined).
+    ///
+    /// # 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-macros/src/class/data_models/signal.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.

itest/rust/src/object_tests/call_deferred_test.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()
 }