Struct LockFreeEventQueue 

pub struct LockFreeEventQueue { /* private fields */ }

Lock-free bounded event queue for high-throughput ingestion

Design Pattern

Uses crossbeam’s lock-free MPMC (Multi-Producer, Multi-Consumer) queue to eliminate contention in the hot path of event ingestion.

Benefits

• Zero Lock Contention: Multiple threads can push/pop concurrently
• Predictable Latency: No waiting for locks
• High Throughput: Optimized for concurrent access
• Backpressure Handling: Returns error when full

Performance

• Push: ~10-20ns (lock-free)
• Pop: ~10-20ns (lock-free)
• vs RwLock: 100-500ns (with contention)

Example

let queue = LockFreeEventQueue::new(10000);

// Multiple producers can push concurrently
let event = Event::from_strings(...)?;
queue.try_push(event)?;

// Multiple consumers can pop concurrently
if let Some(event) = queue.try_pop() {
    // Process event
}

Implementations

impl LockFreeEventQueue

pub fn new(capacity: usize) -> Self

Create new lock-free event queue with fixed capacity

Arguments

• capacity: Maximum number of events the queue can hold

Capacity Guidelines

• Small: 1,000-10,000 events (low memory, fast overflow)
• Medium: 10,000-100,000 events (balanced)
• Large: 100,000-1,000,000 events (high memory, slow overflow)

pub fn try_push(&self, event: Event) -> Result<()>

Try to push an event to the queue (non-blocking)

Returns an error if the queue is full. Callers should implement backpressure handling (e.g., retry with exponential backoff, or return HTTP 503 Service Unavailable).

Performance

• Lock-free operation (~10-20ns)
• No waiting on contention
• Constant time O(1)

pub fn try_pop(&self) -> Option<Event>

Try to pop an event from the queue (non-blocking)

Returns None if the queue is empty.

Performance

• Lock-free operation (~10-20ns)
• No waiting on contention
• Constant time O(1)

pub fn len(&self) -> usize

Get current queue length

Note: This is approximate in concurrent scenarios due to race conditions between length check and actual push/pop operations.

pub fn is_empty(&self) -> bool

Check if queue is empty

Note: Result may be stale in concurrent scenarios.

pub fn is_full(&self) -> bool

Check if queue is full

Note: Result may be stale in concurrent scenarios.

pub fn capacity(&self) -> usize

Get queue capacity

pub fn fill_ratio(&self) -> f64

Get approximate fill percentage (0.0 to 1.0)

Trait Implementations

impl Clone for LockFreeEventQueue

fn clone(&self) -> LockFreeEventQueue

Returns a duplicate of the value.

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

Performs copy-assignment from source.