bevyengine / bevyengine/bevy

Document what differentiates IoTaskPool and AsyncComputeTaskPool beyond basic usage

Open
#22,301 4 comments 0 reactions 0 assignees View on GitHub
A-Tasks C-Docs C-Examples C-Usability D-Async D-Modest S-Ready-For-Implementation
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.