Struct KernelQueue 

pub struct KernelQueue { /* private fields */ }

A kernel queue for inter-task communication.

Implements io_uring-style ring buffer IPC as specified in ADR-087 Section 7. Features:

• Lock-free send/recv using atomic head/tail pointers
• Zero-copy descriptor-based messaging for shared regions
• Priority support (messages can have Low, Normal, High, Urgent priority)
• Optional WIT schema validation

Thread Safety

KernelQueue is Send and Sync. Multiple tasks can send to the same queue concurrently. Receives are typically done by a single consumer task.

Implementations

impl KernelQueue

pub fn new( config: QueueConfig, region: RegionHandle, buffer: *mut u8, buffer_len: usize, ) -> Result<Self>

Create a new kernel queue.

Arguments

• config - Queue configuration
• region - Handle to the backing region
• buffer - Pointer to the backing memory
• buffer_len - Length of the backing memory

Errors

Returns InvalidParameter if the configuration is invalid. Returns OutOfMemory if the buffer is too small.

pub fn new_heap(config: QueueConfig) -> Result<(Self, Vec<u8>)>

Create a queue with heap-allocated backing memory.

This is a convenience method for testing and std environments.

pub fn send(&mut self, msg: &[u8], priority: MsgPriority) -> Result<()>

Send a message to the queue.

Arguments

• msg - Message payload bytes
• priority - Message priority

Errors

Returns QueueFull if the queue is full. Returns MessageTooLarge if the message exceeds max_msg_size.

pub fn send_descriptor( &mut self, descriptor: &MessageDescriptor, region_policy: &RegionPolicy, region_size: usize, priority: MsgPriority, ) -> Result<()>

Send a zero-copy message via descriptor.

Instead of copying data, this sends a reference to data in a shared region. The receiver must read the data from the shared region using the descriptor.

Arguments

• descriptor - Reference to data in a shared region
• region_policy - Policy of the region referenced by the descriptor
• region_size - Size of the region
• priority - Message priority

Errors

Returns QueueFull if the queue is full. Returns InvalidDescriptorRegion if the region policy doesn’t allow descriptors. Returns InvalidParameter if the descriptor references out-of-bounds memory.

TOCTOU Protection

Only Immutable or AppendOnly regions are allowed. This prevents the sender from modifying the data after sending but before the receiver processes it.

pub fn recv(&mut self, buf: &mut [u8]) -> Result<usize>

Receive a message from the queue (non-blocking).

Arguments

• buf - Buffer to receive the message data

Returns

On success, returns the number of bytes received. For descriptor messages, the descriptor is written to buf and you should use MessageDescriptor::from_bytes to parse it.

Errors

Returns QueueEmpty if no messages are available.

pub fn recv_timeout( &mut self, buf: &mut [u8], timeout: Duration, ) -> Result<usize>

Receive a message from the queue with timeout.

Arguments

• buf - Buffer to receive the message data
• timeout - Maximum time to wait for a message

Returns

On success, returns the number of bytes received.

Errors

Returns Timeout if no message arrived within the timeout period.

pub fn recv_typed(&mut self, buf: &mut [u8]) -> Result<ReceivedMessage>

Receive a message, distinguishing between inline data and descriptors.

Returns

Returns ReceivedMessage which indicates whether the data is inline or a descriptor reference.

pub fn peek(&self) -> Option<RingEntry>

Peek at the next message without removing it.

pub fn is_empty(&self) -> bool

Check if the queue is empty.

pub fn is_full(&self) -> bool

Check if the queue is full.

pub fn len(&self) -> u32

Get the number of messages currently in the queue.

pub fn available(&self) -> u32

Get the number of available slots.

pub fn config(&self) -> &QueueConfig

Get the queue configuration.

pub fn region(&self) -> RegionHandle

Get the backing region handle.

pub fn send_count(&self) -> u32

Get the total number of send operations.

pub fn recv_count(&self) -> u32

Get the total number of recv operations.