Struct PinnedRing 

pub struct PinnedRing<'a> { /* private fields */ }

Handle pinned to one shape of the parent AdaptiveRing. Hot-path ops bypass the adaptive dispatch and call the native backend directly. The pin holder periodically calls is_still_valid to check whether a morph has invalidated this pin; on false the caller releases and re-acquires via AdaptiveRing::pin_current_shape.

Implementations

impl<'a> PinnedRing<'a>

pub fn shape(&self) -> RingShape

Shape this pin was captured at.

pub fn recv_signal(&self, shape: RingShape) -> &AtomicU64

Monitor-wait HINT for the consumer side of shape: an atom whose Release-store accompanies (or is) the next publish a pop is waiting for. Arm crate::monitor_wait::monitor_wait_u64 on it instead of burning a raw spin loop - on Windows the scheduler deschedules and migrates pure spinners (measured 1.7-2.7 us one-way for a cross-process spin ping-pong that runs in ~100-300 ns under Linux/FreeBSD on comparable silicon), while a monitor-armed waiter wakes on the store itself.

Contract: this is a HINT, not a wake guarantee - on the multi-line shapes (MPSC/MPMC) it covers producer line 0 only, and on Vyukov it covers the slot at the CURRENT consumer position (recompute after each pop). Callers must keep their waits budget-bounded and re-poll, which monitor_wait_u64’s budget enforces.

pub fn is_still_valid(&self) -> bool

One Acquire load on the parent’s pin_generation. Returns true while the pin is current; false if a morph has happened and the caller should release + re-acquire.

pub fn spsc_try_push(&self, payload: &[u8]) -> Result<(), RingError>

Native SPSC push. Caller assumes single-producer ownership and ensures pin validity is checked at meaningful intervals.

pub fn spsc_try_pop(&self, out: &mut [u8]) -> Result<usize, RingError>

Native SPSC pop.

pub fn mpsc_try_push( &self, producer_id: usize, payload: &[u8], ) -> Result<(), RingError>

MPSC push to a specific producer ring (captured at pin time).

pub fn mpsc_try_pop(&self, out: &mut [u8]) -> Result<usize, RingError>

MPSC pop (round-robin across the producer rings captured at pin time; a grown producer set invalidates the pin).

pub fn mpmc_try_push( &self, producer_id: usize, payload: &[u8], ) -> Result<(), RingError>

MPMC push to a specific producer ring (captured at pin time).

pub fn mpmc_try_pop( &self, consumer_id: usize, out: &mut [u8], ) -> Result<usize, RingError>

MPMC pop for a specific consumer. Ownership is consulted live from the shared directory (correctness under consumer joins / leaves); the ring array is the pin-time capture.

pub fn vyukov_try_push(&self, payload: &[u8]) -> Result<(), RingError>

Vyukov MPMC push.

pub fn vyukov_try_pop(&self, out: &mut [u8]) -> Result<usize, RingError>

Vyukov MPMC pop.

pub fn stamped_try_push( &self, producer_id: usize, payload: &[u8], ) -> Result<(), RingError>

Stamped push through the pinned shape: the producer’s next stamp is prepended and the payload cap is STAMPED_PAYLOAD_BYTES. Requires a ring constructed with AdaptiveRing::with_ordering_stamps; returns RingError::NotStamped otherwise.

pub fn ordered_try_pop( &self, consumer_id: usize, out: &mut [u8], ) -> Result<usize, RingError>

Ordering-aware pop through the pinned shape. The pin stays valid across ordering-mode flips - this call reads the MMF-resident mode atom every time (one Acquire load, a plain MOV on x86 TSO) and dispatches accordingly: partition pop + inversion counter under Unordered, k-way min-stamp merge under MergeByStamp / MergeStrict. Returns payload bytes only (Ok(56)).

pub fn ordered_try_pop_with_stamp( &self, consumer_id: usize, out: &mut [u8], ) -> Result<(usize, u64), RingError>

As ordered_try_pop, also returning the popped stamp so hot-loop consumers can assert the ordering guarantee they paid for.