omega_cache/core/
engine.rs

1use crate::core::entry::Entry;
2use crate::core::entry_ref::Ref;
3use crate::core::key::Key;
4use crate::core::request_quota::RequestQuota;
5use crate::core::thread_context::ThreadContext;
6use crate::metrics::MetricsSnapshot;
7use std::borrow::Borrow;
8use std::hash::Hash;
9
10/// A thread-safe, fixed-capacity caching interface.
11///
12/// This trait abstracts the underlying storage and eviction mechanics,
13/// allowing callers to interact with different cache implementations
14/// through a consistent API.
15///
16/// # Type Parameters
17/// * `K`: The key type, which must implement [`Eq`] and [`Hash`].
18/// * `V`: The value type stored in the cache.
19pub trait CacheEngine<K, V>
20where
21    K: Eq + Hash,
22{
23    /// Retrieves a protected reference to a cached value.
24    ///
25    /// Returns `Some(Ref<K, V>)` if the key exists and is not expired. Accessing
26    /// a key typically updates internal frequency metadata, which the eviction
27    /// algorithm uses to protect "hot" data from removal.
28    ///
29    /// # Memory Safety
30    /// The returned [`Ref`] pins the entry in memory using an epoch guard.
31    /// The data will remain valid and allocated until the reference is dropped
32    /// and the global epoch advances.
33    fn get<Q>(&self, key: &Q, context: &ThreadContext) -> Option<Ref<K, V>>
34    where
35        Key<K>: Borrow<Q>,
36        Q: Eq + Hash + ?Sized;
37
38    /// Inserts a key-value pair into the cache.
39    ///
40    /// This is a convenience wrapper around [`insert_with`] that always
41    /// admits the new entry. If the cache is full, an existing entry
42    /// is evicted based on the engine's internal policy.
43    fn insert(&self, entry: Entry<K, V>, context: &ThreadContext, quota: &mut RequestQuota);
44
45    /// Removes an entry from the cache.
46    ///
47    /// Returns `true` if the entry was found and successfully marked for
48    /// removal.
49    ///
50    /// # Consistency
51    /// This method performs an atomic "unlinking." The entry is immediately
52    /// made unreachable for new `get` requests, while existing readers
53    /// can continue to access the data safely until their [`Ref`] is dropped.
54    fn remove<Q>(&self, key: &Q, context: &ThreadContext) -> bool
55    where
56        Key<K>: Borrow<Q>,
57        Q: Eq + Hash + ?Sized;
58
59    /// Returns the total number of slots allocated for the cache.
60    fn capacity(&self) -> usize;
61
62    /// Returns a snapshot of internal cache statistics.
63    fn metrics(&self) -> MetricsSnapshot;
64}
omega_cache/core/engine.rs

omega_cache/core/
engine.rs
