Struct CacheDirectory 

pub struct CacheDirectory<S = DefaultHashBuilder> { /* private fields */ }

Implementations

impl CacheDirectory<DefaultHashBuilder>

pub fn new() -> Self

Construct an empty cache using the default per-process-randomized hasher.

impl<S: BuildHasher> CacheDirectory<S>

pub fn with_hasher(hasher: S) -> Self

where S: Clone,

Construct an empty cache with an explicit hasher.

impl<S> CacheDirectory<S>

pub const fn new_const(blobs_hasher: S, instances_hasher: S) -> Self

const fn constructor for static initialisation. Used by the guest’s state_cache::CACHE static. Takes both hashers separately because const fn can’t call S::clone() and not every BuildHasher (notably foldhash::fast::FixedState) implements Copy. Callers normally pass two identically-seeded instances so both maps hash to the same buckets.

impl<S: BuildHasher> CacheDirectory<S>

pub fn blob_count(&self) -> usize

Number of blob entries.

pub fn instance_count(&self) -> usize

Number of instance entries (live or unswept).

pub fn contains_blob(&self, hash: &CapHash) -> bool

Whether the blobs tier holds an entry under hash.

pub fn get_blob(&self, hash: &CapHash) -> Option<Arc<Cap>>

Get an Arc::clone of the blob cap at hash, or None if absent.

pub fn get_instance(&self, capref: &CapRef) -> Option<Arc<Cap>>

Get an Arc::clone of the instance cap at capref, or None if absent.

pub fn iter_blobs(&self) -> Vec<(CapHash, Arc<Cap>)>

Snapshot the blob tier into a Vec<(CapHash, Arc<Cap>)>. Order is unspecified (HashMap iteration); callers that need deterministic order (state-root computations) sort by hash.

pub fn get(&self, key: CapHashOrRef) -> Option<Arc<Cap>>

Polymorphic lookup that dispatches on the CapHashOrRef arm. Returns an Arc::clone of the matching cap.

pub fn set_instance( &self, capref: &CapRef, new_arc: Arc<Cap>, ) -> Result<(), CacheError>

Replace the instance at capref with a fresh Arc<Cap>. The old Arc<Cap> drops outside the lock (so any cascading Cap::drop → CapRef::drop chain doesn’t try to re-enter the directory while we hold the guard).

pub fn put_cap(&self, cap: &Cap) -> Result<CapHash, CacheError>

Hash + insert into blobs. Idempotent: re-puts of identical content are a no-op. Returns the content hash.

pub fn put_cap_with_hash( &self, hash: CapHash, cap: &Cap, ) -> Result<(), CacheError>

Pre-hashed insert. Debug-asserts the claimed hash matches the cap; release trusts the caller (the SSZ merkleize is the hot cost on the publish path).

pub fn put_instance(&self, cap: Cap) -> CapRef

Insert a freshly-built Cap as a new instance entry. Returns the CapRef handle. The directory keeps its own clone of the returned handle internally as the entry’s self-reference; when all external clones drop, sweep_instances will reclaim the entry.

pub fn promote_blob_to_instance(&self, hash: &CapHash) -> Option<CapRef>

Lazily promote a blob to a fresh instance entry. The blob and the new instance entry share the same Arc<Cap> (no Cap data deep-copy); the next Arc::make_mut call on either side clones-on-write if both still hold the Arc.

Returns None if the blob isn’t published.

pub fn sweep_instances(&self)

GC pass. Walk the instances tier and remove every entry whose stored CapRef has strong_count == 1 (the directory is the sole holder — no external CapRef clone exists). Loop until a pass finds nothing to remove, so cascading drops can orphan more entries which then get reclaimed in the next iteration.

Cycles are structurally impossible (data-flow principle), so the loop is guaranteed to terminate.

pub fn settle(&self, key: CapHashOrRef) -> Result<CapHash, CacheError>

Settle a Ref-keyed working entry: walk nested Ref targets, resolve each to a Hash, then hash the surviving cap. Non- Instance entries (Data / CNode) graduate from instances to blobs under the computed hash; Instance entries stay in instances (they’re the live mutable state) and the returned hash is a snapshot identifier.

For Hash-keyed input, returns it unchanged.

Trait Implementations

impl Default for CacheDirectory<DefaultHashBuilder>

fn default() -> Self

Returns the “default value” for a type.