Struct ComputeTaskPool 

pub struct ComputeTaskPool(/* private fields */);

A newtype for a task pool for CPU-intensive work that must be completed to deliver the next frame

See TaskPool documentation for details on Bevy tasks. AsyncComputeTaskPool should be preferred if the work does not have to be completed before the next frame.

Implementations

impl ComputeTaskPool

pub fn get_or_init(f: impl FnOnce() -> TaskPool) -> &'static ComputeTaskPool

Gets the global ComputeTaskPool instance, or initializes it with f.

pub fn try_get() -> Option<&'static ComputeTaskPool>

Attempts to get the global ComputeTaskPool instance, or returns None if it is not initialized.

pub fn get() -> &'static ComputeTaskPool

Gets the global ComputeTaskPool instance.

Panics

Panics if the global instance has not been initialized yet.

Methods from Deref<Target = TaskPool>

pub fn thread_num(&self) -> usize

Return the number of threads owned by the task pool

pub fn scope<'env, F, T>(&self, f: F) -> Vec<T>

where F: for<'scope> FnOnce(&'scope Scope<'scope, 'env, T>), T: Send + 'static,

Allows spawning non-'static futures on the thread pool. The function takes a callback, passing a scope object into it. The scope object provided to the callback can be used to spawn tasks. This function will await the completion of all tasks before returning.

This is similar to thread::scope and rayon::scope.

Example

use bevy_tasks::TaskPool;

let pool = TaskPool::new();
let mut x = 0;
let results = pool.scope(|s| {
    s.spawn(async {
        // you can borrow the spawner inside a task and spawn tasks from within the task
        s.spawn(async {
            // borrow x and mutate it.
            x = 2;
            // return a value from the task
            1
        });
        // return some other value from the first task
        0
    });
});

// The ordering of results is non-deterministic if you spawn from within tasks as above.
// If you're doing this, you'll have to write your code to not depend on the ordering.
assert!(results.contains(&0));
assert!(results.contains(&1));

// The ordering is deterministic if you only spawn directly from the closure function.
let results = pool.scope(|s| {
    s.spawn(async { 0 });
    s.spawn(async { 1 });
});
assert_eq!(&results[..], &[0, 1]);

// You can access x after scope runs, since it was only temporarily borrowed in the scope.
assert_eq!(x, 2);

Lifetimes

The Scope object takes two lifetimes: 'scope and 'env.

The 'scope lifetime represents the lifetime of the scope. That is the time during which the provided closure and tasks that are spawned into the scope are run.

The 'env lifetime represents the lifetime of whatever is borrowed by the scope. Thus this lifetime must outlive 'scope.

use bevy_tasks::TaskPool;
fn scope_escapes_closure() {
    let pool = TaskPool::new();
    let foo = Box::new(42);
    pool.scope(|scope| {
        std::thread::spawn(move || {
            // UB. This could spawn on the scope after `.scope` returns and the internal Scope is dropped.
            scope.spawn(async move {
                assert_eq!(*foo, 42);
            });
        });
    });
}

use bevy_tasks::TaskPool;
fn cannot_borrow_from_closure() {
    let pool = TaskPool::new();
    pool.scope(|scope| {
        let x = 1;
        let y = &x;
        scope.spawn(async move {
            assert_eq!(*y, 1);
        });
    });
}

pub fn scope_with_executor<'env, F, T>( &self, tick_task_pool_executor: bool, external_executor: Option<&ThreadExecutor<'_>>, f: F, ) -> Vec<T>

where F: for<'scope> FnOnce(&'scope Scope<'scope, 'env, T>), T: Send + 'static,

This allows passing an external executor to spawn tasks on. When you pass an external executor Scope::spawn_on_scope spawns is then run on the thread that ThreadExecutor is being ticked on. If None is passed the scope will use a ThreadExecutor that is ticked on the current thread.

When tick_task_pool_executor is set to true, the multithreaded task stealing executor is ticked on the scope thread. Disabling this can be useful when finishing the scope is latency sensitive. Pulling tasks from global executor can run tasks unrelated to the scope and delay when the scope returns.

See Self::scope for more details in general about how scopes work.

