Struct EventQueue 

pub struct EventQueue<E: Event> { /* private fields */ }

Double-buffered event queue for storing events of a single type.

EventQueue uses a double-buffer pattern where events are written to the active buffer and read from the inactive buffer. At the end of each frame, swap_buffers is called to switch which buffer is active.

Double-Buffer Pattern

Frame N:
  - Systems write new events to Buffer A (active write buffer)
  - Systems read events from Buffer B (read buffer from Frame N-1)

End of Frame N: swap_buffers()

Frame N+1:
  - Systems write new events to Buffer B (now active write buffer)
  - Systems read events from Buffer A (read buffer from Frame N)

This pattern ensures:

• Writers and readers never access the same buffer simultaneously
• Events persist for exactly one frame after being written
• No locking required within a single-threaded frame

Example

use goud_engine::core::event::EventQueue;

#[derive(Debug, Clone, PartialEq)]
struct DamageEvent { amount: u32 }

let mut queue: EventQueue<DamageEvent> = EventQueue::new();

// Write to active buffer
queue.send(DamageEvent { amount: 10 });
queue.send(DamageEvent { amount: 25 });

// Read buffer is empty (events are in write buffer)
assert!(queue.drain().collect::<Vec<_>>().is_empty());

// Swap buffers at frame boundary
queue.swap_buffers();

// Now we can read the events
let events: Vec<_> = queue.drain().collect();
assert_eq!(events.len(), 2);
assert_eq!(events[0].amount, 10);
assert_eq!(events[1].amount, 25);

Implementations

impl<E: Event> EventQueue<E>

pub fn new() -> Self

Creates a new empty EventQueue.

Both buffers start empty, and Buffer A is the initial write buffer.

Example

use goud_engine::core::event::EventQueue;

struct MyEvent { data: i32 }
let queue: EventQueue<MyEvent> = EventQueue::new();
assert!(queue.is_empty());

pub fn send(&mut self, event: E)

Sends an event to the write buffer.

The event will be available for reading after the next swap_buffers call.

Example

use goud_engine::core::event::EventQueue;

struct ScoreEvent { points: i32 }
let mut queue: EventQueue<ScoreEvent> = EventQueue::new();

queue.send(ScoreEvent { points: 100 });
queue.send(ScoreEvent { points: 50 });

assert_eq!(queue.len(), 2);

pub fn drain(&mut self) -> impl Iterator<Item = E> + '_

Drains all events from the read buffer, returning an iterator.

After draining, the read buffer will be empty. This is the primary way to consume events during a frame.

Example

use goud_engine::core::event::EventQueue;

#[derive(Debug)]
struct Event { id: u32 }

let mut queue: EventQueue<Event> = EventQueue::new();
queue.send(Event { id: 1 });
queue.send(Event { id: 2 });
queue.swap_buffers();

for event in queue.drain() {
    println!("Processing event: {:?}", event);
}

pub fn swap_buffers(&mut self)

Swaps the active and read buffers.

This should be called exactly once per frame, typically at the frame boundary. After swapping:

• The old write buffer becomes the new read buffer
• The old read buffer (now cleared) becomes the new write buffer

Example

use goud_engine::core::event::EventQueue;

struct FrameEvent;
let mut queue: EventQueue<FrameEvent> = EventQueue::new();

// Frame 1: send events
queue.send(FrameEvent);

// End of Frame 1
queue.swap_buffers();

// Frame 2: events from Frame 1 are now readable
let count = queue.drain().count();
assert_eq!(count, 1);

pub fn clear(&mut self)

Clears both buffers, removing all events.

This is useful for resetting the event system, such as when transitioning between game states.

Example

use goud_engine::core::event::EventQueue;

struct Event;
let mut queue: EventQueue<Event> = EventQueue::new();

queue.send(Event);
queue.swap_buffers();
queue.send(Event);

queue.clear();

assert!(queue.is_empty());
assert!(queue.drain().next().is_none());

pub fn is_empty(&self) -> bool

Returns true if the write buffer has no pending events.

Note: This only checks the write buffer. The read buffer may still contain events from the previous frame.

Example

use goud_engine::core::event::EventQueue;

struct Event;
let mut queue: EventQueue<Event> = EventQueue::new();

assert!(queue.is_empty());

queue.send(Event);
assert!(!queue.is_empty());

pub fn len(&self) -> usize

Returns the number of events in the write buffer.

Note: This only counts events in the write buffer (pending events). Use read_len() to count events available for reading.

Example

use goud_engine::core::event::EventQueue;

struct Event;
let mut queue: EventQueue<Event> = EventQueue::new();

assert_eq!(queue.len(), 0);

queue.send(Event);
queue.send(Event);
queue.send(Event);

assert_eq!(queue.len(), 3);

pub fn read_len(&self) -> usize

Returns the number of events available for reading.

Example

use goud_engine::core::event::EventQueue;

struct Event;
let mut queue: EventQueue<Event> = EventQueue::new();

queue.send(Event);
queue.send(Event);

// Events are in write buffer, not yet readable
assert_eq!(queue.read_len(), 0);

queue.swap_buffers();

// Now they're in the read buffer
assert_eq!(queue.read_len(), 2);

pub fn read_buffer(&self) -> &Vec<E>

Returns a reference to the read buffer.

This is exposed for use by crate::core::event::EventReader to access events without draining.

Trait Implementations

impl<E: Event> Default for EventQueue<E>

fn default() -> Self

Returns the “default value” for a type.