Struct PartitionedQueue 

pub struct PartitionedQueue { /* private fields */ }

A partitioned queue for reduced contention with multiple producers.

Instead of a single queue with a lock, this uses multiple independent partitions (SPSC queues) to reduce contention when many producers are sending messages concurrently.

Producers are routed to partitions based on their source ID, ensuring messages from the same source go to the same partition (preserving order).

Example

use ringkernel_core::queue::{PartitionedQueue, QueueTier};

// Create 4 partitions with Medium tier capacity each
let queue = PartitionedQueue::new(4, QueueTier::Medium.capacity());

// Enqueue with source-based routing
queue.try_enqueue_from(source_id, envelope)?;

// Dequeue from any partition that has messages
if let Some(envelope) = queue.try_dequeue_any() {
    // process message
}

Implementations

impl PartitionedQueue

pub fn new(partition_count: usize, capacity_per_partition: usize) -> Self

Creates a new partitioned queue.

Arguments

• partition_count - Number of partitions (should be power of 2 for efficiency)
• capacity_per_partition - Capacity of each partition

pub fn with_defaults() -> Self

Creates a partitioned queue with default settings.

Uses 4 partitions with Medium tier capacity.

pub fn for_high_contention() -> Self

Creates a partitioned queue sized for high contention.

Uses 8 partitions with Large tier capacity.

pub fn partition_for(&self, source_id: u64) -> usize

Returns the partition index for a given source ID.

pub fn partition_count(&self) -> usize

Returns the number of partitions.

pub fn capacity_per_partition(&self) -> usize

Returns the capacity per partition.

pub fn total_capacity(&self) -> usize

Total capacity across all partitions.

pub fn total_messages(&self) -> usize

Total messages across all partitions.

pub fn try_enqueue_from( &self, source_id: u64, envelope: MessageEnvelope, ) -> Result<()>

Enqueues a message to a partition based on source ID.

Messages from the same source always go to the same partition, preserving ordering for that source.

pub fn try_enqueue(&self, envelope: MessageEnvelope) -> Result<()>

Enqueues a message using the envelope’s source kernel ID.

pub fn try_dequeue_partition(&self, partition: usize) -> Result<MessageEnvelope>

Tries to dequeue from a specific partition.

pub fn try_dequeue_any(&self) -> Option<MessageEnvelope>

Tries to dequeue from any partition that has messages.

Uses round-robin to fairly distribute dequeues across partitions.

pub fn partition_stats(&self, partition: usize) -> Option<QueueStats>

Returns statistics for a specific partition.

pub fn stats(&self) -> PartitionedQueueStats

Returns aggregated statistics across all partitions.

pub fn reset_stats(&self)

Resets statistics for all partitions.