Crate ruvix_queue 

io_uring-style Ring Buffer IPC for RuVix Cognition Kernel.

This crate implements the Queue primitive from ADR-087 Section 7. All inter-task communication in RuVix goes through queues. There are no synchronous IPC calls, no shared memory without explicit region grants, and no signals.

Architecture

Queues use io_uring-style ring buffers with separate submission (SQ) and completion (CQ) queues. This enables:

• Lock-free operation: Using atomic head/tail pointers
• Zero-copy semantics: When sender and receiver share a region
• Typed messages: WIT schema validation at send time
• Priority support: Higher priority messages are delivered first

Zero-Copy Semantics

When sender and receiver share a region, queue_send places a descriptor (offset + length) in the ring rather than copying bytes. This is critical for high-throughput vector streaming where copying 768-dimensional f32 vectors would be prohibitive.

TOCTOU Protection: Only Immutable or AppendOnly regions can use descriptors (ADR-087 Section 20.5). The kernel rejects descriptors pointing into Slab regions to prevent time-of-check-to-time-of-use attacks.

Example

use ruvix_queue::{KernelQueue, QueueConfig};
use ruvix_types::MsgPriority;

// Create a queue
let config = QueueConfig::new(64, 4096); // 64 entries, 4KB max message
let mut queue = KernelQueue::new(config, region_handle)?;

// Send a message
queue.send(b"hello", MsgPriority::Normal)?;

// Receive with timeout
let mut buf = [0u8; 4096];
let len = queue.recv(&mut buf, Duration::from_millis(100))?;

Structs

DescriptorValidator

Validator for message descriptors.

KernelQueue

A kernel queue for inter-task communication.

MessageDescriptor

A zero-copy message descriptor.

OptimizedRingBuffer

Optimized lock-free ring buffer with power-of-2 size.

OptimizedRingEntry

Optimized ring entry header (8 bytes).

OptimizedRingSlot

Cache-line aligned ring slot.

QueueConfig

Configuration for a kernel queue.

RingBuffer

A lock-free ring buffer for message passing.

RingEntry

A lock-free ring buffer entry.

RingStats

Statistics for ring buffer operations.

Type Aliases

Duration

Duration type for timeouts (re-export for convenience).

Result

Result type for queue operations.