pub fn spawn<T>( &self, future: impl Future<Output = T> + Send + 'static, ) -> Task<T>

where T: Send + 'static,

Spawns a static future onto the thread pool. The returned Task is a future that can be polled for the result. It can also be canceled and “detached”, allowing the task to continue running even if dropped. In any case, the pool will execute the task even without polling by the end-user.

If the provided future is non-Send, TaskPool::spawn_local should be used instead.

Examples found in repository

examples/async_tasks/async_channel_pattern.rs (lines 53-60)

fn spawn_tasks(channel: Res<CubeChannel>) {
    let pool = AsyncComputeTaskPool::get();

    for x in -NUM_CUBES..NUM_CUBES {
        for z in -NUM_CUBES..NUM_CUBES {
            let sender = channel.sender.clone();
            // Spawn a task on the async compute pool
            pool.spawn(async move {
                let delay = Duration::from_secs_f32(rand::rng().random_range(2.0..8.0));
                // Simulate a delay before task completion
                Delay::new(delay).await;
                let _ = sender.send(CubeFinished {
                    transform: Transform::from_xyz(x as f32, 0.5, z as f32),
                });
            })
            .detach();
        }
    }
}

examples/asset/asset_saving.rs (lines 48-61)

fn perform_save(
    image_to_save: Res<ImageToSave>,
    images: Res<Assets<Image>>,
    asset_server: Res<AssetServer>,
) {
    let image = images.get(&image_to_save.0).unwrap();

    let image = image.clone();
    let asset_server = asset_server.clone();
    IoTaskPool::get()
        .spawn(async move {
            match save_using_saver(
                asset_server.clone(),
                &ImageSaver,
                &ASSET_PATH.into(),
                SavedAsset::from_asset(&image),
                &ImageSaverSettings::default(),
            )
            .await
            {
                Ok(()) => info!("Completed save of {ASSET_PATH}"),
                Err(err) => error!("Failed to save asset: {err}"),
            }
        })
        .detach();
}

examples/asset/multi_asset_sync.rs (lines 165-169)

fn setup_assets(mut commands: Commands, asset_server: Res<AssetServer>) {
    let (barrier, guard) = AssetBarrier::new();
    commands.insert_resource(OneHundredThings(std::array::from_fn(|i| {
        let builder = asset_server.load_builder().with_guard(guard.clone());
        match i % 5 {
            0 => builder.load("models/GolfBall/GolfBall.glb"),
            1 => builder.load("models/AlienCake/alien.glb"),
            2 => builder.load("models/AlienCake/cakeBirthday.glb"),
            3 => builder.load("models/FlightHelmet/FlightHelmet.gltf"),
            4 => builder.load("models/torus/torus.gltf"),
            _ => unreachable!(),
        }
    })));
    let future = barrier.wait_async();
    commands.insert_resource(barrier);

    let loading_state = Arc::new(AtomicBool::new(false));
    commands.insert_resource(AsyncLoadingState(loading_state.clone()));

    // await the `AssetBarrierFuture`.
    AsyncComputeTaskPool::get()
        .spawn(async move {
            future.await;
            // Notify via `AsyncLoadingState`
            loading_state.store(true, Ordering::Release);
        })
        .detach();
}

examples/asset/asset_saving_with_subassets.rs (lines 58-85)

fn perform_save(boxes: Query<(&Sprite, &Transform), With<Box>>, asset_server: Res<AssetServer>) {
    // First we extract all the data needed to produce an asset we can save.
    let boxes = boxes
        .iter()
        .map(|(sprite, transform)| OneBox {
            position: transform.translation.xy(),
            color: sprite.color,
        })
        .collect::<Vec<_>>();

    let asset_server = asset_server.clone();
    IoTaskPool::get()
        .spawn(async move {
            // Build a `SavedAsset` instance from the boxes we extracted.
            let mut builder = SavedAssetBuilder::new(asset_server.clone(), ASSET_PATH.into());
            let mut many_boxes = ManyBoxes { boxes: vec![] };
            for (index, one_box) in boxes.iter().enumerate() {
                many_boxes
                    .boxes
                    .push(builder.add_labeled_asset_with_new_handle(
                        index.to_string(),
                        SavedAsset::from_asset(one_box),
                    ));
            }

            let saved_asset = builder.build(&many_boxes);
            // Save the asset using the provided saver.
            match save_using_saver(
                asset_server.clone(),
                &ManyBoxesSaver,
                &ASSET_PATH.into(),
                saved_asset,
                &(),
            )
            .await
            {
                Ok(()) => info!("Completed save of {ASSET_PATH}"),
                Err(err) => error!("Failed to save asset: {err}"),
            }
        })
        .detach();
}

examples/animation/animation_graph.rs (lines 182-200)

fn setup_assets_programmatically(
    commands: &mut Commands,
    asset_server: &mut AssetServer,
    animation_graphs: &mut Assets<AnimationGraph>,
    _save: bool,
) {
    // Create the nodes.
    let mut animation_graph = AnimationGraph::new();
    let blend_node = animation_graph.add_blend(0.5, animation_graph.root);
    animation_graph.add_clip(
        asset_server.load(GltfAssetLabel::Animation(0).from_asset("models/animated/Fox.glb")),
        1.0,
        animation_graph.root,
    );
    animation_graph.add_clip(
        asset_server.load(GltfAssetLabel::Animation(1).from_asset("models/animated/Fox.glb")),
        1.0,
        blend_node,
    );
    animation_graph.add_clip(
        asset_server.load(GltfAssetLabel::Animation(2).from_asset("models/animated/Fox.glb")),
        1.0,
        blend_node,
    );

    // If asked to save, do so.
    #[cfg(not(target_arch = "wasm32"))]
    if _save {
        let animation_graph = animation_graph.clone();

        IoTaskPool::get()
            .spawn(async move {
                use std::io::Write;

                let animation_graph: SerializedAnimationGraph = animation_graph
                    .try_into()
                    .expect("The animation graph failed to convert to its serialized form");

                let serialized_graph =
                    ron::ser::to_string_pretty(&animation_graph, PrettyConfig::default())
                        .expect("Failed to serialize the animation graph");
                let mut animation_graph_writer = File::create(Path::join(
                    &FileAssetReader::get_base_path(),
                    Path::join(Path::new("assets"), Path::new(ANIMATION_GRAPH_PATH)),
                ))
                .expect("Failed to open the animation graph asset");
                animation_graph_writer
                    .write_all(serialized_graph.as_bytes())
                    .expect("Failed to write the animation graph");
            })
            .detach();
    }

    // Add the graph.
    let handle = animation_graphs.add(animation_graph);

    // Save the assets in a resource.
    commands.insert_resource(ExampleAnimationGraph(handle));
}

examples/scene/world_serialization.rs (lines 208-213)

fn save_world_system(world: &mut World) {
    let asset_server = world.resource::<AssetServer>().clone();
    // The `TypeRegistry` resource contains information about all registered types (including components).
    // This is used to construct worlds, so we'll want to ensure that we use the registry from the
    // main world. To do this, we can simply clone the `AppTypeRegistry` resource.
    let type_registry = world.resource::<AppTypeRegistry>().clone();

    // Any ECS World can be serialized.
    // For demonstration purposes, we'll create a new one.
    let mut scene_world = World::new();

    let mut component_b = ComponentB::from_world(world);
    component_b.value = "hello".to_string();
    scene_world.spawn((
        component_b,
        ComponentA { x: 1.0, y: 2.0 },
        Transform::IDENTITY,
        Name::new("joe"),
        WorldAssetRoot(asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0")),
    ));
    scene_world.spawn(ComponentA { x: 3.0, y: 4.0 });
    scene_world.insert_resource(ResourceA { score: 1 });

    // With our sample world ready to go, we can now create a DynamicWorld from it.
    // For simplicity, we will create our scene using DynamicWorld directly, but if
    // you need more control, you can use DynamicWorldBuilder.
    let dynamic_world = DynamicWorld::from_world_with(&scene_world, &type_registry.read());

    // Dynamic Worlds can be serialized like this:
    let type_registry = world.resource::<AppTypeRegistry>();
    let type_registry = type_registry.read();
    let serialized_world = dynamic_world.serialize(&type_registry).unwrap();

    // Shows the serialized world in the console
    info!("{}", serialized_world);

    // Writing the world to a new file. Using a task to avoid calling the filesystem APIs in a system
    // as they are blocking.
    //
    // This can't work in Wasm as there is no filesystem access.
    #[cfg(not(target_arch = "wasm32"))]
    IoTaskPool::get()
        .spawn(async move {
            // Write the world RON data to file
            File::create(format!("assets/{NEW_WORLD_FILE_PATH}"))
                .and_then(|mut file| file.write(serialized_world.as_bytes()))
                .expect("Error while writing world to file");
        })
        .detach();
}

Additional examples can be found in:

• examples/async_tasks/async_compute.rs

pub fn spawn_local<T>( &self, future: impl Future<Output = T> + 'static, ) -> Task<T>

where T: 'static,

Spawns a static future on the thread-local async executor for the current thread. The task will run entirely on the thread the task was spawned on.

The returned Task is a future that can be polled for the result. It can also be canceled and “detached”, allowing the task to continue running even if dropped. In any case, the pool will execute the task even without polling by the end-user.

Users should generally prefer to use TaskPool::spawn instead, unless the provided future is not Send.

pub fn with_local_executor<F, R>(&self, f: F) -> R

where F: FnOnce(&LocalExecutor<'_>) -> R,

Runs a function with the local executor. Typically used to tick the local executor on the main thread as it needs to share time with other things.

use bevy_tasks::TaskPool;

TaskPool::new().with_local_executor(|local_executor| {
    local_executor.try_tick();
});

Trait Implementations

impl Debug for ComputeTaskPool

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deref for ComputeTaskPool

type Target = TaskPool

The resulting type after dereferencing.

fn deref(&self) -> &<ComputeTaskPool as Deref>::Target

Dereferences the value.