Type-Safe deferred method calls

[goatfryed]

I think deferred method calls could be improved. I'd like to propose the introduction of a deferred() helper struct similar to signals() as introduced in #1000

So the following

#[func]
pub fn do_something(&mut self, my_resource: Gd<MyResource>)

could allow to do something like this

//  call method deferred
self.deferred().do_something(my_resource);

// or maybe even async
self.deferred().do_something(my_resource).await;

and would improve the less type-safe and more verbose syntax of

self.base_mut().call_deferred("do_something", &[my_resource.to_variant()])

As I understand it, `#[func]' already tells us, which methods can be deferred, but since visibility of godot and rust is orthogonal, it should require both here.

Maybe this could even integrate with the signals api somehow to make setup of deferred signals less verbose.

Maybe it's just the way I program and that can be improved, but I use a lot of deferred method calls, when processing game state.

[goatfryed]

I'm quite new to rust and I use godot-rust to familiarize myself with it. If this fits the project goals and we can agree on an api, I see this as an interesting challenge for myself to learn rust and I'd like to contribute a PR at a later point.

[Bromeon]

Thanks for the proposal! It goes a bit in a similar direction as typed RPCs (#1158).

The big challenge here is to avoid duplicating the entire class API. All the potential do_something() methods would need to map somehow to the real ones via call_deferred.

I have an idea: what about a declarative macro

call_deferred! {
    self.do_something(my_resource, 42, "yes");
}

which expands to the following expression, which has always unit type ():

if (false) {
    // This branch never runs, but exists for type-check.
    self.do_something(my_resource, 42, "yes");
} else {
    // Actual invocation here.
    self.call_deferred("do_something", vslice![my_resource, 42, "yes"]);
}

The type checks would encompass both existence of the method and number + types of arguments. It could be made a bit more flexible to support also non-self invocations.

[goatfryed]

Looks like a nice solution.

I double checked, if there is any valid concern regarding return value, which would make the branching trick more difficult. The official signature returns variant, but godot officially documents that call_deferred always returns nil and there is even godotengine/godot#95491. So this isn't even any limitiation or edge case.

Would we support multiple method call statements in the block expression or just one? To do the transformation once or multiple times shouldn't be an issue, but then users might write other statements in the block and this could lead to confusion or increased complexity. So I'd atleast support method call expressions and block statements containing a single method call expression initially.

If we do this, we don't verify #[func] was used on the method and if I understand the macro system and right, that's not possible. Correct? For me personally, typing is far more important, since it can change later on through refactoring. The missing attribute would be caught early enough on initial setup, so having that is only a minor benefit.

[Houtamelo]

// call method deferred
self.deferred().do_something(my_resource);

This isn't doable without doubling the code size of the entire project. It works for the signal api because signals have one type for each signature, doing the same for regular methods would also require creating one type for each method.

---

Aside from what @Bromeon suggested, the next thing that comes to mind is a simple map-like function:

self.map_deferred(|this: &mut Self| {
     // do whatever     
});

Which would be syntax sugar for:

let callable = Callable::from_local_fn(|args| {
    let mut self_gd = args[0].to::<Gd<Self>>();
    let mut self_mut = self_gd.bind_mut();
    // do whatever
});

callable.call_deferred(&[self.to_gd().to_variant()]);

[Bromeon]

Would we support multiple method call statements in the block expression or just one? To do the transformation once or multiple times shouldn't be an issue, but then users might write other statements in the block and this could lead to confusion or increased complexity. So I'd atleast support method call expressions and block statements containing a single method call expression initially.

I was thinking about that before, but you make a good point with in-between statements. If we go with the macro solution, I agree we should start with one call per macro invocation, we can always extend it.

---

If we do this, we don't verify #[func] was used on the method and if I understand the macro system and right, that's not possible. Correct?

Good observation. We dealt with a related issue in #1019: making #[func] emit a constant that contained the Godot name of the function (since #[func(rename = ...)] can change it). Accessing that constant inside the macro should be relatively easy to do and effectively limit to #[func], but it would also mean we could no longer call any engine APIs in deferred mode.

In your use case, are all deferred calls going to user-defined #[func]s?

---

Aside from what @Bromeon suggested, the next thing that comes to mind is a simple map-like function:

Also a great idea, and more aspect-like. More flexible by supporting ad-hoc closures and non-#[func] for deferring. Has a small runtime overhead due to Callable indirection. Not sure if there is any nuance between Callable::call_deferred and Object::call_deferred.

---

Opinions on the two approaches? 🙂

Whatever we choose, I'd say if @goatfryed is interested in tackling the Rust challenge, we should give him precedence for a potential PR 💪

[Bromeon]

Any opinions here?

[TitanNano]

Any opinions here?

I think there would be two versions of the macro required: One for Self: GodotClass and one for Gd<T> because one time the call_deferred has to be called on the base.

So i prefer @Houtamelo s suggestion. It looks more versatile.

[goatfryed]

Would you assign the issue to me? Let's go with @Houtamelo 's suggestion. I'll provide a PR

I'd only nitpick and call it apply_deferred instead, since map raises the expectation to return a value and continue processing with the transformed value

[Bromeon]

Yes, I don't think it should be map_deferred either, I think Houtamelo meant mostly that it follows the style of such functions. Not 100% sure about apply either, but this is a minor detail we can always discuss later. Thanks for volunteering! 🙂