[discussion] Async-await support

Goal

The Godot API is rich in asynchronousness with its many signals. The interface is easy for GDScript to consume, in coroutines with the yield function, but not very wieldy in Rust. Async-await may help close this gap. Wel want to be able to write something like this in Rust:

// Provisional API
#[export(spawn = "local")] // Indicates that the future will be spawned on a local executor, explained below
async fn my_coroutine(&self, owner: Node, anim: AnimationPlayer) -> String {
    use gdnative::async_yield::Yield;
    // - snip -
    Yield::new(anim, "animation_finished").await;
    // - snip -
    "foo".into()
}

And be able to consume it in GDScript like this:

func foo(node):
    # - snip -
    var result = yield(node.my_coroutine(get_node("anim")), "completed")
    print(result) # outputs "foo"

Proposed implementation

To accomplish this, there are four parts that need to be implemented, at minimum:

• The Yield Future itself. This should just be a thin wrapper around a Waker.
• A NativeClass singleton that acts as a bridge between signals and Wakers (only NativeClasses can connect to signals, and giving each Yield its own instance would be too expensive).
• A NativeClass that wraps around boxed Futures and exposes resume and a completed signal, analogous to GDScriptFunctionState.
• Support for async methods in the proc-macro.

For this feature to work, two supportive NativeClass types need to be registered. It should be easiest for the users that we put the types behind a (optionally optional) async_yield feature, and automatically register them on init if the feature enabled. If we give sufficiently long and specific names to these types, I think we can safely pray that collisions won't happen. The proc-macro can emit errors when async methods are encountered, if the feature flag is not enabled.

Executor to use

Futures are lazy and require an executor to actually progress. The futures crate implements both a multi-thread executor and a single-thread one that we can use. However, both of them have some problems:

ThreadPool can be used without manual intervention, but don't play well with Godot's generally thread-unsafe API. LocalPool should enable more ergonomic async functions, but needs to be polled from a Node, which have to be manually put into the scene tree by the user, and has serious performance implications. Both options are not very ideal as a default.

As such, we have to require the users to provide their own executors in their init functions, and not provide a default:

// Provisional API
fn init(handle: init::InitHandle) {
    // - snip -
    gdnative::async_yield::set_spawner(Box::new(ThreadPool::new().unwrap());
    gdnative::async_yield::set_local_spawner(Box::new(MY_LOCAL_POOL.spawner()));
}

// in a Node far, far away
#[export]
fn _process(&self, _owner: Node) {
    // this certainly won't just compile, but essentially do something in the spirit of:
    MY_LOCAL_POOL.run_until_stalled();
}

Unresolved questions

The feature should be reasonably useful, and the implementation itself should be fairly straightforward, but there are several problems I have with the current provisional API:

• The proposed module name and feature flag being async_yield. I don't think it's very good, but async and yield are keywords and can't be used. futures sound a bit too broad, on the other hand.
• The spawners being global. Alternatively spawners can be specified for each method individually using the attribute, but it doesn't feel very useful.
• The spawn = "local" attribute argument. I feel it can be a bit confusing, but something like it is necessary since the methods in Spawn and LocaSpawn are named differently, and a macro has no way to tell whether the resulting Future will be Send.

Opinions are very appreciated!

[karroffel]

I think it is a great idea to use async/await to implement GDScript's yield functionaliy!

I wonder if we need a general purpose executor. I think in GDScript there is a separate Object (or just method) that connects to a signal. If the signal is fired then the code after the yield get executed until the function execution is done or another yield was encountered.

So I don't think we need a poll on every _process or something like this. I have not written Godot code in a while so I don't know how correct my impression is.

I wonder if we need a general purpose executor.

We certainly do if we're going to export async methods, because they return anonymous types that implement Future. That means we don't get to assume anything else about the type.

However, we don't have to write that general purpose executor. As pointed out in the original post, an existing single-threaded executor should do just fine, provided that the user implemented the necessary wrapper node and added it to the scene tree. We can't provide such a type only due to the "add to scene tree" requirement.

in GDScript there is a separate Object (or just method) that connects to a signal. If the signal is fired then the code after the yield get executed until the function execution is done or another yield was encountered.

I'm not sure what you're referring to. I can't see how GDScript yield is relevant to the implementation: it's magic that only looks like a function in GDScript. Under the hood it's doing something comparable to async-await: transforming the function into a state machine. Surely Godot can't transform our machine code on the fly...?

So I don't think we need a poll on every _process

We certainly don't! I'm pretty sure that the existing executors are smart enough to only poll woken futures, and I won't be surprised if they have fast paths in case nothing is woken in the interim. We won't be polling the futures ourselves: the bridge will just connect to signals, and wake corresponding wakers when it receives a signal. The user-provided executor should handle the rest.

...or something like this

I'm pretty sure that all four parts listed in the original post are required:

• The two Future wrappers are needed, since signals need to be wrapped into Futures for .await, and the return values need to be wrapped into something Godot can consume.
• Changes in the export macro are also always needed, since a macro won't be able to detect whether the resulting Future will be Send.
• The bridge won't be needed if there is a way to connect bare function pointers to signals, but I don't see such provisions in the GDNative API.

Looking back at the original post, I might have given the wrong impression by saying that LocalPool "has serious performance implications". What I actually meant is that it requires the users to think about their workload and not spawn computation heavy tasks, or frames can be delayed. It was written by a sleepy me.

We certainly don't have to implement a new executor from scratch!

[halzy]

I've been looking at async + godot-rust and have some notes that may be useful here:

Of the popular runtimes, only futures and multitask (which is the runtime of smol which is the runtime of async-std) have the ability to not block a thread and let the consumer decide when and how much work should be attempted.

futures has:

• LocalPool::try_run_one
• LocalPool::run_until
• LocalPool::run_until_stalled

multitask has:

• LocalExecutor::tick

Here is a sample singleton Rt that has spawn() and local() using multitask that works with 0.9.0-preview.0:

• https://paste.sr.ht/~halzy/874bad14268ef749597cf6b94cebf855938c710b

---

Posted this in discord, but it belongs here.
How will we ensure that Ref<Node>-like arguments are still valid by the time the async-runtime executes them?

It may be possible for ManuallyManaged types to be released in the window between spawning the task that calls the exported async fn and it being run.

How will we ensure that Ref<Node>-like arguments are still valid by the time the async-runtime executes them?

We can't. That's why assume_safe is unsafe after all...

[halzy]

With the idea that Instance is passed in to the function, would it still have self as a parameter?

#[export(spawn = "local")] // Indicates that the future will be spawned on a local executor
async fn my_coroutine(instance: RefInstance<Self>) -> String {
    // - snip -
}

Of course not. The code examples in the original issue aren't updated for 0.9.