Update Async Task documentation

[ewrogers]

How can Bevy's documentation be improved?

The current examples for using async computing are out of date. Specifically, they use the older v0.7 syntax of Res<AsyncComputeTaskPool>, which will not compile in current Bevy (0.11.2).

Additionally, the async compute and Task system is not highlighted at all in current documentation. Coming from Unity's DOTS and Job pipelines, I was looking for a similar analog.

As luck would have it, I ran across Logic Projects' great video on Pathfinding + Bevy Async Tasks which was exactly what I was trying to do. The relevant source code can be found on the Github project.

I think it would be immensely useful for developers to know that Bevy supports this, and refreshed documentation on how to use it.

[nicopap]

Your first link to "current examples" links to a March 2022 commit. Check out the tag at the top left of the web interface.

Examples are compiled and checked every commit, so they can't be out of sync with current bevy, they always compile (unless there is a bug in CI).

The example for the latest release is available at:

https://github.com/bevyengine/bevy/blob/latest/examples/async_tasks/async_compute.rs

[ewrogers]

Derp... I don't know how I missed that! Good to know.

One thing I was trying to reason about is the cancel() function on tasks.

It mentions that it "waits" for the task to complete which suggests blocking behavior, which can be counter-productive to async behaviors. It does go on to mention it returns None if the task did not complete so I am a bit confused.

Are there synchronous tasks and asynchronous tasks which cancellation behavior may differ based on which compute task pool is used?

Digging into the code it seems bevy_tasks is a wrapper around async_executor and async_task crates, using futures_lite for some of the blocking/polling behavior.

It seems that cancel().await is called under the hood but it's immediately obvious what happens.

Do I get a way for my background function to respond to the cancellation? Or does it just become a runaway thread? Maybe some examples with cancellation and how it could be used.

Another non-obvious aspect is the need to use future::block_on and future::poll_once to get the result, which seems like a leaky abstraction. I will likely make a PR that exposes a poll_result() -> Option<T> for the task to wrap this since futures_lite is already a dependency for bevy.

[hymm]

You can Drop the returned Task if you don't care about waiting for the task to complete if you didn't detach() it.

There is this PR to add an abstraction to make working with tasks a little easier, but seems to have stalled. #4102. You could probably adopt it.