Struct PriorityQueue 

pub struct PriorityQueue { /* private fields */ }

A priority queue for PromptRequest items that orders requests by Priority and, within the same tier, by arrival time (FIFO).

Capacity

PriorityQueue::new creates a queue with capacity 10 000. Use PriorityQueue::with_capacity for custom sizing. When the queue is full, PriorityQueue::push returns Err(QueueError::QueueFull).

Deadline enforcement

Use PriorityQueue::pop_with_deadline_check to automatically skip requests whose deadline has already passed. Each skipped request is counted in expired_total (accessible via QueueStats) and a tracing::warn! is emitted.

Thread safety

PriorityQueue is Clone + Send + Sync. All clones share the same underlying heap behind a Mutex.

Examples

use std::collections::HashMap;
use tokio_prompt_orchestrator::{PromptRequest, SessionId};
use tokio_prompt_orchestrator::enhanced::{PriorityQueue, Priority};

let queue = PriorityQueue::new();

let req = PromptRequest {
    session: SessionId::new("s1"),
    request_id: "r1".to_string(),
    input: "hello".to_string(),
    meta: HashMap::new(),
    deadline: None,
};

queue.push(Priority::High, req).await.unwrap();

if let Some((priority, request)) = queue.pop().await {
    println!("{priority:?}: {}", request.input);
}

Implementations

impl PriorityQueue

pub fn new() -> Self

Create a PriorityQueue with the default capacity of 10 000 entries.

See also PriorityQueue::with_capacity.

pub fn with_capacity(max_size: usize) -> Self

Create a PriorityQueue with a specific maximum capacity.

A capacity of 0 causes every push to return Err(QueueError::QueueFull) immediately.

pub async fn push( &self, priority: Priority, request: PromptRequest, ) -> Result<(), QueueError>

Push a request onto the queue with the given priority.

Arguments

• priority — Relative importance; see Priority.
• request — The PromptRequest to enqueue.

Errors

Returns Err(QueueError::QueueFull) if the queue has reached its capacity. The request is not enqueued in that case.

pub async fn pop(&self) -> Option<(Priority, PromptRequest)>

Remove and return the highest-priority request.

Among requests with equal priority the one inserted first is returned (FIFO within a tier).

Returns

Some((priority, request)) if the queue is non-empty, otherwise None.

pub async fn pop_with_deadline_check(&self) -> Option<(Priority, PromptRequest)>

Remove and return the highest-priority request whose deadline has not yet passed.

Requests are popped in priority order (highest first, then FIFO). Any request whose deadline is Some(t) and t < Instant::now() is silently discarded: the expired_total counter is incremented, a tracing::warn! is emitted, and the next candidate is checked.

Requests with deadline = None are never expired.

Returns

Some((priority, request)) for the first non-expired request found, or None if the queue is empty or all remaining requests have expired.

Panics

This function does not panic.

pub async fn len(&self) -> usize

Get current queue size

pub async fn is_empty(&self) -> bool

Check if queue is empty

pub async fn stats(&self) -> QueueStats

Get queue statistics by priority.

Reads from lock-free atomic counters — O(1), no mutex held.

pub async fn clear(&self)

Clear all requests

Trait Implementations

impl Clone for PriorityQueue

fn clone(&self) -> PriorityQueue

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for PriorityQueue

fn default() -> Self

Returns the “default value” for a type.