Struct ShardedCache 

pub struct ShardedCache { /* private fields */ }

64-shard query cache.

Each shard protects a HashMap<QueryKey, CachedResult> behind a parking_lot::RwLock. The query registry assigns each query type to a specific shard via TypeId hashing, so reads for different query types never contend on the same lock.

Raw-byte retention and persistence

Use [insert_query] (generic over Q: DerivedQuery) to insert entries with raw-byte retention. The method serialises the key and value at insert time and enforces the max_entry_size_bytes cap from QueryDbConfig.

Use [iter_persistent] to stream all persistent entries for the SAVE_PATH unit. It collects cheap Arc clones under each shard lock, then releases the lock before yielding, so shard locks are never held during I/O.

Implementations

impl ShardedCache

pub fn new(shard_count: usize) -> Self

Creates a new cache with the given number of shards.

Panics

Panics if shard_count is zero or not a power of two.

pub fn shard_count(&self) -> usize

Returns the number of shards.

pub fn get_if_valid<V: Clone + 'static>( &self, shard_idx: usize, key: &QueryKey, validate: impl FnOnce(&CachedResult) -> bool, ) -> Option<V>

Attempts to retrieve a cached value, validating and downcasting within the read lock scope.

The validate closure receives the cached result and should return true if the cache entry is still valid. If valid, the value is downcast and cloned. Returns None on miss, failed validation, or downcast failure.

This design avoids lifetime issues with read guards by performing all work within the lock scope.

pub fn get_cold_if_valid<V: Clone + Send + Sync + DeserializeOwned + 'static>( &self, shard_idx: usize, key: &QueryKey, validate: impl FnOnce(&CachedResult) -> bool, ) -> Option<V>

Cold-load rehydration lookup.

Companion to [get_if_valid] for entries placed by ShardedCache::insert_validated during PN3’s load_derived. Those entries carry raw postcard bytes for the value but only a unit placeholder in the typed Box<dyn Any> slot, so [get_if_valid]’s downcast returns None on them. This method:

1. Reads the cached entry; returns None on miss.
2. Runs validate (three-tier revision check). Returns None on fail.
3. If the entry’s raw bytes decode into V via postcard::from_bytes, promotes the entry in place only if no other thread has already written a typed value into the slot. Subsequent lookups hit the fast get_if_valid path. Returns the decoded value.

The read lock is dropped before the decode so the (moderately-sized) postcard work does not block the shard. The write lock for promotion is re-acquired briefly.

Concurrent-update safety

Between this method’s read and write phases another thread may have recomputed the entry, producing a fresher typed value, OR loaded a more recent revision from disk. Blindly overwriting cached.value in that gap would clobber the newer result with the stale cold- loaded one (Codex review finding on commit a41787179). The promote step therefore:

1. Re-reads the entry under the write lock.
2. Verifies it is still the unit placeholder left by [insert_validated] — i.e. value.downcast_ref::<()>() succeeds. If anything else lives there (a typed V, a different revision’s value, or a newly-recomputed result), skip the overwrite.
3. Verifies the raw bytes have not changed (e.g., a concurrent insert_query with a different value).
4. Only then writes the decoded value.

The caller still receives the decoded value it returned up, because correctness for this individual call does not depend on the promote succeeding — a lost promotion just means the next reader pays the decode cost too. The race window is bounded to at most one decode per concurrent reader per entry per cold-start session.

Errors

Returns None on miss, validation failure, or decode failure. The caller falls back to recomputation on None just as it would for a cold cache miss.

pub fn insert(&self, shard_idx: usize, key: QueryKey, result: CachedResult)

Inserts a pre-built CachedResult into the specified shard.

This is the low-level, non-generic insert used internally and by tests that construct CachedResult directly (without needing raw-byte retention). For production call-sites that require serialisation and the max_entry_size_bytes cap, use [insert_query] instead.

pub fn insert_query<Q: DerivedQuery>( &self, shard_idx: usize, query_key: QueryKey, key: &Q::Key, value: Q::Value, file_deps: SmallVec<[FileDep; 8]>, edge_revision: Option<u64>, metadata_revision: Option<u64>, config: &QueryDbConfig, ) -> Result<(), Error>

where Q::Key: Serialize, Q::Value: Serialize,

Type-aware insert for queries that require raw-byte retention.

Serialises key and value via postcard at insert time. If Q::PERSISTENT = true and raw_result_bytes.len() <= config.max_entry_size_bytes, the entry is stored with full persistence metadata. If the serialised value exceeds the cap, the entry is not stored (soft skip — returns Ok(())); the caller’s computed value is unaffected.

For Q::PERSISTENT = false, the typed value is stored but raw bytes are left empty and persistent = false — the entry is invisible to [iter_persistent].

Errors

Returns an error only if postcard serialisation of the key or value fails (should not occur for well-formed types that implement Serialize).

pub fn remove(&self, shard_idx: usize, key: &QueryKey) -> bool

Removes a specific key from a shard.

pub fn clear_all(&self)

Clears all entries from all shards.

pub fn total_entries(&self) -> usize

Returns the total number of cached entries across all shards.

pub fn shard_entry_counts(&self) -> Vec<usize>

Returns per-shard entry counts for diagnostics.

Trait Implementations

impl Send for ShardedCache

impl Sync for ShardedCache