Trait Lifecycle 

pub trait Lifecycle<Key, Val> {
    type RequestState: Default;

    // Provided methods
    fn is_pinned(&self, key: &Key, val: &Val) -> bool { ... }
    fn before_evict(
        &self,
        state: &mut Self::RequestState,
        key: &Key,
        val: &mut Val,
    ) { ... }
    fn on_evict(&self, state: &mut Self::RequestState, key: Key, val: Val) { ... }
    fn on_evict_cold(&self, state: &mut Self::RequestState, key: Key, val: Val) { ... }
    fn on_evict_hot(&self, state: &mut Self::RequestState, key: Key, val: Val) { ... }
}

Hooks into the lifetime of the cache items.

The functions should be small and very fast, otherwise the cache performance might be negatively affected.

Request state

Operations that may evict items thread a RequestState through the eviction hooks. It is a per-request accumulator: the cache constructs a fresh one via Default, the on_evict*/before_evict hooks record into it, and it is finalized by its own Drop (which, for example, releases evicted items after the shard lock is dropped).

The _with_lifecycle cache methods take &mut RequestState, letting a caller drive several operations against a single state — e.g. to batch the eviction work or inspect evicted items before dropping it:

let mut lcs = Default::default();
cache.insert_with_lifecycle(k1, v1, &mut lcs);
cache.insert_with_lifecycle(k2, v2, &mut lcs);
// inspect `lcs` here if desired; evicted items are released when it drops

Required Associated Types

type RequestState: Default

Per-request accumulator threaded through the eviction hooks.

Constructed via Default at the start of each request and finalized by its Drop. Keep it cheap to create and drop.

Provided Methods

fn is_pinned(&self, key: &Key, val: &Val) -> bool

Returns whether the item is pinned. Items that are pinned can’t be evicted. Note that a pinned item can still be replaced with get_mut, insert, replace and similar APIs.

Compared to zero (0) weight items, pinned items still consume (non-zero) weight even if they can’t be evicted. Furthermore, zero (0) weight items are separated from the other entries, which allows having a large number of them without impacting performance, but moving them in/out or the evictable section has a small cost. Pinning on the other hand doesn’t separate entries, so during eviction the cache may visit pinned entries but will ignore them.

fn before_evict(&self, state: &mut Self::RequestState, key: &Key, val: &mut Val)

Called when a cache item is about to be evicted. Note that value replacement (e.g. insertions for the same key) won’t call this method.

This is the only time the item can change its weight. If the item weight becomes zero (0) it will be left in the cache, otherwise it’ll still be removed. Zero (0) weight items aren’t evictable and are kept separated from the other items so it’s possible to have a large number of them without negatively affecting eviction performance.

fn on_evict(&self, state: &mut Self::RequestState, key: Key, val: Val)

Called when an item is evicted.

To distinguish evictions from the hot vs cold queues, override Lifecycle::on_evict_hot and/or Lifecycle::on_evict_cold instead; they default to delegating here.

If none of on_evict, on_evict_hot, or on_evict_cold is overridden, eviction notifications are silently dropped.

Note: items that are rejected without ever being admitted to the cache (oversized inserts and oversized placeholder values) are routed through Lifecycle::on_evict_cold, which by default reaches this method.

fn on_evict_cold(&self, state: &mut Self::RequestState, key: Key, val: Val)

Called when an item is evicted from the cold queue.

By default delegates to Lifecycle::on_evict.

Note: items that are rejected without ever being admitted to the cache (oversized inserts and oversized placeholder values) are also reported via this method.

fn on_evict_hot(&self, state: &mut Self::RequestState, key: Key, val: Val)

Called when an item is evicted from the hot queue.

By default delegates to Lifecycle::on_evict.

Note: rejected (never-admitted) items are reported via Lifecycle::on_evict_cold, not this method.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<Key, Val> Lifecycle<Key, Val> for quick_cache::sync::DefaultLifecycle<Key, Val>

type RequestState = [Option<(Key, Val)>; 2]

impl<Key, Val> Lifecycle<Key, Val> for quick_cache::unsync::DefaultLifecycle<Key, Val>

type RequestState = ()