Struct FoyerHybridCache 

pub struct FoyerHybridCache { /* private fields */ }

Hybrid memory + disk cache backed by foyer.

Construction requires an async runtime because foyer’s builder is async. We pin a dedicated multi-thread runtime to the cache instance and reuse it for the slow path on memory miss.

Implementations

impl FoyerHybridCache

pub fn open(config: FoyerCacheConfig) -> Result<Arc<Self>, FoyerCacheError>

Build a new hybrid cache. Creates the on-disk directory if missing. Allocates a fresh tokio runtime for foyer’s async paths.

pub fn open_with_runtime( config: FoyerCacheConfig, runtime: Arc<Runtime>, ) -> Result<Arc<Self>, FoyerCacheError>

Build the cache with a caller-provided runtime. Useful for sharing a runtime across multiple subsystems in the same process.

pub fn ssd_dir(&self) -> &Path

pub fn hits(&self) -> u64

pub fn misses(&self) -> u64

pub fn inserts(&self) -> u64

pub fn get(&self, key: &str) -> Option<Bytes>

Sync read. Probes the in-memory tier first to avoid a runtime hop on warm hits. Falls through to foyer’s async hybrid get only when the memory tier misses.

Convenience wrapper over get_with_tier for callers that don’t need to distinguish RAM vs SSD hits.

pub fn get_with_tier(&self, key: &str) -> Option<(Bytes, FoyerHitTier)>

Sync read with tier attribution. Returns the tier the value was served from on hit. Lets callers attribute load latency to the right tier, critical for diagnosing the “blob too big for RAM tier, always SSD-streamed” case (e.g. qwen3’s pre-allocated 4.7 GiB KV cache against a 2 GiB RAM budget).

pub fn contains(&self, key: &str) -> bool

Sync existence check that does not materialize the cached payload.

pub fn put(&self, key: &str, payload: Bytes)

Sync write. Foyer’s insert is sync; the disk-side flush happens on background workers driven by the cache’s spawner.

pub fn clear(&self)

Drop all entries from both tiers.

pub fn close(&self)

Block until the foyer write-queue has drained to SSD.

Foyer’s Drop impl spawns a close future on the cache’s own spawner but does NOT wait for it, so process exit immediately after the last Arc clone drops can leave SSD entries un-flushed. This method is the explicit drain hook callers should invoke before tearing down the cache; the Drop impl on FoyerHybridCache also calls it on a best-effort basis.

Trait Implementations

impl Drop for FoyerHybridCache

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.