Struct ResidentWorkQueue 

pub struct ResidentWorkQueue;

Stateless owner of resident work-queue encoding and decoding operations.

Implementations

impl ResidentWorkQueue

pub fn transition_slot_status( ring_bytes: &mut [u8], slot_idx: u32, transition: RingSlotTransition, ) -> Result<u32, PipelineError>

Apply one explicit lifecycle transition to a ring slot status word.

This helper is for host-side tests, recovery, cancellation, and diagnostics. Normal publication should still use Self::publish_slot or batch publishers so payload words are written before the PUBLISHED status barrier.

Errors

Returns PipelineError::QueueFull when the slot is out of bounds, the ring is malformed, or the requested transition is illegal for the current status word.

pub fn publish_slot( ring_bytes: &mut [u8], slot_idx: u32, tenant_id: u32, opcode: u32, args: &[u32], ) -> Result<(), PipelineError>

Publish one opcode into ring_bytes[slot_idx].

Errors

PipelineError::QueueFull when out of bounds, too many args, or the slot is still in flight.

pub fn encode_work_items_ring_into( slot_count: u32, tenant_id: u32, items: &[ResidentWorkItem], ring_bytes: &mut Vec<u8>, ) -> Result<(), PipelineError>

Reset ring_bytes to an empty ring and publish a contiguous ResidentWorkItem queue into slots 0..items.len().

This is the hot-path publisher for one-shot megakernel launches. It validates the full batch before mutating ring_bytes, encodes an empty ring once, writes the fixed ResidentWorkItem ABI directly, and stores slot::PUBLISHED last for each slot.

Errors

Returns PipelineError::QueueFull when slot_count cannot encode, the queue does not fit in the ring, the slot ABI cannot hold a ResidentWorkItem, or an item opcode is not publishable.

pub fn publish_work_items( ring_bytes: &mut [u8], start_slot: u32, tenant_id: u32, items: &[ResidentWorkItem], ) -> Result<u32, PipelineError>

Publish a contiguous fixed-ABI work-item window into an existing ring without resetting unrelated slots.

This is the resident hot path for repeated megakernel queue updates: validate the whole target window first, then write each slot once and store slot::PUBLISHED last. Unlike Self::encode_work_items_ring_into, this does not clear the full ring, so sparse updates scale with items.len() rather than slot_count.

Errors

Returns PipelineError::QueueFull when the target window is outside the ring, any slot is still in flight, or an item opcode is not publishable.

pub fn encode_work_items_ring_words_into( slot_count: u32, tenant_id: u32, items: &[ResidentWorkItem], ring_words: &mut Vec<u32>, ) -> Result<(), PipelineError>

Reset ring_words to an empty ring and publish a contiguous ResidentWorkItem queue as native little-endian u32 words.

This is equivalent to Self::encode_work_items_ring_into but avoids thousands of tiny byte-slice stores on hot dispatch paths. Callers can pass the result to backends as bytes with bytemuck::cast_slice.

Errors

Returns PipelineError::QueueFull when slot_count cannot encode, the queue does not fit in the ring, the slot ABI cannot hold a ResidentWorkItem, or an item opcode is not publishable.

pub fn publish_packed_slot<A>( ring_bytes: &mut [u8], slot_idx: u32, tenant_id: u32, ops: &[(u8, A)], ) -> Result<(), PipelineError>

where A: AsRef<[u32]>,

Publish one packed slot containing multiple inner ops.

The inner opcode id is stored as u8; args are packed into the slot’s 12-word payload tail and addressed by per-op arg_offset values.

Errors

Returns PipelineError::QueueFull when the packed payload exceeds the slot capacity or when the target slot is not publishable.

pub fn batch_publish<A>( ring_bytes: &mut [u8], start_slot: u32, tenant_id: u32, items: &[(u32, A)], batch_tag: u32, ) -> Result<u32, PipelineError>

where A: AsRef<[u32]>,

Publish multiple slots atomically - the final slot is a BATCH_FENCE that signals completion to the host. This is the high-throughput entry point for scanner pipelines: publish N work items + 1 fence in one call.

Errors

PipelineError::QueueFull if any slot rejects.

impl ResidentWorkQueue

pub fn control_byte_len(observable_slots: u32) -> Option<usize>

Byte length of a control buffer for observable_slots.

pub fn ring_byte_len(slot_count: u32) -> Option<usize>

Byte length of a ring buffer for slot_count.

pub fn debug_log_byte_len(record_capacity: u32) -> Option<usize>

Byte length of a debug-log buffer for record_capacity.

pub fn debug_record_capacity() -> u32

Default debug-log record capacity owned by the runtime protocol.

pub fn encode_control( shutdown: bool, tenant_count: u32, observable_slots: u32, ) -> Result<Vec<u8>, PipelineError>

Encode a control-buffer payload.

Errors

Returns PipelineError::QueueFull when the requested observable region cannot fit in process address space.

pub fn try_encode_control( shutdown: bool, tenant_count: u32, observable_slots: u32, ) -> Result<Vec<u8>, PipelineError>

Fallible control-buffer encoder for callers accepting untrusted sizing.

Errors

Returns PipelineError::QueueFull when the requested observable region cannot fit in process address space.

pub fn try_encode_control_into( shutdown: bool, tenant_count: u32, observable_slots: u32, dst: &mut Vec<u8>, ) -> Result<(), PipelineError>

