linera_cache/lib.rs
1// Copyright (c) Zefchain Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Caching utilities for the Linera protocol.
5//!
6//! ## Hash-consing and the "one allocation per content" invariant
7//!
8//! [`ValueCache`] is the canonical home for content-addressed immutable data
9//! (also known as hash-consed data) such as `Block`, `Blob`, and
10//! `ConfirmedBlockCertificate`. For such types the cache guarantees that at
11//! most one allocation exists per distinct content at any time, and all
12//! consumers share the same `Arc<T>`.
13//!
14//! The guarantee is implemented by combining two structures:
15//!
16//! - A bounded `quick_cache` (S3-FIFO eviction) for hot-path lookups.
17//! - A lock-free `papaya::HashMap<K, Weak<V>>` weak index that survives bounded
18//! eviction. If the bounded cache evicts an entry while a consumer still
19//! holds an `Arc`, re-requesting the same key returns the existing
20//! allocation instead of creating a duplicate.
21//!
22//! A background task periodically sweeps dead `Weak` entries from the index to
23//! prevent unbounded growth.
24//!
25//! For the invariant to hold, all inserts of hash-consed values must go
26//! through the cache (e.g. [`ValueCache::insert`] or [`ValueCache::insert_hashed`]).
27//! The [`Arc`] newtype enforces this structurally: it has no public constructor,
28//! so callers cannot bypass the cache by calling `std::sync::Arc::new` directly.
29
30#![deny(missing_docs)]
31
32mod arc;
33mod unique_value_cache;
34mod value_cache;
35
36pub use arc::Arc;
37pub use unique_value_cache::UniqueValueCache;
38pub use value_cache::{ValueCache, DEFAULT_CLEANUP_INTERVAL_SECS};