Struct Cache 

pub struct Cache<I, P> { /* private fields */ }

Available on crate features alloc or no-atomic or std only.

Passive record cache.

Implementations

impl<I, P> Cache<I, P>

where I: Instant, P: Pool<CacheEntry<I>>,

pub fn new() -> Self

Empty cache with the default maximum entry cap (1024).

pub fn with_max_entries(max: usize) -> Self

Empty cache with a custom maximum entry cap.

When try_insert is called and the number of stored entries has reached max, the soonest-expiring entry is evicted proactively before the new entry is inserted. This bounds memory usage even when the backing Pool grows without error (e.g. slab::Slab).

pub const fn max_entries(&self) -> usize

The configured maximum number of entries.

pub fn len(&self) -> usize

The current number of cached entries.

pub fn is_empty(&self) -> bool

Whether the cache is empty.

pub fn try_insert( &mut self, name: Name, rtype: ResourceType, rclass: ResourceClass, rdata: impl Into<RdataBuf>, ttl: Duration, now: I, cache_flush: bool, ) -> Result<Option<usize>, P::Error>

Insert (or update / remove) a record observation.

Semantics:

• If ttl == 0, treat as “record going away” (RFC 6762 §10.1): clamp the matching (name, rtype, rclass, rdata) entry’s expires_at to one second out (rescue window, never extending a sooner expiry) and return Ok(None) — NOT an immediate delete.
• If cache_flush == true (RFC 6762 §10.2), DEFER eviction by 1 second: clamp the expires_at of every existing sibling matching (name, rtype, rclass) (and not the new rdata) to min(current, now + 1s). This gives a refresh burst time to re-announce missing siblings before they disappear from the cache.
• If a matching (name, rtype, rclass, rdata) entry already exists, refresh its expiration in place and return Ok(Some(key)) (deduplication).
• Otherwise insert a new entry. If the pool is full, evict the soonest-expiring entry first (best-effort) then retry. If the retry still fails the error is propagated.

cache identity is (name, rtype, rclass, rdata). A non-IN class record cannot dedupe with, evict, or count as an IN record.

pub fn sweep_expired(&mut self, now: I) -> usize

Sweep expired entries, returning how many were removed.

pub fn next_expiration(&self) -> Option<I>

Next deadline (soonest expiration), if any.

pub fn contains( &self, name: &Name, rtype: ResourceType, rclass: ResourceClass, ) -> bool

Look up whether the cache contains a record matching (name, rtype, rclass). class is part of the cache key.

pub fn count_matching( &self, name: &Name, rtype: ResourceType, rclass: ResourceClass, ) -> usize

Count the number of cached entries matching (name, rtype, rclass).

Multiple distinct records can share (name, rtype, rclass) (e.g. a multi-homed host with several A records), so a single contains check cannot tell you whether the full RRSet landed. Use this for RRSet-coherency checks.

Trait Implementations

impl<I, P> Default for Cache<I, P>

where I: Instant, P: Pool<CacheEntry<I>>,

fn default() -> Self

Returns the “default value” for a type.