Fallible control-buffer encoder into caller-owned storage.

Errors

Returns PipelineError::QueueFull when the requested observable region cannot fit in process address space.

pub fn encode_empty_ring(slot_count: u32) -> Result<Vec<u8>, PipelineError>

Encode an empty ring buffer with slot_count slots.

Errors

Returns PipelineError::QueueFull when slot_count * SLOT_WORDS * 4 overflows.

pub fn try_encode_empty_ring(slot_count: u32) -> Result<Vec<u8>, PipelineError>

Fallible ring-buffer encoder for callers accepting untrusted slot counts.

Errors

Returns PipelineError::QueueFull when slot_count * SLOT_WORDS * 4 overflows.

pub fn try_encode_empty_ring_into( slot_count: u32, dst: &mut Vec<u8>, ) -> Result<(), PipelineError>

Fallible ring-buffer encoder into caller-owned storage.

Errors

Returns PipelineError::QueueFull when the requested capacity cannot fit in process address space.

pub fn encode_empty_debug_log( record_capacity: u32, ) -> Result<Vec<u8>, PipelineError>

Encode an empty PRINTF channel buffer.

Errors

Returns PipelineError::QueueFull when the record capacity overflows.

pub fn try_encode_empty_debug_log( record_capacity: u32, ) -> Result<Vec<u8>, PipelineError>

Fallible debug-log encoder for callers accepting untrusted capacities.

Errors

Returns PipelineError::QueueFull when the record capacity overflows.

pub fn try_encode_empty_debug_log_into( record_capacity: u32, dst: &mut Vec<u8>, ) -> Result<(), PipelineError>

Fallible debug-log encoder into caller-owned storage.

Errors

Returns PipelineError::QueueFull when the requested capacity cannot fit in process address space.

pub fn read_done_count(control_bytes: &[u8]) -> u32

Decode the kernel’s done_count from a control buffer.

pub fn try_read_done_count(control_bytes: &[u8]) -> Result<u32, PipelineError>

Strictly decode the kernel’s done_count from a control buffer.

Errors

Returns PipelineError when the control buffer is malformed or too short to contain the done counter.

pub fn try_read_epoch(control_bytes: &[u8]) -> Result<u32, PipelineError>

Strictly read the epoch counter from a control buffer.

Errors

Returns PipelineError when the control buffer is malformed or too short to contain the epoch counter.

pub fn try_count_done_ring_slots( ring_bytes: &[u8], item_count: usize, ) -> Result<u64, PipelineError>

Strictly count DONE slots in a ring-buffer readback.

Errors

Returns PipelineError when the ring readback is malformed or too short for item_count complete protocol slots.

pub fn read_debug_log(debug_bytes: &[u8]) -> Vec<DebugRecord>

Decode PRINTF records out of the debug-log buffer.

pub fn read_debug_log_into(debug_bytes: &[u8], out: &mut Vec<DebugRecord>)

Decode PRINTF records into caller-owned storage.

pub fn try_read_debug_log( debug_bytes: &[u8], ) -> Result<Vec<DebugRecord>, PipelineError>

Strictly decode PRINTF records out of the debug-log buffer.

Errors

Returns PipelineError when the debug-log buffer is malformed or the cursor points at a partial record.

pub fn try_read_debug_log_into( debug_bytes: &[u8], out: &mut Vec<DebugRecord>, ) -> Result<(), PipelineError>

Strictly decode PRINTF records into caller-owned storage.

Errors

Returns PipelineError when the debug-log buffer is malformed or the cursor points at a partial record.

pub fn read_epoch(control_bytes: &[u8]) -> u32

Read the epoch counter from a control buffer. The epoch increments on each BATCH_FENCE execution - the host polls this to detect batch completion without scanning the ring.

pub fn read_observable(control_bytes: &[u8], index: u32) -> u32

Read an observable result word from a control buffer. Opcodes like LOAD_U32, COMPARE_SWAP, and BATCH_FENCE write results here.

pub fn try_read_observable( control_bytes: &[u8], index: u32, ) -> Result<u32, PipelineError>

Strictly read an observable result word from a control buffer.

Errors

Returns PipelineError when the buffer is malformed or the observable index is outside the supplied readback.

pub fn read_metrics(control_bytes: &[u8]) -> Vec<(u32, u32)>

Read per-opcode metrics counters from a control buffer. Returns a map of opcode_id → execution_count for any non-zero counters.

pub fn read_metrics_into(control_bytes: &[u8], out: &mut Vec<(u32, u32)>)

Read per-opcode metrics counters into caller-owned storage.

pub fn try_read_metrics( control_bytes: &[u8], ) -> Result<Vec<(u32, u32)>, PipelineError>

Strictly read per-opcode metrics counters from a control buffer.

Errors

Returns PipelineError when the buffer is malformed or too short for the fixed metrics window.

pub fn try_read_metrics_into( control_bytes: &[u8], out: &mut Vec<(u32, u32)>, ) -> Result<(), PipelineError>

Strictly read per-opcode metrics counters into caller-owned storage.

Errors

Returns PipelineError when the buffer is malformed or too short for the fixed metrics window.

Trait Implementations

impl Clone for ResidentWorkQueue

fn clone(&self) -> ResidentWorkQueue

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for ResidentWorkQueue

impl Debug for ResidentWorkQueue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ResidentWorkQueue

fn default() -> ResidentWorkQueue

Returns the “default value” for a type.