feat(core): support easier, type-safe deferred calls

Author: goatfryed

godot-core/src/obj/call_deferred.rs

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+use crate::builtin::{Callable, Variant};
+use crate::meta::UniformObjectDeref;
+use crate::obj::bounds::Declarer;
+use crate::obj::GodotClass;
+#[cfg(since_api = "4.2")]
+use crate::registry::signal::ToSignalObj;
+use godot_ffi::is_main_thread;
+use std::ops::DerefMut;
+
+// Dummy traits to still allow bounds and imports.
+#[cfg(before_api = "4.2")]
+pub trait WithDeferredCall<T: GodotClass> {}
+
+/// Trait that is automatically implemented for engine classes and  user classes containing a `Base<T>` field.
+///
+/// This trait enables type safe deferred method calls.
+///
+/// # Usage
+///
+/// ```no_compile
+/// # use godot::prelude::*;
+/// # use godot::classes::CollisionShape2D;
+/// # use std::f32::consts::PI;
+/// fn some_fn(mut node: Gd<Node2D>)
+/// {
+///     node.apply_deferred(|shape_mut| shape_mut.rotate(PI))
+/// }
+/// ```
+#[cfg(since_api = "4.2")]
+pub trait WithDeferredCall<T: GodotClass> {
+    /// Runs the given Closure deferred.
+    ///
+    /// This can be a type-safe alternative to [`Object::call_deferred`][crate::classes::Object::call_deferred]. This method must be used on the main thread.
+    fn apply_deferred<F>(&mut self, rust_function: F)
+    where
+        F: FnMut(&mut T) + 'static;
+}
+
+#[cfg(since_api = "4.2")]
+impl<T, S, D> WithDeferredCall<T> for S
+where
+    T: UniformObjectDeref<D, Declarer = D>,
+    S: ToSignalObj<T>,
+    D: Declarer,
+{
+    fn apply_deferred<'a, F>(&mut self, mut rust_function: F)
+    where
+        F: FnMut(&mut T) + 'static,
+    {
+        assert!(
+            is_main_thread(),
+            "`apply_deferred` must be called on the main thread"
+        );
+        let mut this = self.to_signal_obj().clone();
+        let callable = Callable::from_local_fn("apply_deferred", move |_| {
+            rust_function(T::object_as_mut(&mut this).deref_mut());
+            Ok(Variant::nil())
+        });
+        callable.call_deferred(&[]);
+    }
+}

godot-core/src/obj/mod.rs

@@ -12,6 +12,7 @@
 //! * [`Gd`], a smart pointer that manages instances of Godot classes.
 
 mod base;
+mod call_deferred;
 mod dyn_gd;
 mod gd;
 mod guards;
@@ -24,6 +25,7 @@ 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};
@@ -35,6 +37,7 @@ pub use traits::*;
 
 pub mod bounds;
 pub mod script;
+
 pub use bounds::private::Bounds;
 
 // Do not re-export rtti here.

godot-ffi/src/lib.rs

@@ -435,7 +435,6 @@ pub fn main_thread_id() -> std::thread::ThreadId {
 ///
 /// # Panics
 /// - If it is called before the engine bindings have been initialized.
-///
 pub fn is_main_thread() -> bool {
     #[cfg(not(wasm_nothreads))]
     {

godot/src/prelude.rs

@@ -36,5 +36,6 @@ pub use super::obj::EngineEnum as _;
 pub use super::obj::NewAlloc as _;
 pub use super::obj::NewGd as _;
 pub use super::obj::WithBaseField as _; // base(), base_mut(), to_gd()
+pub use super::obj::WithDeferredCall as _;
 pub use super::obj::WithSignals as _; // Gd::signals()
 pub use super::obj::WithUserSignals as _; // self.signals()

itest/rust/src/object_tests/call_deferred_test.rs

@@ -4,72 +4,107 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
-
 use crate::framework::itest;
-use crate::object_tests::call_deferred_test::TestState::{Accepted, Initial};
+use godot::obj::WithBaseField;
 use godot::prelude::*;
 use godot::task::{SignalFuture, TaskHandle};
+use std::ops::DerefMut;
 
-#[derive(GodotConvert, Var, Export, Clone, PartialEq, Debug)]
-#[godot(via = GString)]
-enum TestState {
-    Initial,
-    Accepted,
-}
+const ACCEPTED_NAME: &str = "touched";
 
 #[derive(GodotClass)]
-#[class(base=Node)]
+#[class(init,base=Node2D)]
 struct DeferredTestNode {
-    base: Base<Node>,
-    state: TestState,
+    base: Base<Node2D>,
 }
 
 #[godot_api]
 impl DeferredTestNode {
     #[signal]
-    fn test_completed(state: TestState);
+    fn test_completed(name: StringName);
 
     #[func]
     fn accept(&mut self) {
-        self.state = Accepted;
+        self.base_mut().set_name(ACCEPTED_NAME);
     }
 
-    fn as_expectation_task(&self) -> TaskHandle {
-        assert_eq!(Initial, self.state, "accept evaluated synchronously");
+    fn to_assertion_task(&self) -> TaskHandle {
+        assert_ne!(
+            self.base().get_name().to_string(),
+            ACCEPTED_NAME,
+            "accept evaluated synchronously"
+        );
 
-        let test_will_succeed: SignalFuture<(Variant,)> =
+        let test_will_succeed: SignalFuture<(StringName,)> =
             Signal::from_object_signal(&self.to_gd(), "test_completed").to_future();
+
         godot::task::spawn(async move {
-            let (final_state,) = test_will_succeed.await;
-            let final_state: TestState = final_state.to();
+            let (name,) = test_will_succeed.await;
 
-            assert_eq!(Accepted, final_state);
+            assert_eq!(name.to_string(), ACCEPTED_NAME);
         })
     }
 }
 
 #[godot_api]
-impl INode for DeferredTestNode {
-    fn init(base: Base<Self::Base>) -> Self {
-        Self {
-            base,
-            state: Initial,
-        }
+impl INode2D for DeferredTestNode {
+    fn process(&mut self, _delta: f64) {
+        let name = self.base().get_name();
+        self.signals().test_completed().emit(&name);
+        self.base_mut().queue_free();
     }
 
-    fn process(&mut self, _delta: f64) {
-        let args = vslice![self.state];
-        self.base_mut().emit_signal("test_completed", args);
+    fn ready(&mut self) {
+        self.base_mut().set_name("verify")
     }
 }
 
 #[itest(async)]
-fn calls_method_names_deferred(ctx: &crate::framework::TestContext) -> TaskHandle {
+fn call_deferred_untyped(ctx: &crate::framework::TestContext) -> TaskHandle {
     let mut test_node = DeferredTestNode::new_alloc();
     ctx.scene_tree.clone().add_child(&test_node);
-    
+
+    // this is called through godot binding and therefore requires #[func] on the method
     test_node.call_deferred("accept", &[]);
 
-    let handle = test_node.bind().as_expectation_task();
+    let handle = test_node.bind().to_assertion_task();
+    handle
+}
+
+#[itest(async)]
+fn call_deferred_godot_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();
+    // 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);
+    drop(gd_mut);
+
+    let handle = test_node.bind().to_assertion_task();
+    handle
+}
+
+#[itest(async)]
+fn call_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);
+
+    let handle = test_node.bind().to_assertion_task();
+    handle
+}
+
+#[itest(async)]
+fn call_deferred_gd_engine_class(ctx: &crate::framework::TestContext) -> TaskHandle {
+    let 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));
+
+    let handle = test_node.bind().to_assertion_task();
     handle
 }