pub struct CapacityPubSubRing { /* private fields */ }Expand description
Runtime-resizable pubsub ring.
Implementations§
Source§impl CapacityPubSubRing
impl CapacityPubSubRing
Sourcepub fn create_anon(
initial_capacity: usize,
) -> Result<Arc<Self>, PubSubCapacityMorphError>
pub fn create_anon( initial_capacity: usize, ) -> Result<Arc<Self>, PubSubCapacityMorphError>
Anon (in-process) capacity-adaptive pubsub ring.
Sourcepub fn create(
base_path: impl AsRef<Path>,
initial_capacity: usize,
) -> Result<Arc<Self>, PubSubCapacityMorphError>
pub fn create( base_path: impl AsRef<Path>, initial_capacity: usize, ) -> Result<Arc<Self>, PubSubCapacityMorphError>
File-backed capacity-adaptive pubsub ring.
Sourcepub fn create_shmfs(
name_prefix: &str,
initial_capacity: usize,
) -> Result<Arc<Self>, PubSubCapacityMorphError>
pub fn create_shmfs( name_prefix: &str, initial_capacity: usize, ) -> Result<Arc<Self>, PubSubCapacityMorphError>
ShmFs (named shared memory) capacity-adaptive pubsub ring.
Sourcepub fn current_capacity(&self) -> usize
pub fn current_capacity(&self) -> usize
Current capacity of the active backing.
Sourcepub fn pin_generation(&self) -> u64
pub fn pin_generation(&self) -> u64
Current pin generation.
Sourcepub fn publish(&self, payload: &[u8]) -> u64
pub fn publish(&self, payload: &[u8]) -> u64
Publish a payload to the currently-active backing. Returns the absolute position assigned within that backing (not globally unique across backings - subscribers identify items via payload contents, not position).
The chain lock is held through the inner publish call so a concurrent morph cannot slip in and make this publish land in a backing that just became stale. Subscribers walk the chain oldest-to-newest and only advance forward; if a publish landed in a now-stale backing past where any subscriber had already advanced, those items would be silently lost. Holding the lock through publish prevents that.
Sourcepub fn subscribe_from_now(self: &Arc<Self>) -> CapacityPubSubSubscriber
pub fn subscribe_from_now(self: &Arc<Self>) -> CapacityPubSubSubscriber
Subscribe to the stream from the CURRENT active backing’s current head. The subscriber drains forward from there, crossing into newly-morphed backings as it catches up. “From now” semantics: late joiners do NOT see history from before they subscribed.
Sourcepub fn subscribe_from_oldest(self: &Arc<Self>) -> CapacityPubSubSubscriber
pub fn subscribe_from_oldest(self: &Arc<Self>) -> CapacityPubSubSubscriber
Subscribe starting from the beginning of the OLDEST backing currently in the chain. The subscriber drains every item from every backing oldest-to-newest, crossing chain entries as it catches up. Used when a subscriber needs to replay the full available history.
Sourcepub fn morph_capacity_to(
&self,
new_capacity: usize,
) -> Result<(), PubSubCapacityMorphError>
pub fn morph_capacity_to( &self, new_capacity: usize, ) -> Result<(), PubSubCapacityMorphError>
Morph the active backing’s capacity. Allocates a fresh
backing at new_capacity, appends it to the chain,
bumps pin_generation, and publishes the new active end.
Subscribers reading from older chain entries continue
undisturbed; they advance into the new backing
individually as their try_next catches up.
Sourcepub fn prewarm(&self, capacity: usize) -> Result<(), PubSubCapacityMorphError>
pub fn prewarm(&self, capacity: usize) -> Result<(), PubSubCapacityMorphError>
Speculatively build a backing at capacity into the
one-slot warm cache, off the morph lock’s critical path.
The next morph_capacity_to(capacity) consumes it and
skips allocation. Re-prewarming the cached capacity is a
no-op; a different capacity replaces the slot.
Sourcepub fn warm_capacity(&self) -> Option<usize>
pub fn warm_capacity(&self) -> Option<usize>
Capacity currently held in the warm cache, if any.
Sourcepub fn clear_warm(&self)
pub fn clear_warm(&self)
Drop any cached prediction, releasing its memory (and its file / shm region for non-anon locales).
Sourcepub fn gc(&self) -> usize
pub fn gc(&self) -> usize
Garbage-collect stale backings from the front of the chain. Drops the oldest contiguous run of backings whose strong-count is 1 (only the chain itself holds them; no subscriber is currently reading them). The active backing is never dropped even when it has strong-count 1 - that would lose the producer’s target. Returns the number of stale backings reclaimed.
Sourcepub fn ring_handle(&self) -> Arc<PubSubRing> ⓘ
pub fn ring_handle(&self) -> Arc<PubSubRing> ⓘ
Direct access to the currently-active PubSubRing.
Sourcepub fn chain_len(&self) -> usize
pub fn chain_len(&self) -> usize
Number of backings currently in the chain (active + any not-yet-gc’d stale entries).
Sourcepub fn chain_total_capacity(&self) -> usize
pub fn chain_total_capacity(&self) -> usize
Sum of capacities across every backing currently in the
chain. Used by KeepAll-style producers to bound in-flight
items to actual buffering room: any item the producer
publishes is held in SOME backing until the slowest
subscriber catches up; with at most chain_total_capacity()
in-flight items, no backing wraps past a subscriber’s
position before that subscriber drains it.