pub struct Events<E: Event> { /* private fields */ }
Expand description
An event collection that represents the events that occurred within the last two
Events::update
calls.
Events can be written to using an EventWriter
and are typically cheaply read using an EventReader
.
Each event can be consumed by multiple systems, in parallel,
with consumption tracked by the EventReader
on a per-system basis.
If no ordering
is applied between writing and reading systems, there is a risk of a race condition.
This means that whether the events arrive before or after the next Events::update
is unpredictable.
This collection is meant to be paired with a system that calls
Events::update
exactly once per update/frame.
event_update_system
is a system that does this, typically initialized automatically using
add_event
.
EventReader
s are expected to read events from this collection at least once per loop/frame.
Events will persist across a single frame boundary and so ordering of event producers and
consumers is not critical (although poorly-planned ordering may cause accumulating lag).
If events are not handled by the end of the frame after they are updated, they will be
dropped silently.
§Example
use bevy_ecs::event::{Event, Events};
#[derive(Event)]
struct MyEvent {
value: usize
}
// setup
let mut events = Events::<MyEvent>::default();
let mut reader = events.get_reader();
// run this once per update/frame
events.update();
// somewhere else: send an event
events.send(MyEvent { value: 1 });
// somewhere else: read the events
for event in reader.read(&events) {
assert_eq!(event.value, 1)
}
// events are only processed once per reader
assert_eq!(reader.read(&events).count(), 0);
§Details
Events
is implemented using a variation of a double buffer strategy.
Each call to update
swaps buffers and clears out the oldest one.
EventReader
s will read events from both buffers.EventReader
s that read at least once per update will never drop events.EventReader
s that read once within two updates might still receive some eventsEventReader
s that read after two updates are guaranteed to drop all events that occurred before those updates.
The buffers in Events
will grow indefinitely if update
is never called.
An alternative call pattern would be to call update
manually across frames to control when events are cleared.
This complicates consumption and risks ever-expanding memory usage if not cleaned up,
but can be done by adding your event as a resource instead of using
add_event
.
Implementations§
source§impl<E: Event> Events<E>
impl<E: Event> Events<E>
sourcepub fn oldest_event_count(&self) -> usize
pub fn oldest_event_count(&self) -> usize
Returns the index of the oldest event stored in the event buffer.
sourcepub fn send(&mut self, event: E) -> EventId<E>
pub fn send(&mut self, event: E) -> EventId<E>
“Sends” an event
by writing it to the current event buffer. EventReader
s can then read
the event.
This method returns the ID of the sent event
.
sourcepub fn send_batch(
&mut self,
events: impl IntoIterator<Item = E>
) -> SendBatchIds<E> ⓘ
pub fn send_batch( &mut self, events: impl IntoIterator<Item = E> ) -> SendBatchIds<E> ⓘ
Sends a list of events
all at once, which can later be read by EventReader
s.
This is more efficient than sending each event individually.
This method returns the IDs of the sent events
.
sourcepub fn send_default(&mut self) -> EventId<E>where
E: Default,
pub fn send_default(&mut self) -> EventId<E>where
E: Default,
Sends the default value of the event. Useful when the event is an empty struct.
This method returns the ID of the sent event
.
sourcepub fn get_reader(&self) -> ManualEventReader<E>
pub fn get_reader(&self) -> ManualEventReader<E>
Gets a new ManualEventReader
. This will include all events already in the event buffers.
sourcepub fn get_reader_current(&self) -> ManualEventReader<E>
pub fn get_reader_current(&self) -> ManualEventReader<E>
Gets a new ManualEventReader
. This will ignore all events already in the event buffers.
It will read all future events.
sourcepub fn update(&mut self)
pub fn update(&mut self)
Swaps the event buffers and clears the oldest event buffer. In general, this should be called once per frame/update.
If you need access to the events that were removed, consider using Events::update_drain
.
sourcepub fn update_drain(&mut self) -> impl Iterator<Item = E> + '_
pub fn update_drain(&mut self) -> impl Iterator<Item = E> + '_
Swaps the event buffers and drains the oldest event buffer, returning an iterator of all events that were removed. In general, this should be called once per frame/update.
If you do not need to take ownership of the removed events, use Events::update
instead.
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true if there are no events currently stored in the event buffer.
sourcepub fn drain(&mut self) -> impl Iterator<Item = E> + '_
pub fn drain(&mut self) -> impl Iterator<Item = E> + '_
Creates a draining iterator that removes all events.
sourcepub fn iter_current_update_events(&self) -> impl ExactSizeIterator<Item = &E>
pub fn iter_current_update_events(&self) -> impl ExactSizeIterator<Item = &E>
Iterates over events that happened since the last “update” call.
WARNING: You probably don’t want to use this call. In most cases you should use an
EventReader
. You should only use this if you know you only need to consume events
between the last update()
call and your call to iter_current_update_events
.
If events happen outside that window, they will not be handled. For example, any events that
happen after this call and before the next update()
call will be dropped.
Trait Implementations§
source§impl<E: Event> Extend<E> for Events<E>
impl<E: Event> Extend<E> for Events<E>
source§fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = E>,
fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = E>,
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl<E> FromReflect for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
impl<E> FromReflect for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
source§fn from_reflect(reflect: &dyn Reflect) -> Option<Self>
fn from_reflect(reflect: &dyn Reflect) -> Option<Self>
Self
from a reflected value.source§fn take_from_reflect(
reflect: Box<dyn Reflect>
) -> Result<Self, Box<dyn Reflect>>
fn take_from_reflect( reflect: Box<dyn Reflect> ) -> Result<Self, Box<dyn Reflect>>
Self
using,
constructing the value using from_reflect
if that fails. Read moresource§impl<E> GetTypeRegistration for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
impl<E> GetTypeRegistration for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
source§fn get_type_registration() -> TypeRegistration
fn get_type_registration() -> TypeRegistration
TypeRegistration
for this type.source§fn register_type_dependencies(registry: &mut TypeRegistry)
fn register_type_dependencies(registry: &mut TypeRegistry)
source§impl<E> Reflect for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
impl<E> Reflect for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
source§fn get_represented_type_info(&self) -> Option<&'static TypeInfo>
fn get_represented_type_info(&self) -> Option<&'static TypeInfo>
source§fn as_any_mut(&mut self) -> &mut dyn Any
fn as_any_mut(&mut self) -> &mut dyn Any
&mut dyn Any
.source§fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>
fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>
source§fn as_reflect(&self) -> &dyn Reflect
fn as_reflect(&self) -> &dyn Reflect
source§fn as_reflect_mut(&mut self) -> &mut dyn Reflect
fn as_reflect_mut(&mut self) -> &mut dyn Reflect
source§fn clone_value(&self) -> Box<dyn Reflect>
fn clone_value(&self) -> Box<dyn Reflect>
Reflect
trait object. Read moresource§fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>
fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>
source§fn reflect_kind(&self) -> ReflectKind
fn reflect_kind(&self) -> ReflectKind
source§fn reflect_ref(&self) -> ReflectRef<'_>
fn reflect_ref(&self) -> ReflectRef<'_>
source§fn reflect_mut(&mut self) -> ReflectMut<'_>
fn reflect_mut(&mut self) -> ReflectMut<'_>
source§fn reflect_owned(self: Box<Self>) -> ReflectOwned
fn reflect_owned(self: Box<Self>) -> ReflectOwned
source§fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>
fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>
source§fn apply(&mut self, value: &(dyn Reflect + 'static))
fn apply(&mut self, value: &(dyn Reflect + 'static))
source§fn reflect_hash(&self) -> Option<u64>
fn reflect_hash(&self) -> Option<u64>
source§fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>
fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>
source§fn serializable(&self) -> Option<Serializable<'_>>
fn serializable(&self) -> Option<Serializable<'_>>
source§fn is_dynamic(&self) -> bool
fn is_dynamic(&self) -> bool
source§impl<E> Struct for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
impl<E> Struct for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
source§fn field(&self, name: &str) -> Option<&dyn Reflect>
fn field(&self, name: &str) -> Option<&dyn Reflect>
name
as a &dyn Reflect
.source§fn field_mut(&mut self, name: &str) -> Option<&mut dyn Reflect>
fn field_mut(&mut self, name: &str) -> Option<&mut dyn Reflect>
name
as a
&mut dyn Reflect
.source§fn field_at(&self, index: usize) -> Option<&dyn Reflect>
fn field_at(&self, index: usize) -> Option<&dyn Reflect>
index
as a
&dyn Reflect
.source§fn field_at_mut(&mut self, index: usize) -> Option<&mut dyn Reflect>
fn field_at_mut(&mut self, index: usize) -> Option<&mut dyn Reflect>
index
as a &mut dyn Reflect
.source§fn name_at(&self, index: usize) -> Option<&str>
fn name_at(&self, index: usize) -> Option<&str>
index
.source§fn iter_fields(&self) -> FieldIter<'_>
fn iter_fields(&self) -> FieldIter<'_>
source§fn clone_dynamic(&self) -> DynamicStruct
fn clone_dynamic(&self) -> DynamicStruct
DynamicStruct
.source§impl<E> TypePath for Events<E>
impl<E> TypePath for Events<E>
source§fn type_path() -> &'static str
fn type_path() -> &'static str
source§fn short_type_path() -> &'static str
fn short_type_path() -> &'static str
source§fn type_ident() -> Option<&'static str>
fn type_ident() -> Option<&'static str>
source§fn crate_name() -> Option<&'static str>
fn crate_name() -> Option<&'static str>
source§impl<E> Typed for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
impl<E> Typed for Events<E>where
Self: Any + Send + Sync,
E: TypePath + Event,
EventSequence<E>: FromReflect + TypePath + RegisterForReflection,
usize: FromReflect + TypePath + RegisterForReflection,
impl<E: Event> Resource for Events<E>
Auto Trait Implementations§
impl<E> Freeze for Events<E>
impl<E> RefUnwindSafe for Events<E>where
E: RefUnwindSafe,
impl<E> Send for Events<E>
impl<E> Sync for Events<E>
impl<E> Unpin for Events<E>where
E: Unpin,
impl<E> UnwindSafe for Events<E>where
E: UnwindSafe,
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
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>
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>
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)
&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)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.source§impl<T> DowncastSync for T
impl<T> DowncastSync for T
source§impl<T> DynamicTypePath for Twhere
T: TypePath,
impl<T> DynamicTypePath for Twhere
T: TypePath,
source§fn reflect_type_path(&self) -> &str
fn reflect_type_path(&self) -> &str
TypePath::type_path
.source§fn reflect_short_type_path(&self) -> &str
fn reflect_short_type_path(&self) -> &str
source§fn reflect_type_ident(&self) -> Option<&str>
fn reflect_type_ident(&self) -> Option<&str>
TypePath::type_ident
.source§fn reflect_crate_name(&self) -> Option<&str>
fn reflect_crate_name(&self) -> Option<&str>
TypePath::crate_name
.source§fn reflect_module_path(&self) -> Option<&str>
fn reflect_module_path(&self) -> Option<&str>
source§impl<T> FromWorld for Twhere
T: Default,
impl<T> FromWorld for Twhere
T: Default,
source§fn from_world(_world: &mut World) -> T
fn from_world(_world: &mut World) -> T
Self
using data from the given World
.source§impl<S> GetField for Swhere
S: Struct,
impl<S> GetField for Swhere
S: Struct,
source§impl<T> GetPath for T
impl<T> GetPath for T
source§fn reflect_path<'p>(
&self,
path: impl ReflectPath<'p>
) -> Result<&(dyn Reflect + 'static), ReflectPathError<'p>>
fn reflect_path<'p>( &self, path: impl ReflectPath<'p> ) -> Result<&(dyn Reflect + 'static), ReflectPathError<'p>>
path
. Read moresource§fn reflect_path_mut<'p>(
&mut self,
path: impl ReflectPath<'p>
) -> Result<&mut (dyn Reflect + 'static), ReflectPathError<'p>>
fn reflect_path_mut<'p>( &mut self, path: impl ReflectPath<'p> ) -> Result<&mut (dyn Reflect + 'static), ReflectPathError<'p>>
path
. Read moresource§fn path<'p, T>(
&self,
path: impl ReflectPath<'p>
) -> Result<&T, ReflectPathError<'p>>where
T: Reflect,
fn path<'p, T>(
&self,
path: impl ReflectPath<'p>
) -> Result<&T, ReflectPathError<'p>>where
T: Reflect,
path
. Read moresource§fn path_mut<'p, T>(
&mut self,
path: impl ReflectPath<'p>
) -> Result<&mut T, ReflectPathError<'p>>where
T: Reflect,
fn path_mut<'p, T>(
&mut self,
path: impl ReflectPath<'p>
) -> Result<&mut T, ReflectPathError<'p>>where
T: Reflect,
path
. Read more