Struct bevy::tasks::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/scene/scene.rs (lines 138-143)

fn save_scene_system(world: &mut World) {
    // Scenes can be created from any ECS World.
    // You can either create a new one for the scene or use the current World.
    // For demonstration purposes, we'll create a new one.
    let mut scene_world = World::new();

    // The `TypeRegistry` resource contains information about all registered types (including components).
    // This is used to construct scenes, so we'll want to ensure that our previous type registrations
    // exist in this new scene world as well.
    // To do this, we can simply clone the `AppTypeRegistry` resource.
    let type_registry = world.resource::<AppTypeRegistry>().clone();
    scene_world.insert_resource(type_registry);

    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"),
    ));
    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 our scene using DynamicScene or DynamicSceneBuilder.
    // For simplicity, we will create our scene using DynamicScene:
    let scene = DynamicScene::from_world(&scene_world);

    // Scenes can be serialized like this:
    let type_registry = world.resource::<AppTypeRegistry>();
    let serialized_scene = scene.serialize_ron(type_registry).unwrap();

    // Showing the scene in the console
    info!("{}", serialized_scene);

    // Writing the scene 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 scene RON data to file
            File::create(format!("assets/{NEW_SCENE_FILE_PATH}"))
                .and_then(|mut file| file.write(serialized_scene.as_bytes()))
                .expect("Error while writing scene to file");
        })
        .detach();
}

examples/async_tasks/async_compute.rs (lines 61-101)

fn spawn_tasks(mut commands: Commands) {
    let thread_pool = AsyncComputeTaskPool::get();
    for x in 0..NUM_CUBES {
        for y in 0..NUM_CUBES {
            for z in 0..NUM_CUBES {
                // Spawn new task on the AsyncComputeTaskPool; the task will be
                // executed in the background, and the Task future returned by
                // spawn() can be used to poll for the result
                let entity = commands.spawn_empty().id();
                let task = thread_pool.spawn(async move {
                    let mut rng = rand::thread_rng();

                    let duration = Duration::from_secs_f32(rng.gen_range(0.05..0.2));

                    // Pretend this is a time-intensive function. :)
                    thread::sleep(duration);

                    // Such hard work, all done!
                    let transform = Transform::from_xyz(x as f32, y as f32, z as f32);
                    let mut command_queue = CommandQueue::default();

                    // we use a raw command queue to pass a FnOne(&mut World) back to be
                    // applied in a deferred manner.
                    command_queue.push(move |world: &mut World| {
                        let (box_mesh_handle, box_material_handle) = {
                            let mut system_state = SystemState::<(
                                Res<BoxMeshHandle>,
                                Res<BoxMaterialHandle>,
                            )>::new(world);
                            let (box_mesh_handle, box_material_handle) =
                                system_state.get_mut(world);

                            (box_mesh_handle.clone(), box_material_handle.clone())
                        };

                        world
                            .entity_mut(entity)
                            // Add our new PbrBundle of components to our tagged entity
                            .insert(PbrBundle {
                                mesh: box_mesh_handle,
                                material: box_material_handle,
                                transform,
                                ..default()
                            })
                            // Task is complete, so remove task component from entity
                            .remove::<ComputeTransform>();
                    });

                    command_queue
                });

                // Spawn new entity and add our new task as a component
                commands.entity(entity).insert(ComputeTransform(task));
            }
        }
    }
}

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.