Adding future and deferred documentation

[bitterepic]

The problem this PR is trying to solve:

1. More complete documentation.
2. For people going through the godot game tutorials , searching for keywords will return meaninful results.

Example:

The proposed solution

This PR proposes a new Futures and Deferred Functions section to help explain async in rust-godot. There was a lot of work to related functionality for typesafe deferred function calls and futures... we should show it off in the documentation!

Feedback welcome! This is just a draft for now! Thank you for your time!

[Bromeon]

Thanks a lot for your contribution! I think this is a great addition to the book.

Some comments:

1. Title should probably be "Async programming" or so; there may be more additions in the future.

2. Formatting and linting:

   • Please use the available line lenghts of 130-150 characters, see how other pages do it.
   • Lints should pass, see https://github.com/godot-rust/book#formatting-and-linting.
   • Same for license.
   • If possible, run a spellchecker or AI review, there are a few grammar/orthography mistakes. (To be clear I'm not suggesting to let AI rewrite things, the human formulations are great. More about giving feedback so we don't have to manually go through each instance).

3. The "Using the Godot API" section is for very basic things, while this is rather advanced. You're also referencing concepts like signals that haven't yet been explained. For now I would move this down to the "Recipes" section -- we should probably reorganize that to "Advanced topics" or so later.

[Bromeon]

Please only use exclamation marks in rare circumstances when attention is absolutely required. Inflationary use seems overly dramatic and can disrupt the reading flow. This also applies to many other places on the page. I think most of the current ! could just be . instead.

Here it's also not clear what "FAIL" even means. Does it not compile? Crash at runtime? Comments should be more descriptive.

Furthermore, object_to_owned is an extremely niche API mostly used by signal internals. Can this problem be demonstrated by a more common API, that the user is likely to have come across by the time of reading this page?

[bitterepic]

I think so. There is to the to_gd method. Or alternatively we can drop this section if you don't think it is needed.

[Bromeon]

This is very vague:

• First, the causality "Rust + Godot separate" -> "deadlock" is misleading, what's the logical step here?
• This doesn't offer any concrete advice on avoiding deadlocks. "Be thoughtful" is not really helpful 🙂

Since there is an example following this, shouldn't this be regular text rather than an admonition? The text could then introduce the example rather than make vague statements.

[bitterepic]

Let's try to regular text that also crossed my mind.

[TitanNano]

Because the Godot engine is running separate of Rust

This is not very accurate. Both Rust and Godot run in the same process and even in the same thread. This is why the future can't make any progress when you block the thread waiting for the future.

[bitterepic]

Yup, thank you for pointing this out! I have unverified word mush here that I will iterate on and add this.

Speaking of broken promises, my screenshot example also isn't being fulfilled yet. I don't use the word set_deferred anywhere in this documentation so it will still show as not found.

[bitterepic]

@Bromeon It sounds like you are interested in this section, so I'll give this PR a clean up while also adding your suggestions.

[bitterepic]

I'm hoping to have a new iteration out on this this evening JST.

@Bromeon Regarding connect_other, in a separate PR would you like me to look into if I can make it also accept a Gd? Or would you prefer me to keep the example using the builder's connect_other_gd in this documentation?

[Bromeon]

@Bromeon Regarding connect_other, in a separate PR would you like me to look into if I can make it also accept a Gd? Or would you prefer me to keep the example using the builder's connect_other_gd in this documentation?

As mentioned here, does this really add something in the context of async programming, or is it more distracting? The subtleties of signal APIs are already explained in quite some detail in API docs, including connect_other_gd 🤔

In other words, the book's purpose is to be an introductory guide / tutorial for people learning the library, and it does not strive to exhaustively cover the API. That part is the responsibility of our API docs.

---

Please also fix the CI, then we can give this a review 🙂

[bitterepic]

@Bromeon Regarding connect_other, in a separate PR would you like me to look into if I can make it also accept a Gd? Or would you prefer me to keep the example using the builder's connect_other_gd in this documentation?

