Struct S3FIFOCache 

pub struct S3FIFOCache<K, V>
where
    K: Eq + Hash,
{ /* private fields */ }

A cache implementation based on the S3-FIFO (Simple Scalable Static FIFO) algorithm.

S3-FIFO uses a three-queue architecture to achieve high hit rates by separating transient “one-hit wonders” from frequently accessed data.

Architecture

1. Small Queue: An intake FIFO for new entries (probationary area).
2. Main Queue: A FIFO for entries that have proven their value (protected area).
3. Ghost Queue: Tracks hashes of recently evicted items to facilitate re-insertion directly into the Main Queue.

Implementations

impl<K, V> S3FIFOCache<K, V>

where K: Eq + Hash,

pub fn new( capacity: usize, backoff_config: BackoffConfig, metrics_config: MetricsConfig, ) -> Self

Creates a new S3Cache with the specified capacity.

The total capacity is partitioned between a 10% small probationary segment and a 90% main protected segment. All slots are initialized as empty and their indices are added to the available pool.

pub fn get<Q>(&self, key: &Q) -> Option<Ref<K, V>>

where Key<K>: Borrow<Q>, Q: Eq + Hash + ?Sized,

Retrieves a reference to an entry associated with the provided key.

If the entry exists and is valid, its access frequency is atomically incremented. This protects the entry from being removed during the next space-reclamation cycle.

pub fn insert_with( &self, key: K, value: V, expired_at: Option<Instant>, admission: impl Fn(&K, &K) -> bool, )

Handles the admission of new entries into the probationary segment.

If the segment is full, this function triggers space reclamation. The entry is stored in a slot obtained from the available pool and then appended to the small queue.

pub fn remove<Q>(&self, key: &Q) -> bool

where Key<K>: Borrow<Q>, Q: Eq + Hash + ?Sized,

Trait Implementations

impl<K, V> CacheEngine<K, V> for S3FIFOCache<K, V>

where K: Eq + Hash,

fn get<Q>(&self, key: &Q) -> Option<Ref<K, V>>

where Key<K>: Borrow<Q>, Q: Eq + Hash + ?Sized,

Retrieves a protected reference to a cached value.

fn insert_with<A>( &self, key: K, value: V, expired_at: Option<Instant>, admission: A, )

where A: Fn(&K, &K) -> bool,

Inserts a key-value pair with a custom admission policy.

fn remove<Q>(&self, key: &Q) -> bool

where Key<K>: Borrow<Q>, Q: Eq + Hash + ?Sized,

Removes an entry from the cache.

fn capacity(&self) -> usize

Returns the total number of slots allocated for the cache.

fn metrics(&self) -> MetricsSnapshot

Returns a snapshot of internal cache statistics.

fn insert(&self, key: K, value: V, expired_at: Option<Instant>)

Inserts a key-value pair into the cache.