lance_core/cache/
backend.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright The Lance Authors
3
4//! Backend interface for cache implementors.
5//!
6//! This module defines the trait that custom cache backends must implement,
7//! along with the entry type they operate on. Most callers should
8//! use [`LanceCache`](super::LanceCache) instead of interacting with
9//! backends directly.
10//!
11//! # Migrating custom backends
12//!
13//! Cache keys are opaque 16-byte values. Store
14//! [`InternalCacheKey::as_bytes`] directly instead of decomposing a logical
15//! prefix, key string, and Rust type name. The physical namespace must also
16//! include [`CACHE_KEY_FORMAT`](super::CACHE_KEY_FORMAT), so a future key
17//! protocol produces cold misses instead of aliases. Persistent or tiered
18//! backends can route serializable values with [`CacheCodec::type_id`].
19//!
20//! Prefix invalidation and key inventory are intentionally not part of this
21//! interface: one-way digests cannot support either operation without
22//! retaining the logical strings that fixed-size keys are designed to remove.
23//! Existing callers should migrate removed symbols as follows:
24//! - replace `with_backend_and_prefix(backend, prefix)` with
25//!   [`LanceCache::with_backend`](super::LanceCache::with_backend) followed by
26//!   [`LanceCache::with_key_prefix`](super::LanceCache::with_key_prefix);
27//! - replace `invalidate_prefix` with [`LanceCache::clear`](super::LanceCache::clear)
28//!   when clearing the shared backend is acceptable, or rotate a versioned
29//!   namespace to leave older entries to age out;
30//! - remove uses of `prefix`, `keys`, and session key-inventory methods; opaque
31//!   keys have no readable or enumerable equivalent.
32
33use std::any::Any;
34use std::pin::Pin;
35use std::sync::Arc;
36
37use async_trait::async_trait;
38use futures::Future;
39
40use crate::Result;
41use crate::deepsize::Context;
42
43use super::{CacheCodec, InternalCacheKey};
44
45/// A type-erased cache entry.
46pub type CacheEntry = Arc<dyn Any + Send + Sync>;
47
48/// Low-level pluggable cache backend.
49///
50/// Implementations store entries keyed by [`InternalCacheKey`] and return
51/// type-erased [`CacheEntry`] values.
52/// [`LanceCache`](super::LanceCache) handles key construction and type safety;
53/// backend authors only need to implement storage and eviction.
54#[async_trait]
55pub trait CacheBackend: Send + Sync + std::fmt::Debug {
56    /// Look up an entry by its key.
57    ///
58    /// `codec` is provided so that persistent backends can deserialize the
59    /// entry from storage. In-memory backends can ignore it. When `codec`
60    /// is `None`, the entry type does not support serialization yet and
61    /// must be stored in-memory.
62    ///
63    /// The goal is for all cache entry types to eventually have codecs,
64    /// at which point the `Option` will be removed.
65    async fn get(&self, key: &InternalCacheKey, codec: Option<CacheCodec>) -> Option<CacheEntry>;
66
67    /// Store an entry. `size_bytes` is used for eviction accounting.
68    ///
69    /// See [`get`](Self::get) for codec semantics.
70    async fn insert(
71        &self,
72        key: &InternalCacheKey,
73        entry: CacheEntry,
74        size_bytes: usize,
75        codec: Option<CacheCodec>,
76    );
77
78    /// Get an existing entry or compute it from `loader`.
79    ///
80    /// Implementations should deduplicate concurrent loads for the same key
81    /// so the loader runs at most once, unless caching is disabled. Disabled
82    /// caches may invoke each caller's loader independently.
83    ///
84    /// Returns `(entry, was_cached)` where `was_cached` is `true` if the entry
85    /// was already present in the cache (the loader was not invoked).
86    ///
87    /// See [`get`](Self::get) for codec semantics.
88    async fn get_or_insert<'a>(
89        &self,
90        key: &InternalCacheKey,
91        loader: Pin<Box<dyn Future<Output = Result<(CacheEntry, usize)>> + Send + 'a>>,
92        codec: Option<CacheCodec>,
93    ) -> Result<(CacheEntry, bool)>;
94
95    /// Remove all entries.
96    async fn clear(&self);
97
98    /// Number of entries currently stored (may flush pending operations).
99    async fn num_entries(&self) -> usize;
100
101    /// Total weighted size in bytes of all stored entries (may flush pending operations).
102    async fn size_bytes(&self) -> usize;
103
104    /// Approximate number of entries, callable from synchronous contexts.
105    /// Backends that cannot provide this cheaply should return 0.
106    fn approx_num_entries(&self) -> usize {
107        0
108    }
109
110    /// Approximate weighted size in bytes, callable from synchronous contexts.
111    /// Used as a `DeepSizeOf` fallback when exact entry traversal is unavailable.
112    /// Backends that cannot provide this cheaply should return 0.
113    ///
114    /// Assumes entries do not share underlying buffers; if they do, the
115    /// returned total may overcount.
116    fn approx_size_bytes(&self) -> usize {
117        0
118    }
119
120    /// Computes the size of the entries currently held in memory.
121    ///
122    /// `size_of_entry` threads a shared [`Context`] through each value so
123    /// allocations shared by multiple entries are counted once. It returns
124    /// `None` when the value's concrete type was not registered by
125    /// [`LanceCache`](super::LanceCache); implementations should use the
126    /// entry's declared eviction size as a fallback in that case.
127    ///
128    /// Backends that can enumerate their in-memory entries should include the
129    /// physical key footprint in the returned total. The default returns
130    /// `None`, causing `LanceCache` to use [`approx_size_bytes`](Self::approx_size_bytes).
131    fn deep_size_of_entries(
132        &self,
133        _context: &mut Context,
134        _size_of_entry: &dyn Fn(&CacheEntry, &mut Context) -> Option<usize>,
135    ) -> Option<usize> {
136        None
137    }
138}
lance_core/cache/backend.rs

lance_core/cache/
backend.rs
