Struct Cache 

pub struct Cache<V: Clone + Send + Sync + 'static> { /* private fields */ }

A robust, multi-level cache.

Cache<V> is generic over a single value type V. Unlike FusionCache (which leans on .NET runtime type information to store heterogeneous values in one instance), the idiomatic Rust model is one value type per cache — this makes “wrong type for this key” unrepresentable instead of a run-time downcast. Use several caches, or a sum type / serde_json::Value, for heterogeneous values.

Cloning a Cache is cheap (it shares one underlying instance) and is how you hand it to other tasks.

Implementations

impl<V: Clone + Send + Sync + 'static> Cache<V>

pub fn builder() -> CacheBuilder<V>

Starts building a cache.

pub fn new() -> Self

Creates a cache with all default settings and the real system clock.

pub fn name(&self) -> &str

The cache’s name.

pub fn events(&self) -> &Events

The event hub; subscribe to observe hits, misses, fail-safe activations…

pub fn entry_options(&self) -> EntryOptions

A clone of the cache’s default entry options, ready to tweak per call.

pub fn wait_for_initial_backplane_subscribe(&self) -> bool

Whether the cache establishes its backplane subscription before build returns (FusionCache WaitForInitialBackplaneSubscribe). In amalgam this is inherently satisfied — see CacheBuilder::wait_for_initial_backplane_subscribe.

pub async fn get_or_set<F, Fut>( &self, key: impl AsRef<str>, factory: F, ) -> Result<V>

where F: FnOnce(FactoryContext<V>) -> Fut + Send + 'static, Fut: Future<Output = Result<FactoryProduct<V>, FactoryError>> + Send + 'static,

Returns the cached value for key, or runs factory to produce it.

Uses the cache’s default options, no tags and no fail-safe default. See get_or_set_full for the complete form.

pub async fn get_or_set_with<F, Fut>( &self, key: impl AsRef<str>, factory: F, options: EntryOptions, ) -> Result<V>

where F: FnOnce(FactoryContext<V>) -> Fut + Send + 'static, Fut: Future<Output = Result<FactoryProduct<V>, FactoryError>> + Send + 'static,

Like get_or_set but with explicit per-call options.

pub async fn get_or_set_value( &self, key: impl AsRef<str>, value: V, options: Option<EntryOptions>, ) -> Result<V>

Returns the cached value for key, or stores and returns the constant value if it is absent.

The constant-value form of get_or_set: it goes through the same L1 → L2 → single-flight flow, but the “factory” simply yields value.

pub async fn get_or_set_full<F, Fut>( &self, key: impl AsRef<str>, factory: F, options: Option<EntryOptions>, tags: Box<[Tag]>, fail_safe_default: MaybeValue<V>, ) -> Result<V>

where F: FnOnce(FactoryContext<V>) -> Fut + Send + 'static, Fut: Future<Output = Result<FactoryProduct<V>, FactoryError>> + Send + 'static,

The full get_or_set: per-call options, tags for the produced entry, and a fail_safe_default served as a last resort when the factory fails and no stale value exists.

pub async fn set(&self, key: impl AsRef<str>, value: V)

Writes value with the cache’s default options and no tags.

pub async fn set_full( &self, key: impl AsRef<str>, value: V, options: Option<EntryOptions>, tags: Box<[Tag]>, )

Writes value with explicit options and tags.

pub async fn try_get( &self, key: impl AsRef<str>, options: Option<EntryOptions>, ) -> MaybeValue<V>

Reads a value without ever running a factory. A miss (or a stale entry, unless allow_stale_on_read_only is set) yields MaybeValue::none.

pub async fn get_or_default( &self, key: impl AsRef<str>, default: V, options: Option<EntryOptions>, ) -> V

Reads a value or returns default (never runs a factory).

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

Removes an entry from L1 and L2 and tells peers to evict it.

pub async fn expire(&self, key: impl AsRef<str>)

Logically expires an entry: it is no longer fresh, but fail-safe can still serve it as a stale fallback. Propagated to L2 and peers.

pub async fn remove_by_tag(&self, tag: impl AsRef<str>)

Invalidates every entry carrying tag (lazily — entries are dropped on their next read). No-op for a blank tag.

pub async fn remove_by_tags<I, S>(&self, tags: I)

where I: IntoIterator<Item = S>, S: AsRef<str>,

Invalidates every entry carrying any of tags.

pub async fn clear(&self, allow_fail_safe: bool)

Clears the whole cache.

With allow_fail_safe = true (the FusionCache default) every entry is logically expired so fail-safe can still serve stale values; with false they are hard-removed.

pub async fn run_pending_tasks(&self)

Runs the L1 backend’s pending maintenance (eviction, expiry). Primarily for deterministic tests.

Trait Implementations

impl<V: Clone + Send + Sync + 'static> Clone for Cache<V>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<V: Clone + Send + Sync + 'static> Default for Cache<V>

fn default() -> Self

Returns the “default value” for a type.