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

Author: goatfryed

godot-core/src/obj/call_deferred.rs

@@ -0,0 +1,73 @@
+/*
+ * 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> {}
+
+/// Enables `Gd::apply_deferred()` for type-safe deferred calls.
+///
+/// The trait is automatically available for all engine-defined Godot classes and 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))
+/// }
+/// ```
+#[cfg(since_api = "4.2")]
+pub trait WithDeferredCall<T: GodotClass> {
+    /// 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].
+    ///
+    /// # Panics
+    /// If called outside the main thread.
+    fn apply_deferred<F>(&mut self, rust_function: F)
+    where
+        F: FnOnce(&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, rust_function: F)
+    where
+        F: FnOnce(&mut T) + 'static,
+    {
+        assert!(
+            is_main_thread(),
+            "`apply_deferred` must be called on the main thread"
+        );
+        let mut rust_fn_once = Some(rust_function);
+        let mut this = self.to_signal_obj().clone();
+        let callable = Callable::from_local_fn("apply_deferred", move |_| {
+            let rust_fn_once = rust_fn_once
+                .take()
+                .expect("rust_fn_once was already consumed");
+            let mut this_mut = T::object_as_mut(&mut this);
+            rust_fn_once(this_mut.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 casts;
 mod dyn_gd;
 mod gd;
@@ -25,6 +26,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};

godot-core/src/registry/signal/typed_signal.rs

@@ -16,6 +16,7 @@ use std::borrow::Cow;
 use std::marker::PhantomData;
 use std::ops::DerefMut;
 
+// TODO(v0.4): find more general name for trait.
 /// Object part of the signal receiver (handler).
 ///
 /// Functionality overlaps partly with [`meta::AsObjectArg`] and [`meta::AsArg<ObjectArg>`]. Can however not directly be replaced

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 _; // apply_deferred()
 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

@@ -8,6 +8,7 @@ use crate::framework::itest;
 use godot::obj::WithBaseField;
 use godot::prelude::*;
 use godot::task::{SignalFuture, TaskHandle};
+use std::ops::DerefMut;
 
 const ACCEPTED_NAME: &str = "touched";
 
@@ -68,3 +69,39 @@ fn call_deferred_untyped(ctx: &crate::framework::TestContext) -> TaskHandle {
     let mut gd_mut = test_node.bind_mut();
     gd_mut.create_assertion_task()
 }
+
+#[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);
+
+    gd_mut.create_assertion_task()
+}
+
+#[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 mut gd_mut = test_node.bind_mut();
+    gd_mut.create_assertion_task()
+}
+
+#[itest(async)]
+fn call_deferred_gd_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));
+
+    let mut gd_mut = test_node.bind_mut();
+    gd_mut.create_assertion_task()
+}