Struct HistoryCache 

pub struct HistoryCache { /* private fields */ }

Ordered sample storage.

Internal storage: BTreeMap for O(log n) insert/lookup and an efficient range iterator.

Note: the writing methods still need &mut self (BTreeMap is not concurrent-safe), but stats are available in parallel in an Arc<HistoryCacheStats> — see stats.

Implementations

impl HistoryCache

pub fn new_with_kind(kind: HistoryKind, max_samples: usize) -> Self

Creates a new cache. max_samples is the upper bound: with KeepAll exceeding it leads to CapacityExceeded, with KeepLast to LRU eviction of the oldest sample.

pub fn stats(&self) -> Arc<HistoryCacheStats>

Shared stats handle for lock-free monitoring.

Consumers hold an Arc<HistoryCacheStats> and poll the atomics with Acquire ordering. Values always reflect a completed cache mutation; cross-field consistency between len and max_sn is not guaranteed (tear risk).

pub fn new(max_samples: usize) -> Self

Legacy constructor — creates a KeepAll cache with a hard capacity limit. For new users prefer [new_with_kind].

pub fn kind(&self) -> HistoryKind

History kind of this cache.

pub fn set_kind_and_max(&mut self, kind: HistoryKind, max_samples: usize)

Expert-only: sets the history kind and max_samples cap at runtime.

Usage: short-term expansion for a backend replay burst (DurabilityService §2.2.3.5), when KeepLast(1) would collapse the replay window. The caller must restore the original kind afterwards.

This method moves no existing samples. If the new cap is smaller than the current sample count, the existing samples stay visible — the next insert then evicts by KeepLast rules.

pub fn max_samples(&self) -> usize

max_samples cap of the cache.

pub fn evicted_count(&self) -> u64

Number of samples discarded by KeepLast eviction since start.

pub fn insert(&mut self, change: CacheChange) -> Result<(), CacheError>

Inserts a change.

Errors

• CapacityExceeded: only with KeepAll, cache full.
• DuplicateSequenceNumber: SN already present.
• ZeroDepth: KeepLast { depth: 0 }.

pub fn insert_returning_evicted( &mut self, change: CacheChange, ) -> Result<Option<CacheChange>, CacheError>

Like Self::insert, but returns the evicted CacheChange (or None if nothing was evicted). Allows the caller to recycle the payload Arc<[u8]> instead of dropping it — see the ReliableWriter::stage_sample hot-path pool.

Errors

As Self::insert.

pub fn get(&self, sn: SequenceNumber) -> Option<&CacheChange>

Fetches a change by SN.

pub fn remove_up_to(&mut self, sn: SequenceNumber) -> usize

Removes all changes with SN ≤ sn. Returns the number of removed entries.

pub fn iter_range( &self, lo: SequenceNumber, hi: SequenceNumber, ) -> impl Iterator<Item = &CacheChange> + '_

Iterates in SN order over changes in the range [lo, hi] (both inclusive).

pub fn min_sn(&self) -> Option<SequenceNumber>

Smallest SN in the cache.

pub fn max_sn(&self) -> Option<SequenceNumber>

Largest SN in the cache.

pub fn len(&self) -> usize

Number of changes.

pub fn is_empty(&self) -> bool

True if no changes.

pub fn capacity(&self) -> usize

Maximum capacity.

Trait Implementations

impl Clone for HistoryCache

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HistoryCache

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

Formats the value using the given formatter.