Struct BlockCache 

pub struct BlockCache<F: AsyncFileReader> { /* private fields */ }

A caching wrapper that fetches fixed-size aligned blocks around each accessed offset.

Unlike a sequential readahead cache, a block cache handles the scattered access patterns of HDF5 metadata efficiently: the superblock is at offset 0, object headers and B-tree nodes are scattered across the file, and a sequential cache would waste bandwidth fetching unneeded array data between metadata structures.

When a byte range is requested, the cache fetches any aligned blocks that overlap the range and caches them for future reads. Nearby metadata reads (e.g., an object header and its continuation chunk, or adjacent B-tree nodes) naturally share blocks.

Default block size is 8 MiB, which typically resolves all metadata for a GOES-16 MCMIPF file (~164 datasets) in about 10 requests.

Implementations

impl<F: AsyncFileReader> BlockCache<F>

pub fn new(inner: F) -> Self

Create a new BlockCache wrapping the given reader. Default block size: 8 MiB.

pub fn inner(&self) -> &F

Access the inner reader.

pub fn with_block_size(self, block_size: u64) -> Self

Set the block size in bytes.

impl<F: AsyncFileReader> BlockCache<F>

pub async fn pre_warm(&self, file_size: u64, max_bytes: u64) -> Result<()>

Pre-fetch blocks in parallel to eliminate sequential cache misses during metadata traversal (B-tree parsing, object headers, etc.).

• If max_bytes covers the entire file, every block is fetched.
• Otherwise only the first max_bytes / block_size blocks are fetched (HDF5 metadata — superblock, root group, B-tree nodes — is typically concentrated near the beginning of the file).

Issues a single batched get_byte_ranges call so that the backend can coalesce and parallelize the fetches.

Trait Implementations

impl<F: AsyncFileReader + Send + Sync> AsyncFileReader for BlockCache<F>

fn get_bytes<'life0, 'async_trait>( &'life0 self, range: Range<u64>, ) -> Pin<Box<dyn Future<Output = Result<Bytes>> + Send + 'async_trait>>

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

Fetch the bytes in the given range.

fn get_byte_ranges<'life0, 'async_trait>( &'life0 self, ranges: Vec<Range<u64>>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Bytes>>> + Send + 'async_trait>>

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

Fetch multiple byte ranges. The default implementation calls get_bytes sequentially; ObjectReader overrides this with get_ranges().

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

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

Return the total file size, if known. Used by BlockCache::pre_warm to fetch all blocks in parallel. The default returns None.

impl<F: Debug + AsyncFileReader> Debug for BlockCache<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.