Struct bevy::ecs::prelude::Deferred

pub struct Deferred<'a, T>(/* private fields */)
where
    T: SystemBuffer;
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§

§

impl<T> Deferred<'_, T>
where T: SystemBuffer,

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§

§

impl<'a, T> Deref for Deferred<'a, T>
where T: SystemBuffer,

§

type Target = T

The resulting type after dereferencing.
§

fn deref(&self) -> &<Deferred<'a, T> as Deref>::Target

Dereferences the value.
§

impl<'a, T> DerefMut for Deferred<'a, T>
where T: SystemBuffer,

§

fn deref_mut(&mut self) -> &mut <Deferred<'a, T> as Deref>::Target

Mutably dereferences the value.
§

impl<T> SystemParam for Deferred<'_, T>
where T: SystemBuffer,

§

type State = SyncCell<T>

Used to store data which persists across invocations of a system.
§

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 more
§

fn init_state( world: &mut World, system_meta: &mut SystemMeta ) -> <Deferred<'_, T> as SystemParam>::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.
§

fn apply( state: &mut <Deferred<'_, T> as SystemParam>::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.
§

unsafe fn get_param<'w, 's>( state: &'s mut <Deferred<'_, T> as SystemParam>::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, _change_tick: Tick ) -> <Deferred<'_, T> as SystemParam>::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction. Read more
§

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 more
§

impl<T> ReadOnlySystemParam for Deferred<'_, T>
where T: SystemBuffer,

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> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<T, U> AsBindGroupShaderType<U> for T
where U: ShaderType, &'a T: for<'a> Into<U>,

§

fn as_bind_group_shader_type(&self, _images: &RenderAssets<GpuImage>) -> U

Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist.
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast<T> for T

§

fn downcast(&self) -> &T

§

impl<T> Downcast for T
where T: 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.
§

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.
§

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.
§

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.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<S> FromSample<S> for S

§

fn from_sample_(s: S) -> S

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<F, T> IntoSample<T> for F
where T: FromSample<F>,

§

fn into_sample(self) -> T

§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

§

fn to_sample_(self) -> U

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> Upcast<T> for T

§

fn upcast(&self) -> Option<&T>

§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
§

impl<T> ConditionalSend for T
where T: Send,

§

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,

§

impl<T> Settings for T
where T: 'static + Send + Sync,

§

impl<T> WasmNotSend for T
where T: Send,

§

impl<T> WasmNotSendSync for T
where T: WasmNotSend + WasmNotSync,

§

impl<T> WasmNotSync for T
where T: Sync,