As mentioned here, does this really add something in the context of async programming, or is it more distracting? The subtleties of signal APIs are already explained in quite some detail in API docs, including connect_other_gd 🤔

In other words, the book's purpose is to be an introductory guide / tutorial for people learning the library, and it does not strive to exhaustively cover the API. That part is the responsibility of our API docs.

Please also fix the CI, then we can give this a review 🙂

I have no pride issues if the outcome of this PR is to close it. I think the other possible outcome is that this documentation doesn't belong here.

Let me post what I think are the for and against argument points of this PR because I think it will help the conversation.

Arguments

Against Argument Points

• The api doc has a detailed example so this PR is not needed.
• I think if the api doc example existed when I was looking for how to implement this it would have saved me a lot of time.
• Previous conversations that I found here were that the C# plugin didn't support async/await so it wasn't prioritized for the rust plugin
• There are async libraries in this ecosystem and we don't want to choose sides

For Argument Points

• It makes sense to cover material in the godot-rust book that is also covered in the official godot docs being careful to not cover more.
• async/await is likely only to grow in popularity like it has in other language ecosystems and people will be looking for it (as well as it is used in gdscript) so there is weight to it as a topic. (ex: how does this interact with Tokio?)
• Because there are many parts for doing async compared to GdScript (getting a Gd pointer, executing with a task), it may be worth to talk about why that is for the consumers of this library.

Potential Approaches

While it is possible to create a separate section in the docs, I think it is also possible to augment existing documentation similar to what we did with the api docs. For example,

The API docs should probably also mention and link run_deferred in these sections for set_deferred or call_deferred. This would mitigate the use case for adding this to the godot-book and would be discoverable by searching set_deferred or call_deferred.

Potential Plans of Action

• We can continue this PR or close it
• I can split out separate issues for
  • adding the run_deferred link to set_deferred/call_deferred
  • maybe making connect_other_gd accessable outside of the signal builder? See if an AsArg type solution is usable for accepting both Gd<T> and T for connect_self and connect_other?

Thoughts?

[Bromeon]

I have no pride issues if the outcome of this PR is to close it. I think the other possible outcome is that this documentation doesn't belong here.

To be clear, I was referring to specific signal APIs, not async. I agree that a page on async programming makes sense. But for people that are new to async (maybe also haven't used it in GDScript before), the topic is already complex enough, so discussing detailed signal connection nuances on the same page may not be in anyone's interest.

---

It makes sense to cover material in the godot-rust book that is also covered in the official godot docs being careful to not cover more.

I don't think this is a good criterion. There are plenty of topics that are Rust-specific and do not exist for Godot itself (the whole Gd lifetime management, typed signals, DynGd...). On the other hand repeating Godot-specific stuff in Rust is also not adding much value in general, unless our way of doing things is different -- like here for async.

---

The API docs should probably also mention and link run_deferred in these sections for set_deferred or call_deferred. This would mitigate the use case for adding this to the godot-book and would be discoverable by searching set_deferred or call_deferred.

I agree, this would be nice. Adding method-specific docs is already planned, but the mechanism in godot-codegen is not yet implemented. Once it is, this link to run_deferred should definitely be established.

---

Potential Plans of Action

I'm happy to continue this PR, but I would remove signal specifics that are not relevant for the understanding of async. Maybe use a very simple signal and link to API docs for more complex connection setups.

[bitterepic]

Thank you! I think this is enough feedback to do another iteration and clean this PR up.

[bitterepic]

@Bromeon I have applied the feedback and made the CI pass. I need to give the documentation one more look over for spelling/phasing before bringing this out of draft.

In my college days I learned that in writing it is more important to get your ideas together to verify them before digging into the weeds of spelling. The reason is you lose focus of the whole. Now in my later years, I also value it in that I don't waste as much time verifying spellchecking and style until I know I have something worth finishing. I don't have as much time nowadays as when I was in my 20s.

[bitterepic]

Regarding not using the timer signal and moving it to a recipe, I'm still brain storming on what to replace the async code with that would be simpler and obvious.

[bitterepic]

@Bromeon @TitanNano Thank you so much for the wait, this PR is now officially read for final review.