Document what differentiates IoTaskPool and AsyncComputeTaskPool beyond basic usage
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 22h
- Merged PRs (30d)
- 161
Description
The current docs for `bevy::tasks` and the pools explains what each task pool should be used for in a short sentence, but doesn't go deeper than that. This leaves open some questions users might have about when to use which pool, as was the case with me. What exactly does `tasks spend very little time in a "woken" state` mean for the kinds of code? Is it enough to call `std::thread::yield_now` or is a `std::thread::sleep` necessary to be considered "not in a woken state"? How does it interact with `std::thread::park`(`_timeout`)? What about on other platforms like web, how can i make sure my code for a IoTaskPool is properly `not in a "woken" state` there, or with single threaded executor?
This might just be a lack of knowledge about threading internals on my end, but on the other hand it seems like knowledge that shouldn't be necessary to understand bevys task pool abstractions.
Normally, i'd look at the code and try to find out what it actually does, but from reading the code its a bit hard to tell what the differences between pools are. To me, the `taskpool!` macro in `bevy_tasks/usages.rs` seems to create newtypes around the same `TaskPool` without any differences between them.
Docs that could be improved: [IoTaskPool](https://docs.rs/bevy/latest/bevy/tasks/struct.TaskPool.html), [AsyncComputeTaskPool](https://docs.rs/bevy/latest/bevy/tasks/struct.AsyncComputeTaskPool.html) and [bevy::tasks](https://docs.rs/bevy/latest/bevy/tasks/index.html)
Comments that would be nice to have: on the `taskpool!` macro, explaining how it generates different code, or why all task pools created by it are equivalent.
Contributor guide
Assessment
This issue has not been assessed yet.