bevyengine/bevy

bevy_tasks

Task pools and async helpers. Provides the threaded executors that the ECS multi-threaded scheduler runs on, plus a Wasm-friendly path for single-threaded environments.

Purpose

bevy_tasks is the threading substrate. It exposes three named pools — compute, async-compute, I/O — and a uniform API for spawn, spawn_local, and block_on. The implementations differ by platform:

Native: async-executor + futures-lite, with one OS thread per pool slot.
Wasm with atomics: the same pools but on wasm-bindgen-spawned workers.
Wasm without atomics or multi_threaded = false: all pools collapse to the calling thread, with spawn polling cooperatively.

Directory layout

crates/bevy_tasks/src/
├── lib.rs
├── single_threaded_task_pool.rs
├── thread_executor.rs
├── task_pool.rs
├── usages.rs                 # ComputeTaskPool / AsyncComputeTaskPool / IoTaskPool aliases
├── iter/                     # ParallelIterator extension
├── conditional_send.rs       # `Send`-or-not based on target_arch
└── prelude.rs

Key abstractions

Type	File	Description
`TaskPool`	`crates/bevy_tasks/src/task_pool.rs`	The native task pool.
`ComputeTaskPool`, `AsyncComputeTaskPool`, `IoTaskPool`	`crates/bevy_tasks/src/usages.rs`	Resource-style accessors for the three named pools.
`Task<T>`	`crates/bevy_tasks/src/task_pool.rs`	A spawned future you can poll.
`Scope<'env, T>`	`crates/bevy_tasks/src/task_pool.rs`	Borrow-tracking scope for "spawn-and-join" patterns.
`ParallelSlice`	`crates/bevy_tasks/src/iter/`	Helpers for parallel iteration.
`block_on`	`crates/bevy_tasks/src/lib.rs`	Synchronously wait for a future.
`IoTaskPool`	`crates/bevy_tasks/src/usages.rs`	Used by the asset server.

How it works

Each pool is a global lazily-initialized singleton. bevy_app::TaskPoolPlugin initializes them at startup with thread counts derived from TaskPoolOptions. The schedule executor in bevy_ecs uses ComputeTaskPool for parallel system dispatch. The asset server uses IoTaskPool for file I/O. User code calls AsyncComputeTaskPool::get().spawn(...) for long-running work.

The Scope helper exists for the "spawn N tasks, wait for all" pattern with proper borrow checking — it's how the schedule executor works.

Integration points

Depends on: async-executor, futures-lite, concurrent-queue, bevy_platform.
Depended on by: bevy_ecs (multi-threaded executor), bevy_app, bevy_asset (I/O), bevy_render (pipeline cache compilation), …

Entry points for modification

Custom pool: create a new alias mirroring ComputeTaskPool. There's nothing magic about the three built-in names beyond convention.
Wasm threading model: single_threaded_task_pool.rs. The build chooses between this and the threaded version based on cfg(target_arch = "wasm32") and the multi_threaded feature.
Scope semantics: task_pool.rs. Tricky lifetimes; touch with care.