Struct MetadataCacheStats 

pub struct MetadataCacheStats { /* private fields */ }

What a file’s metadata cache has done, and what it is holding.

Returned by crate::File::metadata_cache_stats. This is the hdf5-pure counterpart to HDF5’s H5Fget_mdc_hit_rate and H5Fget_mdc_size: entries and bytes are a point-in-time view of occupancy, and the counters are cumulative since the file was opened or since the last reset_metadata_cache_stats.

The reason to look is that MetadataCacheConfig is a budget chosen before a single read has happened, and nothing else reports whether it was the right one:

• hit_rate says whether the cache is earning its memory.
• evictions says whether the budget is the binding constraint. A hit rate below expectations with no evictions is not a budget problem, and raising it will not help.
• oversize_reads says whether max_entry_bytes is turning reads away before they reach the cache at all.
• invalidations says how much of the cache a read-write session is throwing away with its own writes.

Implementations

impl MetadataCacheStats

pub const fn hits(&self) -> u64

Metadata reads served from the cache.

pub const fn misses(&self) -> u64

Metadata reads eligible for the cache that were not in it.

pub const fn oversize_reads(&self) -> u64

Metadata reads that bypassed the cache because they exceed MetadataCacheConfig::max_entry_bytes (or the whole budget).

These are counted apart from misses rather than folded into them: the cache was never offered the read, so charging it as a miss would report a failure at work it could not have done. They still show up in reads.

pub const fn evictions(&self) -> u64

Entries dropped to stay inside MetadataCacheConfig::max_bytes.

pub const fn invalidations(&self) -> u64

Entries dropped because an in-place write overlapped them.

Only a read-write session invalidates; this stays zero on a read-only open. Invalidations approaching misses mean the session is rewriting the metadata it is caching, and a larger budget will not change that.

pub const fn entries(&self) -> usize

Entries currently held.

Against bytes this is the mean entry size, which is what says whether a few large reads are spending the budget; pair it with oversize_reads to see the ones already refused.

pub const fn bytes(&self) -> usize

Bytes currently held, to compare against MetadataCacheConfig::max_bytes.

pub const fn reads(&self) -> u64

Every metadata read through this source: hits, misses, and reads too large to admit.

The last of those three is not in hit_rate’s denominator, so hits() / reads() is a different figure and a lower one.

pub fn hit_rate(&self) -> Option<f64>

The fraction of eligible metadata reads served from the cache, or None before any eligible read has happened.

None rather than C’s 0.0, which H5Fget_mdc_hit_rate also returns for a cache that has missed every access: the two mean opposite things to a caller deciding whether to raise the budget, and only one of them is a reason to.

Trait Implementations

impl Clone for MetadataCacheStats

fn clone(&self) -> MetadataCacheStats

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for MetadataCacheStats

impl Debug for MetadataCacheStats

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

Formats the value using the given formatter.

impl Default for MetadataCacheStats

fn default() -> MetadataCacheStats

Returns the “default value” for a type.

impl Eq for MetadataCacheStats

impl PartialEq for MetadataCacheStats

fn eq(&self, other: &MetadataCacheStats) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for MetadataCacheStats