pub struct Events<T> { /* 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.
This collection is meant to be paired with a system that calls
Events::update
exactly once per update/frame.
Events::update_system
is a system that does this, typically intialized automatically using
App::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::Events;
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.iter(&events) {
assert_eq!(event.value, 1)
}
// events are only processed once per reader
assert_eq!(reader.iter(&events).count(), 0);
Details
Events
is implemented using a double buffer. Each call to Events::update
swaps buffers
and clears out the oldest buffer. 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 events.
EventReader
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 Events::update
is never called.
An alternative call pattern would be to call Events::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 App::add_event
.
Implementations
impl<T> Events<T> where
T: Resource,
impl<T> Events<T> where
T: Resource,
pub fn send(&mut self, event: T)
pub fn send(&mut self, event: T)
“Sends” an event
by writing it to the current event buffer. EventReader
s can then read
the event.
pub fn get_reader(&self) -> ManualEventReader<T>
pub fn get_reader(&self) -> ManualEventReader<T>
Gets a new ManualEventReader
. This will include all events already in the event buffers.
pub fn get_reader_current(&self) -> ManualEventReader<T>
pub fn get_reader_current(&self) -> ManualEventReader<T>
Gets a new ManualEventReader
. This will ignore all events already in the event buffers.
It will read all future events.
pub 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.
pub fn update_system(events: ResMut<'_, Events<T>>)
pub fn update_system(events: ResMut<'_, Events<T>>)
A system that calls Events::update
once per frame.
pub fn clear(&mut self)
pub fn clear(&mut self)
Removes all events.
pub fn drain(&mut self) -> impl Iterator<Item = T>
pub fn drain(&mut self) -> impl Iterator<Item = T>
Creates a draining iterator that removes all events.
pub fn iter_current_update_events(&self) -> impl DoubleEndedIterator
pub fn iter_current_update_events(&self) -> impl DoubleEndedIterator
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
impl<T> Extend<T> for Events<T>
impl<T> Extend<T> for Events<T>
pub fn extend<I>(&mut self, iter: I) where
I: IntoIterator<Item = T>,
pub fn extend<I>(&mut self, iter: I) where
I: IntoIterator<Item = T>,
Extends a collection with the contents of an iterator. Read more
sourcefn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)Extends a collection with exactly one element.
sourcefn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)Reserves capacity in a collection for the given number of additional elements. Read more
Auto Trait Implementations
impl<T> RefUnwindSafe for Events<T> where
T: RefUnwindSafe,
impl<T> Send for Events<T> where
T: Send,
impl<T> Sync for Events<T> where
T: Sync,
impl<T> Unpin for Events<T> where
T: Unpin,
impl<T> UnwindSafe for Events<T> where
T: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> Downcast for T where
T: Any,
impl<T> Downcast for T where
T: Any,
pub fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>ⓘNotable traits for Box<I, A>impl<I, A> Iterator for Box<I, A> where
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;impl<F, A> Future for Box<F, A> where
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;
pub fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>ⓘNotable traits for Box<I, A>impl<I, A> Iterator for Box<I, A> where
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;impl<F, A> Future for Box<F, A> where
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;impl<F, A> Future for Box<F, A> where
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;
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
. Read more
pub fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
pub fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Convert Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read more
pub fn as_any(&self) -> &(dyn Any + 'static)
pub 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. Read more
pub fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
pub 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. Read more
impl<T> FromWorld for T where
T: Default,
impl<T> FromWorld for T where
T: Default,
pub fn from_world(_world: &mut World) -> T
pub fn from_world(_world: &mut World) -> T
Creates Self
using data from the given World
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
sourcefn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
pub fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
where
S: Into<Dispatch>,
T: Future, type Output = <T as Future>::Output;
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
fn with_current_subscriber(self) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more