Struct FabricQueue 

pub struct FabricQueue<T> { /* private fields */ }

A bounded SPSC ring buffer stored in leased fabric memory.

The queue owns its MemLease and releases it on drop. Elements are stored in FIFO order: push() appends to the tail, pop() reads from the head.

Non-blocking semantics

• push() returns Ok(false) when the queue is full.
• pop() returns Ok(None) when the queue is empty.

Neither operation blocks or retries.

Future direction: MPMC

This queue is currently single-producer single-consumer. A future MPMC variant would replace the plain head/tail fields with compare-and-swap (CAS) atomic operations on the remote memory, or alternatively use a lock-based protocol with a lease-scoped mutex in the header region. MPMC support is not yet implemented.

Example

use grafos_collections::queue::FabricQueue;

let mut q: FabricQueue<u32> = FabricQueue::with_capacity(8, 16)?;
q.push(&10)?;
q.push(&20)?;
assert_eq!(q.pop()?, Some(10));
assert_eq!(q.pop()?, Some(20));
assert_eq!(q.pop()?, None);

Implementations

impl<T: Serialize + DeserializeOwned> FabricQueue<T>

pub fn new(lease: MemLease, capacity: usize, stride: usize) -> Result<Self>

Create a new queue over the given lease.

capacity is the total number of slots. stride is the slot width in bytes (must accommodate 4-byte length prefix plus serialized element). One slot is reserved for the empty/full distinction, so the usable capacity is capacity - 1.

Errors

Returns FabricError::CapacityExceeded if the arena is too small to hold the header (32 bytes) plus capacity * stride bytes.

pub fn with_capacity(capacity: usize, stride: usize) -> Result<Self>

Create a new queue by acquiring a lease sized for capacity elements of stride bytes each.

Convenience constructor that acquires a lease via MemBuilder and then calls FabricQueue::new.

Errors

Returns FabricError::CapacityExceeded if the host cannot provide a large enough arena.

pub fn push(&mut self, item: &T) -> Result<bool>

Push an element onto the back of the queue.

Returns Ok(true) if the element was enqueued, Ok(false) if the queue is full. Does not block.

Errors

• FabricError::CapacityExceeded if the serialized element (plus 4-byte length prefix) exceeds stride.
• FabricError::IoError if serialization or remote write fails.

pub fn pop(&mut self) -> Result<Option<T>>

Pop an element from the front of the queue.

Returns Ok(Some(item)) if an element was dequeued, Ok(None) if the queue is empty. Does not block.

Errors

Returns FabricError::IoError if the remote read or deserialization fails.

pub fn len(&self) -> usize

Returns the number of elements currently in the queue.

pub fn is_empty(&self) -> bool

Returns true if the queue contains no elements.

pub fn is_full(&self) -> bool

Returns true if the queue is full.

pub fn lease_id(&self) -> u128

Returns the lease ID of the memory lease for external renewal management (e.g. via [grafos_leasekit::RenewalManager]).

pub fn expires_at_unix_secs(&self) -> u64

Returns the expiry time (unix seconds) of the memory lease for external renewal management.

pub fn max_len(&self) -> usize

Returns the maximum number of elements the queue can hold.

This is capacity - 1 since one slot is reserved for the empty/full distinction.