pub struct OrderingRegion { /* private fields */ }Expand description
The mapped ordering region: header + producer lines, in any of the three locales.
Implementations§
Source§impl OrderingRegion
impl OrderingRegion
Sourcepub fn create_anon(
max_producers: usize,
kind: StampKind,
) -> Result<Self, RingError>
pub fn create_anon( max_producers: usize, kind: StampKind, ) -> Result<Self, RingError>
Anonymous in-process region, initialised.
Sourcepub fn create(
path: impl AsRef<Path>,
max_producers: usize,
kind: StampKind,
) -> Result<Self, RingError>
pub fn create( path: impl AsRef<Path>, max_producers: usize, kind: StampKind, ) -> Result<Self, RingError>
File-backed region at path, initialised.
Sourcepub fn open(
path: impl AsRef<Path>,
max_producers: usize,
) -> Result<Self, RingError>
pub fn open( path: impl AsRef<Path>, max_producers: usize, ) -> Result<Self, RingError>
Open an existing file-backed region. Validates the magic and adopts the creator’s stamp kind; does NOT re-initialise, so the live mode flag, counters, and watermarks survive the attach.
Sourcepub fn create_shm(
shm: ShmFile,
max_producers: usize,
kind: StampKind,
) -> Result<Self, RingError>
pub fn create_shm( shm: ShmFile, max_producers: usize, kind: StampKind, ) -> Result<Self, RingError>
Named-shm region, initialised. Mirrors the ring backings’
create_from_shm semantics (the creator initialises).
Sourcepub fn stamp_kind(&self) -> StampKind
pub fn stamp_kind(&self) -> StampKind
Stamp kind this region was created with.
Sourcepub fn max_producers(&self) -> usize
pub fn max_producers(&self) -> usize
Number of producer lines.
Sourcepub fn lease_generation(&self) -> u64
pub fn lease_generation(&self) -> u64
The drainer-lease generation: bumped on every lease claim / takeover / release and on every epoch tick, and NEVER written otherwise. A merge drainer verifies its lease per pop with one load of this quiet line (compared against a consumer-local cache) and runs the full lease handshake only on change - the per-pop path never touches the stamp-hot first header line.
Sourcepub fn mode(&self) -> OrderingMode
pub fn mode(&self) -> OrderingMode
Current ordering mode. One Acquire load.
Sourcepub fn set_mode(&self, mode: OrderingMode)
pub fn set_mode(&self, mode: OrderingMode)
Flip the ordering mode. Off->On is immediate and retroactive: the in-flight backlog merges in stamp order because the stamps were already in the slots. On->Off is immediate. No drain, no data movement.
Sourcepub fn inversions(&self) -> u64
pub fn inversions(&self) -> u64
Cross-producer inversions observed since creation.
Sourcepub fn refresh_watermark(&self, producer_id: usize)
pub fn refresh_watermark(&self, producer_id: usize)
Watermark heartbeat for an idle producer: advances the watermark to a fresh stamp WITHOUT pushing, so MergeStrict consumers stop waiting on this producer’s silence. Only call from the producer’s own thread between pushes (never while a stamped item is awaiting publish - the refresh would claim “nothing below this stamp is in flight” while one is).
Sourcepub fn issued(&self, producer_id: usize) -> u64
pub fn issued(&self, producer_id: usize) -> u64
Read producer producer_id’s last issued stamp (or
reservation floor while a stamp is being issued).
Sourcepub fn retire_producer(&self, producer_id: usize)
pub fn retire_producer(&self, producer_id: usize)
Terminal producer retirement: publishes u64::MAX as the
slot’s issued stamp + watermark, declaring “this producer
will never stamp again”. MergeStrict consumers stop waiting
on the slot’s silence permanently (any candidate passes its
watermark gate) and the in-flight gate reads it as clean.
A producer MUST NOT push after retiring its slot - the
monotonicity floor is saturated.
Sourcepub fn seed_from(&self, other: &OrderingRegion)
pub fn seed_from(&self, other: &OrderingRegion)
Seed this region’s stamp state from another region so stamps stay monotone across a backing swap (capacity morphs allocate a fresh region; counter stamps would otherwise restart at 1).
Sourcepub fn try_acquire_drainer(&self, token: u64, grace_epochs: u64) -> bool
pub fn try_acquire_drainer(&self, token: u64, grace_epochs: u64) -> bool
Try to become (or confirm being) the active merge drainer.
Token layout: (pid << 32) | consumer_id, never 0.
Succeeds when (a) unleased, (b) the caller already holds the
lease (heartbeat refreshed), or (c) the current holder’s
heartbeat is more than grace_epochs behind the global
epoch (dead-drainer takeover).
Sourcepub fn release_drainer(&self, token: u64) -> bool
pub fn release_drainer(&self, token: u64) -> bool
Voluntarily release the drainer lease. Returns false when
the caller did not hold it.
Sourcepub fn current_drainer(&self) -> u64
pub fn current_drainer(&self) -> u64
Current drainer token (0 = unleased).
Sourcepub fn drainer_beat(&self, token: u64) -> bool
pub fn drainer_beat(&self, token: u64) -> bool
Refresh the drainer heartbeat. Returns false when the
caller no longer holds the lease.
Sourcepub fn tick_drainer_epoch(&self) -> u64
pub fn tick_drainer_epoch(&self) -> u64
Advance the global drainer epoch (caller-driven, typically
the sidecar’s scan tick). A holder whose heartbeat falls more
than grace_epochs behind becomes preemptible. Also bumps the
lease generation so the holder’s next pop re-runs the full
handshake and refreshes its heartbeat (the liveness proof).