Add an @async annotation

[atirut-w]

Describe the project you are working on

N/A

Describe the problem or limitation you are having in your project

In Godot(3 & 4), if you want to await a thread and not block the main thread, you have to do this(syntax depends on engine version):

func _ready() -> void:
    var thread := Thread.new()
    thread.start(do_something)
    while thread.is_alive():
        await get_tree().physics_frame
    thread.wait_to_finish()

func do_something():
    pass # Do something really heavy

These repetitive codes can add up if you have to do this even in a few different functions or places.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The @async annotation would wrap the function as a coroutine do you could await it.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

func _ready() -> void:
    await do_something()

@async
func do_something():
    pass # Do something really heavy

If this enhancement will not be used often, can it be worked around with a few lines of script?

If this will be implemented in GDScript, then custom annotations will be a minimum requirement.

Is there a reason why this should be core and not an add-on in the asset library?

See above

[JoNax97]

I'd prefer a way to switch threads in an async/await context.

Something like this:

await switch_to_worker_thread()

#do heavy stuff

await switch_to_main_thread()

[atirut-w]

I don't think switching thread while inside a function is possible in GDScript. This also looks unintuitive, at least for me.

[Daylily-Zeleen]

I think @async is not means that it should be work in other thread.

Of course, I agree that we should provide a more convenient way to creat a backgound thread without blocking the main thread and can await it to gain it's return value, although it is hard to debug.

How about using @backgound_thread instead of @async.

[atirut-w]

How about using @backgound_thread instead of @async.

I think the name should be shortened a little

[Daylily-Zeleen]

How about using @backgound_thread instead of @async.

I think the name should be shortened a little

@subthread?

[atirut-w]

That sounds great

[Daylily-Zeleen]

I am trying to implement it. But don't be too hopeful.

[Daylily-Zeleen]

Wait, I found that we should not await a thread directly, because users may want to abort a thread before finishing.

[nlupugla]

I have been working on a proposal that I think might come in handy here: #8752. The idea is a general @tag annotation that lets you tag methods with metadata.

So instead of

@async
func do_something():
    # do something heavy

You could write

@tag("async")
func do_something():
    # do something heavy

The tag on it's own wouldn't do anything. However, it would signpost to developers that the function should be called asynchronously. This approach is more flexible that trying to design a one-size-fits-all wrapper annotation because how exactly you want to wrap an async function depends pretty heavily on what exactly it's doing and what other processes it might potentially be blocking.