Struct bevy_internal::tasks::TaskPool

pub struct TaskPool { /* private fields */ }

A thread pool for executing tasks.

While futures usually need to be polled to be executed, Bevy tasks are being automatically driven by the pool on threads owned by the pool. The Task future only needs to be polled in order to receive the result. (For that purpose, it is often stored in a component or resource, see the async_compute example.)

If the result is not required, one may also use Task::detach and the pool will still execute a task, even if it is dropped.

Implementations

impl TaskPool

pub fn get_thread_executor() -> Arc<ThreadExecutor<'static>>

Each thread should only create one ThreadExecutor, otherwise, there are good chances they will deadlock

pub fn new() -> TaskPool

Create a TaskPool with the default configuration.

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.

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 TaskPool

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

Formats the value using the given formatter.

impl Default for TaskPool

fn default() -> TaskPool

Returns the “default value” for a type.

impl Drop for TaskPool

fn drop(&mut self)

Executes the destructor for this type.