Trait EvictionManager

pub trait EvictionManager {
    // Required methods
    fn total_size(&self) -> usize;
    fn total_items(&self) -> usize;
    fn evicted_size(&self) -> usize;
    fn evicted_items(&self) -> usize;
    fn admit(
        &self,
        item: CompactCacheKey,
        size: usize,
        fresh_until: SystemTime,
    ) -> Vec<CompactCacheKey>;
    fn remove(&self, item: &CompactCacheKey);
    fn access(
        &self,
        item: &CompactCacheKey,
        size: usize,
        fresh_until: SystemTime,
    ) -> bool;
    fn peek(&self, item: &CompactCacheKey) -> bool;
    fn save<'life0, 'life1, 'async_trait>(
        &'life0 self,
        dir_path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn load<'life0, 'life1, 'async_trait>(
        &'life0 self,
        dir_path: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
}

The trait that a cache eviction algorithm needs to implement

NOTE: these trait methods require &self not &mut self, which means concurrency should be handled the implementations internally.

Required Methods

fn total_size(&self) -> usize

Total size of the cache in bytes tracked by this eviction manager

fn total_items(&self) -> usize

Number of assets tracked by this eviction manager

fn evicted_size(&self) -> usize

Number of bytes that are already evicted

The accumulated number is returned to play well with Prometheus counter metric type.

fn evicted_items(&self) -> usize

Number of assets that are already evicted

The accumulated number is returned to play well with Prometheus counter metric type.

fn admit( &self, item: CompactCacheKey, size: usize, fresh_until: SystemTime, ) -> Vec<CompactCacheKey>

Admit an item

Return one or more items to evict. The sizes of these items are deducted from the total size already. The caller needs to make sure that these assets are actually removed from the storage.

If the item is already admitted, A. update its freshness; B. if the new size is larger than the existing one, Some(_) might be returned for the caller to evict.

fn remove(&self, item: &CompactCacheKey)

Remove an item from the eviction manager.

The size of the item will be deducted.

fn access( &self, item: &CompactCacheKey, size: usize, fresh_until: SystemTime, ) -> bool

Access an item that should already be in cache.

If the item is not tracked by this EvictionManager, track it but no eviction will happen.

The call used for asking the eviction manager to track the assets that are already admitted in the cache storage system.

fn peek(&self, item: &CompactCacheKey) -> bool

Peek into the manager to see if the item is already tracked by the system

This function should have no side-effect on the asset itself. For example, for LRU, this method shouldn’t change the popularity of the asset being peeked.

fn save<'life0, 'life1, 'async_trait>( &'life0 self, dir_path: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Serialize to save the state of this eviction manager to disk

This function is for preserving the eviction manager’s state across server restarts.

dir_path define the directory on disk that the data should use.

fn load<'life0, 'life1, 'async_trait>( &'life0 self, dir_path: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The counterpart of Self::save().

Implementors

impl EvictionManager for pingora_cache::eviction::simple_lru::Manager

impl<const N: usize> EvictionManager for pingora_cache::eviction::lru::Manager<N>