Struct Engram 

pub struct Engram { /* private fields */ }

A reusable asynchronous cache with Moka memory and SQLite persistence tiers. Engram is cheap to clone; clones share memory, persistence, and synchronization.

Implementations

impl Engram

pub fn builder() -> EngramBuilder

Starts configuration of an Engram cache.

pub async fn get<T>(&self, key: impl AsRef<str>) -> Result<Option<T>>

where T: DeserializeOwned + Clone + Send + Sync + 'static,

Retrieves a value, checking Moka before SQLite.

pub async fn get_key<T>(&self, key: &CacheKey<T>) -> Result<Option<T>>

where T: DeserializeOwned + Clone + Send + Sync + 'static,

Retrieves a value using a caller-controlled schema tag.

pub async fn get_with_metadata<T>( &self, key: impl AsRef<str>, ) -> Result<Option<CacheEntry<T>>>

where T: DeserializeOwned + Clone + Send + Sync + 'static,

Retrieves a value with expiration/source metadata.

pub async fn get_key_with_metadata<T>( &self, key: &CacheKey<T>, ) -> Result<Option<CacheEntry<T>>>

where T: DeserializeOwned + Clone + Send + Sync + 'static,

Retrieves a value and metadata using a caller-controlled schema tag.

pub async fn get_arc<T>(&self, key: impl AsRef<str>) -> Result<Option<Arc<T>>>

where T: DeserializeOwned + Send + Sync + 'static,

Retrieves a shared L1 value without cloning it. This is useful for large values.

pub async fn get_arc_key<T>(&self, key: &CacheKey<T>) -> Result<Option<Arc<T>>>

where T: DeserializeOwned + Send + Sync + 'static,

Retrieves a shared value using a caller-controlled schema tag.

pub async fn metadata( &self, key: impl AsRef<str>, ) -> Result<Option<CacheMetadata>>

Returns expiry and source information without deserializing an L2 value.

pub async fn set<T>( &self, key: impl AsRef<str>, value: &T, ttl: Option<Duration>, ) -> Result<()>

where T: Serialize + Clone + Send + Sync + 'static,

Stores a value in both tiers using serialized byte length as its L1 weight.

pub async fn set_arc<T>( &self, key: impl AsRef<str>, value: Arc<T>, ttl: Option<Duration>, ) -> Result<()>

where T: Serialize + Send + Sync + 'static,

Stores a shared value without cloning it for L1.

pub async fn set_key<T>( &self, key: &CacheKey<T>, value: &T, ttl: Option<Duration>, ) -> Result<()>

where T: Serialize + Clone + Send + Sync + 'static,

Stores a value with a caller-controlled schema tag.

pub async fn set_arc_key<T>( &self, key: &CacheKey<T>, value: Arc<T>, ttl: Option<Duration>, ) -> Result<()>

where T: Serialize + Send + Sync + 'static,

Stores a shared value with a caller-controlled schema tag.

pub async fn set_with_weight<T>( &self, key: impl AsRef<str>, value: &T, ttl: Option<Duration>, weight: u32, ) -> Result<()>

where T: Serialize + Clone + Send + Sync + 'static,

Stores a value with an explicit L1 weight, useful when serialized size is not representative of its in-memory footprint.

pub async fn set_arc_with_weight<T>( &self, key: impl AsRef<str>, value: Arc<T>, ttl: Option<Duration>, weight: u32, ) -> Result<()>

where T: Serialize + Send + Sync + 'static,

Stores an Arc with an explicit L1 weight.

pub async fn set_many<T, I, K>( &self, values: I, ttl: Option<Duration>, ) -> Result<()>

where T: Serialize + Send + Sync + 'static, I: IntoIterator<Item = (K, T)>, K: Into<String>,

Persists many values in one SQLite transaction.

pub async fn remove(&self, key: impl AsRef<str>) -> Result<()>

Removes a key from both memory and persistent storage.

pub async fn clear(&self) -> Result<()>

Clears both cache tiers.

pub async fn purge_expired(&self) -> Result<u64>

Deletes expired SQLite rows and returns the number removed.

pub async fn get_or_try_init<T, F, Fut>( &self, key: impl AsRef<str>, ttl: Option<Duration>, init: F, ) -> Result<T>

where T: Serialize + DeserializeOwned + Clone + Send + Sync + 'static, F: FnOnce() -> Fut, Fut: Future<Output = Result<T>>,

Reads a key, calling init only on a miss and coalescing concurrent calls for the same key. A failed initialization is not cached.

Trait Implementations

impl Clone for Engram

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.