Struct CacheStats 

pub struct CacheStats {

    pub hits: u64,
    pub misses: u64,
    pub loads: u64,
    pub single_flight_joins: u64,
    pub stale_load_discards: u64,
    pub invalidations: u64,
    pub evictions: u64,
    pub oversize_rejections: u64,
    pub events_published: u64,
    pub event_subscriber_lagged: u64,
    pub distributed_invalidations_published: u64,
    pub distributed_invalidations_received: u64,
    pub distributed_invalidations_applied: u64,
    pub distributed_invalidation_lagged: u64,
    pub distributed_invalidation_decode_errors: u64,
    pub distributed_invalidation_publish_failures: u64,
    pub distributed_invalidation_receiver_closed: u64,
    pub consistency_wait_successes: u64,
    pub consistency_wait_timeouts: u64,
    pub consistency_degraded_reads: u64,
    pub consistency_fail_closed: u64,
}

Snapshot of lightweight cache counters.

The counters are intentionally lightweight and approximate enough for local observability. They are not intended to be a durable metrics store.

Example

use hydracache_core::CacheStats;

let stats = CacheStats::default();
assert_eq!(stats.hits, 0);
assert_eq!(stats.single_flight_joins, 0);
assert_eq!(stats.oversize_rejections, 0);
assert_eq!(stats.consistency_wait_successes, 0);
assert_eq!(stats.events_published, 0);
assert_eq!(stats.distributed_invalidations_published, 0);
assert_eq!(stats.distributed_invalidation_lagged, 0);
assert_eq!(stats.distributed_invalidation_decode_errors, 0);
assert_eq!(stats.total_requests(), 0);
assert_eq!(stats.hit_ratio(), None);

Fields

hits: u64

Successful cache lookups.

misses: u64

Cache lookups that did not return a usable value.

loads: u64

Loader closures executed by get_or_load.

single_flight_joins: u64

Calls that joined an already running single-flight load.

stale_load_discards: u64

Loader results skipped because their invalidation generation became stale.

invalidations: u64

Entries removed by invalidation APIs.

evictions: u64

Entries observed as evicted by the backend.

v0 does not wire backend eviction listeners yet, so this remains zero.

oversize_rejections: u64

Entries rejected before insertion because encoded bytes exceeded max_entry_bytes.

events_published: u64

Cache events delivered to at least one subscriber.

event_subscriber_lagged: u64

Event notifications skipped by slow subscribers.

distributed_invalidations_published: u64

Invalidation messages published to an attached bus.

distributed_invalidations_received: u64

Invalidation messages received from an attached bus.

distributed_invalidations_applied: u64

Received invalidation messages applied to the local cache.

distributed_invalidation_lagged: u64

Invalidation messages skipped because a bus receiver lagged behind.

distributed_invalidation_decode_errors: u64

Invalidation transport frames that could not be decoded.

distributed_invalidation_publish_failures: u64

Invalidation publish attempts that returned an error.

distributed_invalidation_receiver_closed: u64

Times an attached bus receiver reported that the stream closed.

consistency_wait_successes: u64

Consistency-token waits that observed the requested generation.

consistency_wait_timeouts: u64

Consistency-token waits that timed out.

consistency_degraded_reads: u64

Consistency-token reads that returned a degraded value.

consistency_fail_closed: u64

Consistency-token reads that failed closed instead of serving stale data.

Implementations

impl CacheStats

pub fn total_requests(&self) -> u64

Return the number of lookup attempts represented by this snapshot.

This is hits + misses, so it intentionally does not include loader executions, invalidations, or backend evictions.

Example

use hydracache_core::CacheStats;

let stats = CacheStats {
    hits: 3,
    misses: 1,
    ..CacheStats::default()
};

assert_eq!(stats.total_requests(), 4);

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

Return the cache hit ratio for this snapshot.

Returns None when no lookup has happened yet. Otherwise the value is hits / (hits + misses) in the 0.0..=1.0 range.

Example

use hydracache_core::CacheStats;

let stats = CacheStats {
    hits: 3,
    misses: 1,
    ..CacheStats::default()
};

assert_eq!(stats.hit_ratio(), Some(0.75));

pub fn has_single_flight_activity(&self) -> bool

Return whether at least one caller joined an existing single-flight load.

This is a compact way to check that concurrent misses were deduplicated.

pub fn has_stale_load_discards(&self) -> bool

Return whether a stale loader result was discarded after invalidation.

pub fn has_oversize_rejections(&self) -> bool

Return whether at least one encoded value was rejected before insertion.

pub fn has_event_subscriber_lag(&self) -> bool

Return whether at least one event subscriber lagged behind the event bus.

pub fn has_distributed_invalidation_activity(&self) -> bool

Return whether this cache has published or received bus invalidations.

pub fn has_distributed_invalidation_bus_issues(&self) -> bool

Return whether this cache observed invalidation bus health issues.

Trait Implementations

impl Clone for CacheStats

fn clone(&self) -> CacheStats

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for CacheStats

impl Debug for CacheStats

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

Formats the value using the given formatter.

impl Default for CacheStats

fn default() -> CacheStats

Returns the “default value” for a type.

impl Eq for CacheStats

impl PartialEq for CacheStats

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for CacheStats