Correct usage of `ComputeTaskPool` is unclear

[clubby789]

How can Bevy's documentation be improved?

I used ComputeTaskPool to queue several computationally heavy tasks that I wanted to run in the background, but complete by the next frame:
https://github.com/Crusaders-of-Rust/cormine/blob/b0d0a65207695e3c8b6266de71da4d80f706bb12/src/main.rs#L246-L320

However, checking frame counts, it seems to take up to 18 frames for the sync tasks to be ready. It's not clear from these docs how exactly this pool should be used to queue tasks for completion by the next frame.

[mockersf]

The documentation may be unclear on two points:

• by "the next frame", what is meant is not that you will have the results for the next frame, but that the next frame may not render until those tasks are done. this is because Bevy use the ComputeTaskPool internally for some of its processing that must happen before anything is rendered, and if you put long lived tasks in it they may be blocked and the next frame may need to wait for them to be finished
• Bevy never gives guarantee of how long a task will take, that's up to you. "the next frame" is not a fixed duration, and will depend on the FPS, often between 30 and 240.

If you want tasks that will be finished "sometime in the future", you should use the AsyncComputeTaskPool. If the result of your tasks is needed to render the next frame, you should use the ComputeTaskPool and wait on the result of those tasks in a system

[clubby789]

I see - the confusion here is that I am spawning tasks on ComputeTaskPool - then, in a later-running system, I call block_on(future::poll_once(&mut task)) on all of the currently existing tasks. Adding frame count debug prints, I can see an 18 frame gap between the task being spawned in the pool, and block_on returning Some. Is this not the correct way to wait on the tasks to complete?