pub struct Deferred<'a, T: SystemBuffer>(/* private fields */);
Expand description
A SystemParam
that stores a buffer which gets applied to the World
during
apply_deferred
.
This is used internally by Commands
to defer World
mutations.
§Examples
By using this type to defer mutations, you can avoid mutable World
access within
a system, which allows it to run in parallel with more systems.
Note that deferring mutations is not free, and should only be used if
the gains in parallelization outweigh the time it takes to apply deferred mutations.
In general, Deferred
should only be used for mutations that are infrequent,
or which otherwise take up a small portion of a system’s run-time.
// Tracks whether or not there is a threat the player should be aware of.
#[derive(Resource, Default)]
pub struct Alarm(bool);
#[derive(Component)]
pub struct Settlement {
// ...
}
// A threat from inside the settlement.
#[derive(Component)]
pub struct Criminal;
// A threat from outside the settlement.
#[derive(Component)]
pub struct Monster;
use bevy_ecs::system::{Deferred, SystemBuffer, SystemMeta};
// Uses deferred mutations to allow signalling the alarm from multiple systems in parallel.
#[derive(Resource, Default)]
struct AlarmFlag(bool);
impl AlarmFlag {
/// Sounds the alarm the next time buffers are applied via apply_deferred.
pub fn flag(&mut self) {
self.0 = true;
}
}
impl SystemBuffer for AlarmFlag {
// When `AlarmFlag` is used in a system, this function will get
// called the next time buffers are applied via apply_deferred.
fn apply(&mut self, system_meta: &SystemMeta, world: &mut World) {
if self.0 {
world.resource_mut::<Alarm>().0 = true;
self.0 = false;
}
}
}
// Sound the alarm if there are any criminals who pose a threat.
fn alert_criminal(
settlements: Query<&Settlement>,
criminals: Query<&Criminal>,
mut alarm: Deferred<AlarmFlag>
) {
let settlement = settlements.single();
for criminal in &criminals {
// Only sound the alarm if the criminal is a threat.
// For this example, assume that this check is expensive to run.
// Since the majority of this system's run-time is dominated
// by calling `is_threat()`, we defer sounding the alarm to
// allow this system to run in parallel with other alarm systems.
if criminal.is_threat(settlement) {
alarm.flag();
}
}
}
// Sound the alarm if there is a monster.
fn alert_monster(
monsters: Query<&Monster>,
mut alarm: ResMut<Alarm>
) {
if monsters.iter().next().is_some() {
// Since this system does nothing except for sounding the alarm,
// it would be pointless to defer it, so we sound the alarm directly.
alarm.0 = true;
}
}
let mut world = World::new();
world.init_resource::<Alarm>();
world.spawn(Settlement {
// ...
});
let mut schedule = Schedule::default();
// These two systems have no conflicts and will run in parallel.
schedule.add_systems((alert_criminal, alert_monster));
// There are no criminals or monsters, so the alarm is not sounded.
schedule.run(&mut world);
assert_eq!(world.resource::<Alarm>().0, false);
// Spawn a monster, which will cause the alarm to be sounded.
let m_id = world.spawn(Monster).id();
schedule.run(&mut world);
assert_eq!(world.resource::<Alarm>().0, true);
// Remove the monster and reset the alarm.
world.entity_mut(m_id).despawn();
world.resource_mut::<Alarm>().0 = false;
// Spawn a criminal, which will cause the alarm to be sounded.
world.spawn(Criminal);
schedule.run(&mut world);
assert_eq!(world.resource::<Alarm>().0, true);
Implementations§
source§impl<T: SystemBuffer> Deferred<'_, T>
impl<T: SystemBuffer> Deferred<'_, T>
sourcepub fn reborrow(&mut self) -> Deferred<'_, T>
pub fn reborrow(&mut self) -> Deferred<'_, T>
Returns a Deferred<T>
with a smaller lifetime.
This is useful if you have &mut Deferred<T>
but need Deferred<T>
.
Trait Implementations§
source§impl<'a, T: SystemBuffer> Deref for Deferred<'a, T>
impl<'a, T: SystemBuffer> Deref for Deferred<'a, T>
source§impl<'a, T: SystemBuffer> DerefMut for Deferred<'a, T>
impl<'a, T: SystemBuffer> DerefMut for Deferred<'a, T>
source§impl<T: SystemBuffer> SystemParam for Deferred<'_, T>
impl<T: SystemBuffer> SystemParam for Deferred<'_, T>
§type Item<'w, 's> = Deferred<'s, T>
type Item<'w, 's> = Deferred<'s, T>
The item type returned when constructing this system param.
The value of this associated type should be
Self
, instantiated with new lifetimes. Read moresource§fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State
fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State
Registers any
World
access used by this SystemParam
and creates a new instance of this param’s State
.source§fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
Applies any deferred mutations stored in this
SystemParam
’s state.
This is used to apply Commands
during apply_deferred
.source§fn queue(
state: &mut Self::State,
system_meta: &SystemMeta,
world: DeferredWorld<'_>
)
fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_> )
Queues any deferred mutations to be applied at the next
apply_deferred
.source§unsafe fn get_param<'w, 's>(
state: &'s mut Self::State,
_system_meta: &SystemMeta,
_world: UnsafeWorldCell<'w>,
_change_tick: Tick
) -> Self::Item<'w, 's>
unsafe fn get_param<'w, 's>( state: &'s mut Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, _change_tick: Tick ) -> Self::Item<'w, 's>
Creates a parameter to be passed into a
SystemParamFunction
. Read moresource§unsafe fn new_archetype(
state: &mut Self::State,
archetype: &Archetype,
system_meta: &mut SystemMeta
)
unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta )
For the specified
Archetype
, registers the components accessed by this SystemParam
(if applicable).a Read moreimpl<T: SystemBuffer> ReadOnlySystemParam for Deferred<'_, T>
Auto Trait Implementations§
impl<'a, T> Freeze for Deferred<'a, T>
impl<'a, T> RefUnwindSafe for Deferred<'a, T>where
T: RefUnwindSafe,
impl<'a, T> Send for Deferred<'a, T>
impl<'a, T> Sync for Deferred<'a, T>where
T: Sync,
impl<'a, T> Unpin for Deferred<'a, T>
impl<'a, T> !UnwindSafe for Deferred<'a, T>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Convert
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
.source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Convert
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
Convert
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
Convert
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.