Struct QueueIndex 

pub struct QueueIndex<V: Clone + Send + Sync> { /* private fields */ }

A queue-optimized ordered index

This provides efficient priority queue operations by:

1. Maintaining a BTreeMap for O(log N) min-key access
2. Caching the minimum key for O(1) peek
3. Tracking size for O(1) count

Internal Structure

┌─────────────────────────────────────────────────────────────────────┐
│                         QueueIndex                                   │
├─────────────────────────────────────────────────────────────────────┤
│ entries: BTreeMap<CompositeKey, Value>  ← O(log N) ordered ops      │
│ min_key_cache: Option<CompositeKey>     ← O(1) peek                 │
│ size: AtomicUsize                       ← O(1) count                │
│ version: AtomicU64                      ← For cache invalidation    │
└─────────────────────────────────────────────────────────────────────┘

Implementations

impl<V: Clone + Send + Sync> QueueIndex<V>

pub fn new(config: QueueIndexConfig) -> Self

Create a new queue index

pub fn insert(&self, key: CompositeQueueKey, value: V)

Insert a task into the queue

Complexity: O(log N)

pub fn peek_min(&self) -> Option<(CompositeQueueKey, V)>

Peek at the minimum key without removing it

Complexity: O(1) if cache hit, O(log N) if cache miss

pub fn pop_min(&self) -> Option<(CompositeQueueKey, V)>

Remove and return the minimum entry

Complexity: O(log N)

pub fn remove(&self, key: &CompositeQueueKey) -> Option<V>

Remove a specific entry by key

Complexity: O(log N)

pub fn get(&self, key: &CompositeQueueKey) -> Option<V>

Get an entry by key

Complexity: O(log N)

pub fn contains(&self, key: &CompositeQueueKey) -> bool

Check if a key exists

Complexity: O(log N)

pub fn len(&self) -> usize

Get queue size

Complexity: O(1)

pub fn is_empty(&self) -> bool

Check if queue is empty

Complexity: O(1)

pub fn version(&self) -> u64

Get current version (for change detection)

pub fn scan_by_priority( &self, max_priority: i64, limit: usize, ) -> Vec<(CompositeQueueKey, V)>

Scan entries with priority <= threshold

Useful for batch processing of high-priority tasks.

Complexity: O(log N + K) where K is result count

pub fn scan_ready(&self, now: u64, limit: usize) -> Vec<(CompositeQueueKey, V)>

Scan entries ready at or before the given timestamp

Complexity: O(N) in worst case, but typically O(K) if data is time-ordered

pub fn config(&self) -> &QueueIndexConfig

Get the configuration