Module cache 

Lance cache system.

For cache users

Use LanceCache (or WeakLanceCache) to store and retrieve typed values. Define a CacheKey (or UnsizedCacheKey for trait objects) to describe what you’re caching and its type.

To make a value type serializable (so persistent backends can store it), implement CacheCodecImpl on the type, then override CacheKey::codec:

impl CacheCodecImpl for MyData {
    fn serialize(&self, w: &mut dyn Write) -> Result<()> { /* ... */ }
    fn deserialize(data: &Bytes) -> Result<Self> { /* ... */ }
}

impl CacheKey for MyDataKey {
    type ValueType = MyData;
    fn key(&self) -> Cow<'_, str> { /* ... */ }
    fn type_name() -> &'static str { "MyData" }
    fn codec() -> Option<CacheCodec> {
        Some(CacheCodec::from_impl::<MyData>())
    }
}

For backend implementors

Implement CacheBackend to provide a custom storage layer (disk, Redis, etc.). Backends receive InternalCacheKey keys and type-erased CacheEntry values — the typed wrapping is handled by LanceCache. See the backend module for details.

Serialization flow

When a CacheKey provides a codec via CacheKey::codec:

1. LanceCache wraps the CacheCodec and passes it to the backend alongside the entry on insert and get calls.
2. In-memory backends (like MokaCacheBackend) ignore the codec.
3. Persistent backends use codec.serialize(entry, writer) on insert and codec.deserialize(reader) on get to persist entries across restarts.

Re-exports

pub use backend::CacheBackend;

pub use backend::CacheEntry;

pub use backend::CacheKeyIterator;

pub use backend::InternalCacheKey;

pub use codec::CacheCodec;

pub use codec::CacheCodecImpl;

pub use codec::CacheDecode;

pub use codec::CacheMissReason;

pub use codec::MAGIC;

pub use codec::has_cache_envelope;

pub use crate::deepsize::Context;

pub use crate::deepsize::DeepSizeOf;

Modules

backend

Backend interface for cache implementors.

codec

Serialization codecs for cache entries.

Structs

CacheEntryReader

Reads a cache entry body, tracking an offset into the input and exposing the entry’s type_version so implementors can branch for backward compat.

CacheEntryWriter

Writes a cache entry body: a header followed by sections, streaming directly to the underlying writer.

CacheStats

LanceCache

Typed cache wrapper that handles key construction and type safety.

MokaCacheBackend

Default CacheBackend backed by a moka cache.

WeakLanceCache

A weak reference to a LanceCache, used by indices to avoid circular references. When the original cache is dropped, operations on this will gracefully no-op.

Traits

CacheKey

Typed cache key for sized value types.

UnsizedCacheKey

Like CacheKey but for unsized value types (e.g. dyn Trait).

Derive Macros

DeepSizeOf

Derive macro for the DeepSizeOf trait.