Struct PortableCache 

pub struct PortableCache<K, V> { /* private fields */ }

Portable, runtime-agnostic in-process cache.

• Max capacity with FIFO eviction
• TTL (time-to-live) and TTI (time-to-idle)
• Single-flight get_with / get_with_by_ref

Implementations

impl<K, V> PortableCache<K, V>

where K: Hash + Eq + Clone + Send + Sync + 'static, V: Clone + Send + Sync + 'static,

pub fn builder() -> PortableCacheBuilder<K, V>

pub async fn get<Q>(&self, key: &Q) -> Option<V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

pub async fn insert(&self, key: K, value: V)

pub async fn upsert_with_by_ref<Q, R>( &self, key: &Q, update: impl FnOnce(Option<&V>) -> (Option<V>, R), ) -> R

where K: Borrow<Q>, Q: ToOwned<Owned = K> + Hash + Eq + ?Sized,

Atomically derive and optionally store a value from the current entry.

The closure runs synchronously under the cache’s existing write lock. Returning None leaves an existing value unchanged and keeps a missing key absent. The key is cloned only when the operation inserts a new entry.

pub async fn remove<Q>(&self, key: &Q) -> Option<V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

pub async fn invalidate<Q>(&self, key: &Q)

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

pub async fn clear(&self)

Reliably remove all entries, awaiting the write lock. Prefer this in async contexts over invalidate_all, whose best-effort sync spin can skip the clear under sustained write contention.

pub fn invalidate_all(&self)

Sync invalidate. Spins briefly if the lock is held; kept for moka API parity. In async contexts prefer clear, which can’t silently skip the clear.

pub fn entry_count(&self) -> u64

pub async fn snapshot_entries(&self) -> Vec<(Arc<K>, V)>

Reliable awaited snapshot of (Arc<K>, V) pairs. Prefer this over iter in async contexts: iter is best-effort (a try_read spin that yields an empty snapshot under write contention), which would silently skip entries an invalidation pass must see.

pub async fn fold_entries<A>(&self, init: A, f: impl FnMut(A, &K, &V) -> A) -> A

Reliable awaited fold over (&K, &V). Unlike the snapshot walks this clones nothing — memory reports must not themselves allocate in proportion to the cache — and unlike iter it cannot degrade to an empty walk under write contention.

pub async fn memory_stats( &self, per_entry: impl FnMut(&K, &V) -> usize, ) -> CollectionStats

Entry count plus estimated retained bytes, summing per_entry under a single awaited read guard so the pair is mutually consistent (and never the empty best-effort snapshot iter can degrade to).

pub fn iter(&self) -> IntoIter<(Arc<K>, V)>

Eager snapshot iterator over (Arc<K>, V): snapshot, not lazy. Includes expired-but-not-yet-evicted entries (consistent with entry_count). Best-effort (try_read spin); use snapshot_entries when missing an entry would be a correctness bug. Caller must not .await with the writer guard held from the same task — would deadlock on single-threaded runtimes.

pub async fn get_with<F>(&self, key: K, init: F) -> V

where F: Future<Output = V> + MaybeSend,

Get or insert (single-flight). Takes key by value.

The initializer is boxed only on cache miss — a hit returns without allocating. The boxing keeps the slow path monomorphic per <K, V> instead of per call-site future type. A racer that loses the double-check inside get_with_slow pays one spare box; deferring the box past the double-check would drag the future type parameter back into the slow path, re-stamping it per call site.

pub async fn get_with_by_ref<Q, F>(&self, key: &Q, init: F) -> V

where K: Borrow<Q>, Q: ToOwned<Owned = K> + Hash + Eq + ?Sized, F: Future<Output = V> + MaybeSend,

Get or insert (single-flight). Takes key by reference — only allocates the owned key (and the boxed initializer) on cache miss.

pub async fn run_pending_tasks(&self)

Evict expired entries and clean up unused init locks.

Trait Implementations

impl<K, V> Clone for PortableCache<K, V>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.