sptos-queue

io_uring-style ring buffer IPC for SPTOS Cognition Kernel

Overview

sptos-queue implements the Queue primitive from ADR-087. All inter-task communication in SPTOS goes through queues -- there are no synchronous IPC calls, no shared memory without explicit region grants, and no signals. Queues use io_uring-style ring buffers with separate submission and completion queues.

Key Features

• Lock-free ring buffers — Atomic head/tail pointers for concurrent access without locks
• Zero-copy semantics — Descriptor-based transfer when sender and receiver share a region
• Priority messaging — Higher priority messages are delivered first
• TOCTOU protection — Only Immutable or AppendOnly regions can use zero-copy descriptors
• Optimized variant — OptimizedRingBuffer for performance-critical paths

Dependencies

Key internal dependencies:

• sptos-types — Queue types (QueueHandle, QueueConfig, MsgPriority)
• sptos-region — Memory region backing for queue storage

Usage

use sptos_queue::{KernelQueue, QueueConfig};
use sptos_types::MsgPriority;

let config = QueueConfig::new(64, 4096);
let mut queue = KernelQueue::new(config, region_handle)?;

queue.send(b"hello", MsgPriority::Normal)?;
let msg = queue.recv(&mut buf, timeout)?;

API Reference

Core Types

Type	Description
KernelQueue	Full-featured queue with send/recv and priority support
RingBuffer	Core lock-free ring buffer implementation
RingEntry	Single entry in a ring buffer slot
MessageDescriptor	Zero-copy descriptor referencing data in a shared region
PrioritizedDescriptor	Descriptor with attached priority for ordered delivery
DescriptorValidator	Validates descriptors against region policies
OptimizedRingBuffer	Performance-optimized ring buffer variant
ReceivedMessage	Message received from a queue with metadata