cc69fdd0c6
# Objective - Fixes #15460 (will open new issues for further `no_std` efforts) - Supersedes #17715 ## Solution - Threaded in new features as required - Made certain crates optional but default enabled - Removed `compile-check-no-std` from internal `ci` tool since GitHub CI can now simply check `bevy` itself now - Added CI task to check `bevy` on `thumbv6m-none-eabi` to ensure `portable-atomic` support is still valid [^1] [^1]: This may be controversial, since it could be interpreted as implying Bevy will maintain support for `thumbv6m-none-eabi` going forward. In reality, just like `x86_64-unknown-none`, this is a [canary](https://en.wiktionary.org/wiki/canary_in_a_coal_mine) target to make it clear when `portable-atomic` no longer works as intended (fixing atomic support on atomically challenged platforms). If a PR comes through and makes supporting this class of platforms impossible, then this CI task can be removed. I however wager this won't be a problem. ## Testing - CI --- ## Release Notes Bevy now has support for `no_std` directly from the `bevy` crate. Users can disable default features and enable a new `default_no_std` feature instead, allowing `bevy` to be used in `no_std` applications and libraries. ```toml # Bevy for `no_std` platforms bevy = { version = "0.16", default-features = false, features = ["default_no_std"] } ``` `default_no_std` enables certain required features, such as `libm` and `critical-section`, and as many optional crates as possible (currently just `bevy_state`). For atomically-challenged platforms such as the Raspberry Pi Pico, `portable-atomic` will be used automatically. For library authors, we recommend depending on `bevy` with `default-features = false` to allow `std` and `no_std` users to both depend on your crate. Here are some recommended features a library crate may want to expose: ```toml [features] # Most users will be on a platform which has `std` and can use the more-powerful `async_executor`. default = ["std", "async_executor"] # Features for typical platforms. std = ["bevy/std"] async_executor = ["bevy/async_executor"] # Features for `no_std` platforms. libm = ["bevy/libm"] critical-section = ["bevy/critical-section"] [dependencies] # We disable default features to ensure we don't accidentally enable `std` on `no_std` targets, for example. bevy = { version = "0.16", default-features = false } ``` While this is verbose, it gives the maximum control to end-users to decide how they wish to use Bevy on their platform. We encourage library authors to experiment with `no_std` support. For libraries relying exclusively on `bevy` and no other dependencies, it may be as simple as adding `#![no_std]` to your `lib.rs` and exposing features as above! Bevy can also provide many `std` types, such as `HashMap`, `Mutex`, and `Instant` on all platforms. See `bevy::platform_support` for details on what's available out of the box! ## Migration Guide - If you were previously relying on `bevy` with default features disabled, you may need to enable the `std` and `async_executor` features. - `bevy_reflect` has had its `bevy` feature removed. If you were relying on this feature, simply enable `smallvec` and `smol_str` instead. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
44 lines
2.6 KiB
Markdown
44 lines
2.6 KiB
Markdown
# Bevy Tasks
|
|
|
|
[](https://github.com/bevyengine/bevy#license)
|
|
[](https://crates.io/crates/bevy_tasks)
|
|
[](https://crates.io/crates/bevy_tasks)
|
|
[](https://docs.rs/bevy_tasks/latest/bevy_tasks/)
|
|
[](https://discord.gg/bevy)
|
|
|
|
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`][bevy] as a lighter alternative to [`rayon`][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`][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.
|
|
|
|
[bevy]: https://bevyengine.org
|
|
[rayon]: https://github.com/rayon-rs/rayon
|
|
[async-executor]: https://github.com/stjepang/async-executor
|