Struct bevy_tasks::TaskPool
source · pub struct TaskPool { /* private fields */ }
Expand description
A thread pool for executing tasks. Tasks are futures that are being automatically driven by the pool on threads owned by the pool.
Implementations§
source§impl TaskPool
impl TaskPool
sourcepub fn get_thread_executor() -> Arc<ThreadExecutor<'static>>
pub fn get_thread_executor() -> Arc<ThreadExecutor<'static>>
Each thread should only create one ThreadExecutor
, otherwise, there are good chances they will deadlock
sourcepub fn thread_num(&self) -> usize
pub fn thread_num(&self) -> usize
Return the number of threads owned by the task pool
sourcepub fn scope<'env, F, T>(&self, f: F) -> Vec<T>where
F: for<'scope> FnOnce(&'scope Scope<'scope, 'env, T>),
T: Send + 'static,
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 rayon::scope
and crossbeam::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);
});
});
}
sourcepub 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,
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.
sourcepub fn spawn<T>(
&self,
future: impl Future<Output = T> + Send + 'static
) -> Task<T> ⓘwhere
T: Send + 'static,
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. It can also be canceled and “detached” allowing it to continue running without having to be polled by the end-user.
If the provided future is non-Send
, TaskPool::spawn_local
should be used instead.
sourcepub fn spawn_local<T>(
&self,
future: impl Future<Output = T> + 'static
) -> Task<T> ⓘwhere
T: 'static,
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.
It can also be canceled and “detached” allowing it to continue running without having
to be polled by the end-user. Users should generally prefer to use TaskPool::spawn
instead, unless the provided future is not Send
.
sourcepub fn with_local_executor<F, R>(&self, f: F) -> Rwhere
F: FnOnce(&LocalExecutor<'_>) -> R,
pub fn with_local_executor<F, R>(&self, f: F) -> Rwhere 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();
});