Struct bevy::tasks::prelude::AsyncComputeTaskPool
pub struct AsyncComputeTaskPool(_);
Expand description
A newtype for a task pool for CPU-intensive work that may span across multiple frames
Implementations§
§impl AsyncComputeTaskPool
impl AsyncComputeTaskPool
pub fn init(f: impl FnOnce() -> TaskPool) -> &'static AsyncComputeTaskPool
pub fn init(f: impl FnOnce() -> TaskPool) -> &'static AsyncComputeTaskPool
Initializes the global AsyncComputeTaskPool
instance.
pub fn get() -> &'static AsyncComputeTaskPool
pub fn get() -> &'static AsyncComputeTaskPool
Methods from Deref<Target = TaskPool>§
pub fn thread_num(&self) -> usize
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, Global> ⓘwhere
F: for<'scope> FnOnce(&'scope Scope<'scope, 'env, T>),
T: 'static + Send,
pub fn scope<'env, F, T>(&self, f: F) -> Vec<T, Global> ⓘwhere
F: for<'scope> FnOnce(&'scope Scope<'scope, 'env, T>),
T: 'static + Send,
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);
});
});
}
pub fn spawn<T>(
&self,
future: impl Future<Output = T> + Send + 'static
) -> Task<T> ⓘwhere
T: 'static + Send,
pub fn spawn<T>(
&self,
future: impl Future<Output = T> + Send + 'static
) -> Task<T> ⓘwhere
T: 'static + Send,
Spawns a static future onto the thread pool. The returned Task is a future. It can also be cancelled 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.
pub 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 cancelled 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
.
pub 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();
});
Trait Implementations§
§impl Debug for AsyncComputeTaskPool
impl Debug for AsyncComputeTaskPool
Auto Trait Implementations§
impl !RefUnwindSafe for AsyncComputeTaskPool
impl Send for AsyncComputeTaskPool
impl Sync for AsyncComputeTaskPool
impl Unpin for AsyncComputeTaskPool
impl !UnwindSafe for AsyncComputeTaskPool
Blanket Implementations§
§impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
§fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
T
ShaderType
for self
. When used in AsBindGroup
derives, it is safe to assume that all images in self
exist. Read more§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
. Read more§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read more§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s. Read more§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s. Read more