Struct IoTaskPool

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

A newtype for a task pool for IO-intensive work (i.e. tasks that spend very little time in a “woken” state)

See TaskPool documentation for details on Bevy tasks.

Implementations

impl IoTaskPool

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

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

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

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

pub fn get() -> &'static IoTaskPool

Gets the global IoTaskPool 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.

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 IoTaskPool

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

Formats the value using the given formatter.

impl Deref for IoTaskPool

type Target = TaskPool

The resulting type after dereferencing.

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

Dereferences the value.