segcache 0.2.0

// Copyright 2021 Twitter, Inc.
// Copyright 2023 Pelikan Cache contributors
// Licensed under the MIT and Apache-2.0 licenses

/// Policies define the eviction strategy to be used. All eviction strategies
/// exclude segments which are currently accepting new items.
#[derive(Copy, Clone, Debug)]
pub enum Policy {
    /// No eviction. When all the segments are full, inserts will fail until
    /// segments are freed by TTL expiration.
    None,
    /// Segment random eviction. Selects a random segment and evicts it. Similar
    /// to slab random eviction.
    Random,
    /// Random FIFO eviction. Selects a random TTL Bucket, weighted by the
    /// number of segments, and evicts the oldest segment in the bucket. This
    /// strategy helps preserve the TTL distribution of the working set and
    /// prioritizes keeping newer items.
    RandomFifo,
    /// FIFO segment eviction. Selects the oldest segment and evicts it. As
    /// segments are append-only, this is similar to both slab LRU and slab LRC
    /// eviction strategies.
    Fifo,
    /// Closest to expiration. Selects the segment that would expire first and
    /// evicts it. This is a unique eviction strategy in segcache and
    /// effectively causes early expiration to free a segment.
    Cte,
    /// Least utilized segment. As segments are append-only, when an item is
    /// replaced or removed the segment containing that item now has dead bytes.
    /// This eviction strategy will free the segment that has the lowest number
    /// of live bytes. This strategy should cause the smallest impact to the
    /// number of live bytes held in the cache.
    Util,
    /// Merge eviction is a unique feature in segcache. It tries to retain items
    /// which have the biggest positive effect on hitrate.
    /// At its core, the idea is to take sequential segments in a chain,
    /// and merge their items into one segment. Unlike the NSDI paper, this
    /// implementation performs two different types of merge operations. The one
    /// matching the NSDI paper is used during eviction and may cause items to
    /// be evicted based on an estimate of their hit frequency. The other
    /// possible merge operation is a simple compaction which will combine
    /// segments which have low utilization (due to item replacement/deletion)
    /// without evicting any live items. Compaction has proven to be beneficial
    /// in workloads that frequently overwrite or delete items in the cache.
    Merge {
        /// The maximum number of segments to merge in a single pass. This can
        /// be used to bound the tail latency impact of a merge operation.
        max: usize,
        /// The target number of segments to merge during eviction. Setting this
        /// higher will result in fewer eviction passes and allow the algorithm
        /// to see more item frequencies. Setting this lower will cause fewer
        /// item evictions per pass.
        merge: usize,
        /// The target number of segments to merge during compaction. Compaction
        /// will only occur if a segment falls below `1/N`th occupancy. Setting
        /// this higher will cause fewer compaction runs but can result in a
        /// larger percentage of dead bytes.
        ///
        /// Note: Compaction will be disabled by setting this parameter to zero.
        compact: usize,
    },
    /// S3-FIFO eviction (S3-Segcache) uses two pools of segments — admission
    /// and main — plus a ghost queue of recently evicted key fingerprints.
    /// New items are written to admission-pool segments. When an admission
    /// segment is evicted, items with frequency > 0 are promoted (copied
    /// into a main-pool segment); items with frequency == 0 are dropped and
    /// their hashes added to the ghost queue. Main-pool segments use
    /// CLOCK-style second-chance eviction.
    ///
    /// If a newly inserted key's hash is found in the ghost queue, the item
    /// is written directly to a main-pool segment, bypassing admission.
    S3Fifo {
        /// Ratio of total segments allocated to the admission pool,
        /// between 0.0 and 1.0. The remaining segments form the main
        /// pool. Typical values are 0.05–0.20. Default: 0.10.
        admission_ratio: f64,
    },
}