Struct PriorityEventQueue 

pub struct PriorityEventQueue<M: Message> { /* private fields */ }

A priority queue for events with automatic backpressure handling

This queue ensures that high priority events (like user input and quit commands) are processed before lower priority events (like ticks and resize events). It implements backpressure to prevent memory exhaustion under high load.

When the queue reaches 80% capacity, backpressure is activated. If the queue fills completely, lower priority events are dropped in favor of higher priority ones.

Example

let mut queue = PriorityEventQueue::new(1000);

queue.push(Event::Tick)?;       // Low priority
queue.push(Event::Quit)?;       // High priority

// High priority events are processed first
assert_eq!(queue.pop(), Some(Event::Quit));
assert_eq!(queue.pop(), Some(Event::Tick));

Implementations

impl<M: Message> PriorityEventQueue<M>

pub fn new(max_size: usize) -> Self

Create a new priority event queue with the specified maximum size

Arguments

• max_size - Maximum number of events the queue can hold

Example

use hojicha_runtime::priority_queue::PriorityEventQueue;

#[derive(Debug, Clone, PartialEq)]
struct TestMsg;

let queue: PriorityEventQueue<TestMsg> = PriorityEventQueue::new(1000);
assert_eq!(queue.len(), 0);
assert_eq!(queue.capacity(), 1000);

pub fn push(&mut self, event: Event<M>) -> Result<(), Event<M>>

Push an event into the priority queue

Events are automatically prioritized based on their type. If the queue is full, lower priority events may be dropped to make room for higher priority ones.

Arguments

• event - The event to add to the queue

Returns

• Ok(()) if the event was successfully added
• Err(event) if the event was dropped due to queue overflow

Example

use hojicha_runtime::priority_queue::PriorityEventQueue;
use hojicha_core::event::Event;

#[derive(Debug, Clone, PartialEq)]
struct TestMsg;

let mut queue: PriorityEventQueue<TestMsg> = PriorityEventQueue::new(1000);
let result = queue.push(Event::Tick);
assert!(result.is_ok());
assert_eq!(queue.len(), 1);

pub fn pop(&mut self) -> Option<Event<M>>

Remove and return the highest priority event from the queue

Events are returned in priority order, with high priority events returned before normal and low priority events.

Returns

• Some(event) if there are events in the queue
• None if the queue is empty

Example

use hojicha_runtime::priority_queue::PriorityEventQueue;
use hojicha_core::event::Event;

#[derive(Debug, Clone, PartialEq)]
struct TestMsg;

let mut queue: PriorityEventQueue<TestMsg> = PriorityEventQueue::new(1000);
queue.push(Event::Tick).unwrap();
queue.push(Event::Quit).unwrap(); // Higher priority

// High priority event comes first
assert_eq!(queue.pop(), Some(Event::Quit));
assert_eq!(queue.pop(), Some(Event::Tick));
assert_eq!(queue.pop(), None);

pub fn is_empty(&self) -> bool

Check if the queue is empty

Returns

• true if the queue contains no events
• false if the queue contains one or more events

pub fn len(&self) -> usize

Get the current number of events in the queue

Returns

The number of events currently in the queue

pub fn is_backpressure_active(&self) -> bool

Check if backpressure is currently active

Backpressure is activated when the queue reaches 80% of its capacity.

Returns

• true if backpressure is active
• false if the queue is below the backpressure threshold

pub fn dropped_events(&self) -> usize

Get the total number of events that have been dropped

Events are dropped when the queue is full and lower priority events are evicted to make room for higher priority ones.

Returns

The total number of events dropped since queue creation

pub fn clear(&mut self)

Clear all events from the queue

This removes all events and resets the backpressure state, but preserves the dropped event counter and capacity settings.

pub fn capacity(&self) -> usize

Get the current capacity of the queue

pub fn resize(&mut self, new_size: usize) -> Result<(), ResizeError>

Resize the queue to a new capacity

Arguments

• new_size - The new maximum size for the queue

Returns

• Ok(()) if resize succeeded
• Err(ResizeError) if the new size is invalid or would cause data loss

pub fn try_grow(&mut self, additional: usize) -> Result<usize, ResizeError>

Try to grow the queue by a specified amount

pub fn try_shrink(&mut self, reduction: usize) -> Result<usize, ResizeError>

Try to shrink the queue by a specified amount

pub fn stats(&self) -> QueueStats

Get current queue statistics for scaling decisions