Added peeking to EventReader

crates/bevy_app/src/app.rs

@@ -4,7 +4,7 @@ use crate::{
 };
 pub use bevy_derive::AppLabel;
 use bevy_ecs::{
-    event::{event_update_system, ManualEventReader},
+    event::{event_update_system, EventCursor},
     intern::Interned,
     prelude::*,
     schedule::{ScheduleBuildSettings, ScheduleLabel},
@@ -818,7 +818,7 @@ impl App {
     /// This should be called after every [`update()`](App::update) otherwise you risk
     /// dropping possible [`AppExit`] events.
     pub fn should_exit(&self) -> Option<AppExit> {
-        let mut reader = ManualEventReader::default();
+        let mut reader = EventCursor::default();
 
         let events = self.world().get_resource::<Events<AppExit>>()?;
         let mut events = reader.read(events);

crates/bevy_asset/src/lib.rs

@@ -454,7 +454,7 @@ mod tests {
     use bevy_core::TaskPoolPlugin;
     use bevy_ecs::prelude::*;
     use bevy_ecs::{
-        event::ManualEventReader,
+        event::EventCursor,
         schedule::{LogLevel, ScheduleBuildSettings},
     };
     use bevy_log::LogPlugin;
@@ -1300,7 +1300,7 @@ mod tests {
         gate_opener.open(b_path);
         gate_opener.open(c_path);
 
-        let mut reader = ManualEventReader::default();
+        let mut reader = EventCursor::default();
         run_app_until(&mut app, |world| {
             let events = world.resource::<Events<AssetEvent<LoadedFolder>>>();
             let asset_server = world.resource::<AssetServer>();

crates/bevy_ecs/src/event/collections.rs

@@ -1,6 +1,6 @@
 use crate as bevy_ecs;
 use bevy_ecs::{
-    event::{Event, EventId, EventInstance, ManualEventReader},
+    event::{Event, EventCursor, EventId, EventInstance},
     system::Resource,
 };
 #[cfg(feature = "bevy_reflect")]
@@ -153,15 +153,37 @@ impl<E: Event> Events<E> {
         self.send(Default::default())
     }
 
-    /// Gets a new [`ManualEventReader`]. This will include all events already in the event buffers.
-    pub fn get_reader(&self) -> ManualEventReader<E> {
-        ManualEventReader::default()
+    /// Gets a new [`EventCursor`]. This will include all events already in the event buffers.
+    pub fn get_cursor(&self) -> EventCursor<E> {
+        EventCursor::default()
     }
 
-    /// Gets a new [`ManualEventReader`]. This will ignore all events already in the event buffers.
+    /// Gets a new [`EventCursor`]. This will ignore all events already in the event buffers.
     /// It will read all future events.
-    pub fn get_reader_current(&self) -> ManualEventReader<E> {
-        ManualEventReader {
+    pub fn get_cursor_current(&self) -> EventCursor<E> {
+        EventCursor {
+            last_event_count: self.event_count,
+            ..Default::default()
+        }
+    }
+
+    #[deprecated(
+        since = "0.14.0",
+        note = "`get_reader` has been deprecated. Please use `get_cursor` instead."
+    )]
+    /// Gets a new [`EventCursor`]. This will include all events already in the event buffers.
+    pub fn get_reader(&self) -> EventCursor<E> {
+        EventCursor::default()
+    }
+
+    #[deprecated(
+        since = "0.14.0",
+        note = "`get_reader_current` has been replaced. Please use `get_cursor_current` instead."
+    )]
+    /// Gets a new [`EventCursor`]. This will ignore all events already in the event buffers.
+    /// It will read all future events.
+    pub fn get_reader_current(&self) -> EventCursor<E> {
+        EventCursor {
             last_event_count: self.event_count,
             ..Default::default()
         }

crates/bevy_ecs/src/event/event_cursor.rs

@@ -0,0 +1,167 @@
+use crate as bevy_ecs;
+use bevy_ecs::event::{
+    Event, EventMutIterator, EventMutIteratorWithId, EventPeekIterator, EventPeekIteratorWithId,
+    EventReadIterator, EventReadIteratorWithId, Events,
+};
+#[cfg(feature = "multi_threaded")]
+use bevy_ecs::event::{EventMutParIter, EventPeekParIter, EventReadParIter};
+use std::marker::PhantomData;
+
+// Deprecated in favor of `EventCursor`, there is no nice way to deprecate this
+// because generic constraints are not allowed in type aliases, so this will always
+// 'dead code'. Hence the `#[allow(dead_code)]`.
+#[deprecated(
+    since = "0.14.0",
+    note = "`ManualEventReader` has been replaced. Please use `EventCursor` instead."
+)]
+#[doc(alias = "EventCursor")]
+#[allow(dead_code)]
+pub type ManualEventReader<E> = EventCursor<E>;
+
+/// Stores the state for an [`EventReader`] or [`EventMutator`].
+///
+/// Access to the [`Events<E>`] resource is required to read any incoming events.
+///
+/// In almost all cases, you should just use an [`EventReader`] or [`EventMutator`],
+/// which will automatically manage the state for you.
+///
+/// However, this type can be useful if you need to manually track events,
+/// such as when you're attempting to send and receive events of the same type in the same system.
+///
+/// # Example
+///
+/// ```
+/// use bevy_ecs::prelude::*;
+/// use bevy_ecs::event::{Event, Events, EventCursor};
+///
+/// #[derive(Event, Clone, Debug)]
+/// struct MyEvent;
+///
+/// /// A system that both sends and receives events using a [`Local`] [`EventCursor`].
+/// fn send_and_receive_events(
+///     // The `Local` `SystemParam` stores state inside the system itself, rather than in the world.
+///     // `EventCursor<T>` is the internal state of `EventMutator<T>`, which tracks which events have been seen.
+///     mut local_event_reader: Local<EventCursor<MyEvent>>,
+///     // We can access the `Events` resource mutably, allowing us to both read and write its contents.
+///     mut events: ResMut<Events<MyEvent>>,
+/// ) {
+///     // We must collect the events to resend, because we can't mutate events while we're iterating over the events.
+///     let mut events_to_resend = Vec::new();
+///
+///     for event in local_event_reader.read(&mut events) {
+///          events_to_resend.push(event.clone());
+///     }
+///
+///     for event in events_to_resend {
+///         events.send(MyEvent);
+///     }
+/// }
+///
+/// # bevy_ecs::system::assert_is_system(send_and_receive_events);
+/// ```
+#[derive(Debug)]
+pub struct EventCursor<E: Event> {
+    pub(super) last_event_count: usize,
+    pub(super) _marker: PhantomData<E>,
+}
+
+impl<E: Event> Default for EventCursor<E> {
+    fn default() -> Self {
+        EventCursor {
+            last_event_count: 0,
+            _marker: Default::default(),
+        }
+    }
+}
+
+impl<E: Event> Clone for EventCursor<E> {
+    fn clone(&self) -> Self {
+        EventCursor {
+            last_event_count: self.last_event_count,
+            _marker: PhantomData,
+        }
+    }
+}
+
+#[allow(clippy::len_without_is_empty)] // Check fails since the is_empty implementation has a signature other than `(&self) -> bool`
+impl<E: Event> EventCursor<E> {
+    /// See [`EventReader::read`]
+    pub fn read<'a>(&'a mut self, events: &'a Events<E>) -> EventReadIterator<'a, E> {
+        self.read_with_id(events).without_id()
+    }
+
+    /// See [`EventReader::peek`]
+    pub fn peek<'a>(&'a self, events: &'a Events<E>) -> EventPeekIterator<'a, E> {
+        self.peek_with_id(events).without_id()
+    }
+
+    /// See [`EventMutator::read`]
+    pub fn read_mut<'a>(&'a mut self, events: &'a mut Events<E>) -> EventMutIterator<'a, E> {
+        self.read_mut_with_id(events).without_id()
+    }
+
+    /// See [`EventReader::read_with_id`]
+    pub fn read_with_id<'a>(&'a mut self, events: &'a Events<E>) -> EventReadIteratorWithId<'a, E> {
+        EventReadIteratorWithId::new(self, events)
+    }
+
+    /// See [`EventReader::peek_with_id`]
+    pub fn peek_with_id<'a>(&'a self, events: &'a Events<E>) -> EventPeekIteratorWithId<'a, E> {
+        EventPeekIteratorWithId::new(self, events)
+    }
+
+    /// See [`EventMutator::read_with_id`]
+    pub fn read_mut_with_id<'a>(
+        &'a mut self,
+        events: &'a mut Events<E>,
+    ) -> EventMutIteratorWithId<'a, E> {
+        EventMutIteratorWithId::new(self, events)
+    }
+
+    /// See [`EventReader::par_read`]
+    #[cfg(feature = "multi_threaded")]
+    pub fn par_read<'a>(&'a mut self, events: &'a Events<E>) -> EventReadParIter<'a, E> {
+        EventReadParIter::new(self, events)
+    }
+
+    /// See [`EventMutator::par_read`]
+    #[cfg(feature = "multi_threaded")]
+    pub fn par_read_mut<'a>(&'a mut self, events: &'a mut Events<E>) -> EventMutParIter<'a, E> {
+        EventMutParIter::new(self, events)
+    }
+
+    /// See [`EventReader::par_peek`]
+    #[cfg(feature = "multi_threaded")]
+    pub fn par_peek<'a>(&'a self, events: &'a Events<E>) -> EventPeekParIter<'a, E> {
+        EventPeekParIter::new(self, events)
+    }
+
+    /// See [`EventReader::len`]
+    pub fn len(&self, events: &Events<E>) -> usize {
+        // The number of events in this reader is the difference between the most recent event
+        // and the last event seen by it. This will be at most the number of events contained
+        // with the events (any others have already been dropped)
+        // TODO: Warn when there are dropped events, or return e.g. a `Result<usize, (usize, usize)>`
+        events
+            .event_count
+            .saturating_sub(self.last_event_count)
+            .min(events.len())
+    }
+
+    /// Amount of events we missed.
+    pub fn missed_events(&self, events: &Events<E>) -> usize {
+        events
+            .oldest_event_count()
+            .saturating_sub(self.last_event_count)
+    }
+
+    /// See [`EventReader::is_empty()`]
+    pub fn is_empty(&self, events: &Events<E>) -> bool {
+        self.len(events) == 0
+    }
+
+    /// See [`EventReader::clear()`]
+    pub fn clear(&mut self, events: &Events<E>) {
+        self.last_event_count = events.event_count;
+    }
+}