Skip to main content

IndexBackend

quillcache_core

Trait IndexBackend 

Source 
pub trait IndexBackend:
    Debug
    + Send
    + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn put(&mut self, residency: CacheResidency);
    fn locate(&self, key: &KvBlockKey) -> Vec<CacheResidency>;
    fn prefix_scan(
        &self,
        scope: &IdentityScope,
        prefix_hash: &str,
    ) -> Vec<CacheResidency>;
    fn remove_block(
        &mut self,
        scope: &IdentityScope,
        worker_id: &str,
        block_hash: &str,
    ) -> usize;
    fn clear_worker(&mut self, worker_id: &str);
    fn clear(&mut self);
    fn snapshot(&self) -> Vec<CacheResidency>;
    fn len(&self) -> usize;

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn metrics(&self) -> IndexMetrics { ... }
    fn persistent(&self) -> bool { ... }
}
Expand description

A pluggable residency-index backend.

The index maps KV-block identity (KvBlockKey) to residency (which worker and tier currently hold the block). It is the seam that lets QuillCache compare interchangeable backends — in-memory, Holt (persistent ART), RocksDB (LSM baseline), filesystem — on the same traces and policies.

Backends store and serve residency metadata only. They do not move or hold KV tensors; that is the data plane (LMCache / KVBM / the engine itself). Event translation (vLLM/SGLang KV events -> KvBlockKey) lives in the control plane and is backend-agnostic, so every backend sees the same put / remove_block / clear_worker calls.

Send + Sync + Debug so a backend can be held as Box<dyn IndexBackend> inside an async control plane behind a lock and swapped at runtime.

Required Methods§

Source

fn name(&self) -> &str

Stable backend name for reports (for example “memory”, “holt”, “rocksdb”).

Source

fn put(&mut self, residency: CacheResidency)

Insert or update a residency record for a block on a worker/tier.

Source

fn locate(&self, key: &KvBlockKey) -> Vec<CacheResidency>

Every residency for an exact block identity. A block may be resident on several workers or tiers at once.

Source

fn prefix_scan( &self, scope: &IdentityScope, prefix_hash: &str, ) -> Vec<CacheResidency>

Identity-aware prefix scan: residencies whose block belongs to scope and whose prefix_hash equals prefix_hash. This is the lookup where radix/ART backends are expected to beat flat maps and LSM stores.

Source

fn remove_block( &mut self, scope: &IdentityScope, worker_id: &str, block_hash: &str, ) -> usize

Remove a single block (by content hash, within an identity scope) from a worker. Returns the number of residency records removed.

Source

fn clear_worker(&mut self, worker_id: &str)

Drop everything resident on one worker/engine (for AllBlocksCleared or worker loss).

Source

fn clear(&mut self)

Drop the entire index.

Source

fn snapshot(&self) -> Vec<CacheResidency>

Full residency snapshot, for debugging and for routers that consume a slice of residency.

Source

fn len(&self) -> usize

Number of residency records currently held.

Provided Methods§

Source

fn is_empty(&self) -> bool

Source

fn metrics(&self) -> IndexMetrics

Comparable backend metrics (see IndexMetrics). The default derives resident_blocks/resident_bytes from a snapshot; persistent backends should override to also report bytes_written and counters.

Source

fn persistent(&self) -> bool

Whether this backend persists residency across process restarts. The in-memory reference backend returns false; Holt (ART), RocksDB (LSM), and filesystem backends return true. Drives recovery experiments and is surfaced in reports.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§