Struct CachedBlockReader 

pub struct CachedBlockReader<S, C> { /* private fields */ }

Read-only block reader wrapper that consults a local file-style cache.

The cache file contains a compact header, a per-block validity bitmap, and raw backing bytes. Misses are fetched from the inner reader, written into the data region, and marked valid.

The cache flushes automatically after writing flush_every_blocks new blocks to ensure persistence across sessions. There is no dirty flag; the bitmap is the authoritative source of validity.

Implementations

impl<S, C> CachedBlockReader<S, C>

where S: BlockReader, C: CacheOps,

pub async fn new(inner: S, cache: C) -> GibbloxResult<Self>

Construct a cached reader using the default flush policy.

pub async fn with_flush_block_limit( inner: S, cache: C, flush_every_blocks: u32, ) -> GibbloxResult<Self>

Construct a cached reader with a custom flush threshold.

The cache will flush after writing flush_every_blocks newly cached blocks. Lower values provide better crash resilience at the cost of more frequent I/O. A value of 1 flushes after every write batch (maximally safe but slowest).

pub async fn flush_cache(&self) -> GibbloxResult<()>

Force a cache flush and clear the dirty bit if there are pending writes.

pub async fn get_stats(&self) -> CacheStats

Return a snapshot of cache statistics.

pub async fn ensure_cached( &self, lba: u64, blocks: u64, ctx: ReadContext, ) -> GibbloxResult<()>

Ensure blocks [lba, lba+blocks) are cached without copying data out.

This fetches any missing blocks from the inner reader and populates the cache without allocating or returning a caller buffer.

Already-cached blocks are skipped (bitmap check only). The provided ReadContext propagates priority hints to the inner reader.

Trait Implementations

impl<S, C> BlockReader for CachedBlockReader<S, C>

where S: BlockReader, C: CacheOps,

fn block_size(&self) -> u32

Logical block size in bytes.

fn total_blocks<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = GibbloxResult<u64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Total number of logical blocks available.

fn write_identity(&self, out: &mut dyn Write) -> Result

Write a stable, canonical identity string for this block reader.

fn read_blocks<'life0, 'life1, 'async_trait>( &'life0 self, lba: u64, buf: &'life1 mut [u8], ctx: ReadContext, ) -> Pin<Box<dyn Future<Output = GibbloxResult<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read one or more blocks starting at lba into buf.