c35df3ca66
## Objective Fixes #19051. --- ## Solution Originally implemented `compiler_error!()` within bevy_tasks/src/lib.rs file to provide descriptive message regarding missing feature. However, a cleaner approach was to add `async_executor` to the array of features enabled by `multi_threaded` instead. This removes the need for users to manually add `features = ["multi_threaded", "async_executor"]` separately as needed to be done previously. --- ## Testing These changes were tested using a minimal, external project designed to specifically test whether the standalone `multi_threaded` feature for `bevy_tasks` with `default-features` disabled worked as intended without running into any compile-time error. ### How it was tested: 1. A `bevy_tasks_test` binary project was set up in an external directory. 2. Its `Cargo.toml` was configured to depend on the local `bevy_tasks`, explicitly disabling default features and enabling only `multi_threaded`. 3. A simple `bevy_tasks_test/bin/bevy_crates_test.rs` was created and configured within `Cargo.toml` file where bevy_tasks was set to the local version of the crate with the modified changes and `cargo add bevy_platform` was executed through the terminal since that dependency is also needed to execute the sample examples. 4. Then both the `examples/busy_behavior.rs` and `examples/idle_behavior.rs` code was added and tested with just the `multi_threaded` feature was enabled and the code executed successfully. ### Results: The code executed successfully for both examples where a threadPool was utilized with 4 tasks and spawning 40 tasks that spin for 100ms. Demonstrating how the threads finished executing all the tasks simultaneously after a brief delay of less than a second (this is referencing `bevy_tasks/examples/busy_behavior.rs`). Alongside the second example where one thread per logical core was was utilized for a single spinning task and aside from utilizing the single thread, system was intended to remain idle as part of good practice when it comes to handling small workloads. (this is referencing `bevy_tasks/examples/idle_behavior.rs`). ### How to test: Reviewers can easily verify this by: 1. Checking out this PR. 2. Creating `cargo new bevy_tasks_test` and the `Cargo.toml` should look something like this: ```toml # bevy/tests/compile_fail_tasks/Cargo.toml [package] name = "bevy_tasks_test" version = "0.1.0" edition = "2021" publish = false [dependencies] # path to bevy_tasks sub-crate to test locally bevy_tasks = { path = "../../bevy_tasks", default-features = false, features = ["multi_threaded"] } bevy_platform = "0.16.1" ``` 3. Copying the examples within bevy_creates/examples one by one and testing them separately within `src/main.rs` to check whether the examples work. 4. Then simply running `cargo run` within the terminal should suffice to test if the single `multi_threaded` feature works without the need for separately adding `async_executor` as `multi_threaded` already uses `async_executor` internally. ### Platforms tested: macOS (aarch64). As a `#[cfg]` based compile-time check, behavior should be consistent across platforms. |
||
|---|---|---|
| .. | ||
| examples | ||
| src | ||
| Cargo.toml | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| README.md | ||
Bevy Tasks
A refreshingly simple task executor for bevy. :)
This is a simple threadpool with minimal dependencies. The main usecase is a scoped fork-join, i.e. spawning tasks from
a single thread and having that thread await the completion of those tasks. This is intended specifically for
bevy as a lighter alternative to rayon for this specific usecase. There are also utilities for
generating the tasks from a slice of data. This library is intended for games and makes no attempt to ensure fairness
or ordering of spawned tasks.
It is based on async-executor, a lightweight executor that allows the end user to manage their own threads.
async-executor is based on async-task, a core piece of async-std.
Usage
In order to be able to optimize task execution in multi-threaded environments, bevy provides three different thread pools via which tasks of different kinds can be spawned. (The same API is used in single-threaded environments, even if execution is limited to a single thread. This currently applies to Wasm targets.) The determining factor for what kind of work should go in each pool is latency requirements:
-
For CPU-intensive work (tasks that generally spin until completion) we have a standard [
ComputeTaskPool] and an [AsyncComputeTaskPool]. Work that does not need to be completed to present the next frame should go to the [AsyncComputeTaskPool]. -
For IO-intensive work (tasks that spend very little time in a "woken" state) we have an [
IoTaskPool] whose tasks are expected to complete very quickly. Generally speaking, they should just await receiving data from somewhere (i.e. disk) and signal other systems when the data is ready for consumption. (likely via channels)
no_std Support
To enable no_std support in this crate, you will need to disable default features, and enable the edge_executor and critical-section features.