Struct DiskKvStore 

pub struct DiskKvStore { /* private fields */ }

A content-addressed block store on disk, with its own writer threads.

Not Clone on purpose – it owns the writer threads and joins them when it drops. Share it as an Arc<DiskKvStore>; every method takes &self.

Implementations

impl DiskKvStore

pub fn open(config: DiskConfig) -> Result<Self, StoreError>

Creates the store’s directories and starts its writer threads. Does not scan root for pre-existing blocks: reattaching to a store left by a previous process is Self::reindex, an explicit step, because it costs a directory walk and a caller may prefer to start cold.

pub fn root(&self) -> &Path

pub fn put(&self, hash: BlockHash, block: KvBlock) -> Result<(), StoreError>

Accepts a block: buffered, indexed, then queued. Returns as soon as the block is visible – a reader can have it immediately, whether or not it has reached disk.

If the write queue is full the block is written on this thread rather than dropped, and the fallback is counted.

pub fn put_blocking( &self, hash: BlockHash, block: KvBlock, ) -> Result<(), StoreError>

Like Self::put, but always writes on the calling thread.

pub fn flush(&self)

Runs every pending write to completion, on this thread if no writer thread gets there first. Returns once the queue is empty and nothing is in flight.

pub fn get(&self, hash: &BlockHash, expected: &CacheSignature) -> ReadOutcome

Looks a block up, verifying it against expected before returning it. Blocks until the answer is in hand.

This is exactly Self::read_async plus a wait – the disk tier has no separate synchronous read path for a prefetch to have to work around later.

pub fn read_async( &self, hash: &BlockHash, expected: &CacheSignature, ) -> ReadHandle

Starts a read and returns immediately. The handle can be polled with ReadHandle::try_claim or waited on.

pub fn prefetch(&self, hashes: &[BlockHash], expected: &CacheSignature)

Reads hashes ahead of anyone asking for them, on the reader threads, and returns without waiting.

Intended for a prefix chain the moment its hashes are known: every block the request is about to want, read while the tokens before it are still being processed. Blocks already staged, in flight, or in memory are skipped; so is everything past prefetch_capacity, because reading ahead must never be the thing that exhausts memory.

pub fn clear_prefetch(&self)

Drops any staged read-ahead results. A caller that abandons a request it prefetched for should say so rather than leave the blocks occupying staging until something else needs the room.

pub fn reindex(&self) -> Result<usize, StoreError>

Adopts the blocks already under root, as a restart would.

pub fn remove(&self, hash: &BlockHash)

Removes a block from the index, the write buffer, and the disk.

pub fn contains(&self, hash: &BlockHash) -> bool

True if the index holds an entry for hash – on disk or still buffered. Says nothing about whether its contents will verify.

pub fn capacity(&self) -> u64

Byte ceiling an operator configured.

pub fn effective_capacity(&self) -> u64

The ceiling eviction is actually working to right now: the configured one, or less when free disk says so.

pub fn block_path(&self, hash: &BlockHash) -> PathBuf

Where a block’s file lives (or would). Useful to an operator tracing one block; the file may not exist yet, or at all.

pub fn stats(&self) -> DiskStats

Trait Implementations

impl Drop for DiskKvStore

fn drop(&mut self)

Stops accepting queued work and joins the worker threads. Blocks already queued but not started are not written: they were never durable, and a shutdown that waits for an arbitrarily deep queue is worse than a cold cache. Call Self::flush first if they matter.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.