Example of custom async task with single block_on

[hanabi1224]

Objective

• Compare performance between using single block_on and multiple block_on(s) when dealing with massive custom async tasks
• The result shows (on windows) that using single block_on has better performance (by 20%~50%), is it feasible to perform poll_once inside ecs framework then, that would save a lot of boilerplate code?
• By avoiding poll_once and block_on in user code, it gets the best performance.

Solution

• Add an async-bench example
• Run with release build cargo run --release --example async_bench
• It pints result like

[handle_tasks_no_poll_once]n_frames executed: 206, avg fps: 34.8(target:120), duration: 5.920s
[handle_tasks]        n_frames executed: 72, avg fps: 12.4(target:120), duration: 5.784s
[handle_tasks_par]    n_frames executed: 123, avg fps: 21.6(target:120), duration: 5.697s
[handle_tasks_par_2]  n_frames executed: 88, avg fps: 15.3(target:120), duration: 5.751s

[NiklasEi]

This seems to be more of a benchmark than an example. Can it be moved to benches?

[hanabi1224]

@NiklasEi Thanks! Sure I can add another micro-benchmark to the benches, in the meanwhile, this one is more like a small toy program that exercises the main stacks of bevy ecs, and show numbers in an E2E scenario. I think micro-benchmark and small benchmark program serves different purposes and should co-exsist.

BTW, It does show a huge perf gap between using single and multiple block_on(s), regarding my question below, where is the best place for discussion? GH discussion or discord?

is it feasible to perform poll_once inside ecs framework then, that would save a lot of boilerplate code?

[mockersf]

The difference between handle_tasks_par and handle_tasks_par_2 are due to the .collect::<Vec<_>>(). Also, you can squeeze a little more speed by changing your n_tasks to a bool, as you don't actually care about the number of task performed.

On the difference between multiple block_on vs a single bigger one, this is more a question for futures-lite but it makes sense as blocking the thread is expensive, so doing it only once is better. Discussion on GH discussion is best as answers will be easily searchable, don't hesitate to post your discussion link on discord if you don't get answers 👍

is it feasible to perform poll_once inside ecs framework then, that would save a lot of boilerplate code?

Are you suggesting something like

struct TaskResult<T>(T);

pub fn handle_tasks<T: Component>(
    mut commands: Commands,
    mut tasks: Query<(Entity, &mut Task<T>)>,
) {
    let done = tasks.iter_mut().map(|(entity, mut task)| async move {
        if let Some(r) = poll_once(&mut *task).await {
            Some((entity, r))
        } else {
            None
        }
    });
    block_on(async {
        for f in done {
            if let Some((entity, result)) = f.await {
                commands
                    .entity(entity)
                    .remove::<Task<T>>()
                    .insert(TaskResult(result));
            }
        }
    });
}

It's possible to add in Bevy, but as it needs to be generic over the task type, you would still need some kind of registration mechanic for your tasks

[hanabi1224]

@mockersf Thanks! I'm thinking of sth like this, users still register Task but can query PollOnce<Task<T>> directly
I guess this requires implementing SysParams for PollOnce<Task<T>> and perform poll_once in fetch after retrieving tasks from entity table

pub fn handle_tasks<T: Component>(
    mut commands: Commands,
    mut tasks: Query<(Entity, PollOnce<Task<T>>)>, 
) {
    block_on(async {
        for entity, task in tasks{
            if let Some(result) = task.await {
                commands
                    .entity(entity)
                    .remove::<Task<T>>()
                    .insert(TaskResult(result));
            }
        }
    });
}

Or, if async fn can be used, ecs will do the block_on part

pub async fn handle_tasks<T: Component>(
    mut commands: Commands,
    mut tasks: Query<(Entity, &mut Task<T>)>,
) {
    for (entity, mut task) in transform_tasks.iter_mut() {
        n_tasks += 1;
        let ret = poll_once(&mut *task).await;
        if ret.is_some() {
            commands.entity(entity).remove::<Task<bool>>();
        }
    }
}

[hanabi1224]

@mockersf After discussion, I found it's better to just totally remove block_on and poll_once from user system code, and here's my proposed API change: #2691

[Nilirad]

This PR adds a new example. Adding module and item level doc comments, as described in:

• Module-style doc strings for examples #3951 and
• [Merged by Bors] - Doc/module style doc blocks for examples #4438,

would be really useful to those who will browse examples.

---

I think it's sufficient to move the description on the top, as a module level doc comment.

I also think this should not be advertized as a benchmark, as examples are built without optimizations by default.

[alice-i-cecile]

Adding the Adopt-Me tag; I think this is valuable but the issues never got fixed.