Struct EngineCache 

pub struct EngineCache { /* private fields */ }

Thread-safe cache of discovered SNMPv3 engine state.

Target addresses map to discovered identities and remote message-size limits. Trusted time is keyed separately by authoritative engine ID, so clients reaching the same engine through multiple targets converge on one high-water value. Whole-state inserts merge monotonically and cannot replace a newer trusted tuple with a stale clone.

Entry lifetime

Each target identity has a refresh timestamp. Every accepted HMAC-verified message refreshes it, including an older in-window message that does not advance trusted time. Entries older than the configured TTL (default 5 minutes) are removed by get.

Expiry prevents a shared entry from being handed indefinitely to newly constructed clients after a target is replaced. It does not silently clear an existing client’s established identity; call Client::rediscover_engine to replace it intentionally.

Actively polled authenticated targets refresh their entry on every accepted HMAC-verified response or Report, so the TTL has no effect during normal authenticated operation.

Capacity

The cache is unbounded by default. Each entry is roughly 100-150 bytes, so even 100k targets uses only ~10-15 MB. For deployments that scan very large address ranges, with_max_capacity sets a hard limit with oldest-entry eviction.

Example

use async_snmp::{Auth, AuthProtocol, Client, EngineCache};
use std::sync::Arc;

let cache = Arc::new(EngineCache::new());

let client1 = Client::builder("192.168.1.1:161",
    Auth::usm("admin").auth(AuthProtocol::Sha1, "authpass"))
    .engine_cache(cache.clone())
    .connect()
    .await?;

let client2 = Client::builder("192.168.1.2:161",
    Auth::usm("admin").auth(AuthProtocol::Sha1, "authpass"))
    .engine_cache(cache.clone())
    .connect()
    .await?;

Implementations

impl EngineCache

pub fn new() -> Self

Create a new empty engine cache with default settings.

pub fn with_max_capacity(self, max_capacity: usize) -> Self

Set a maximum capacity. When full, the oldest entry is evicted on insert.

pub fn with_ttl(self, ttl: Duration) -> Self

Set the TTL for cache entries. Entries not refreshed within this duration are removed on lookup, triggering re-discovery.

pub fn get(&self, target: &SocketAddr) -> Option<EngineState>

Get cached engine state for a target.

Returns None if the entry does not exist or has expired. Expired entries are removed from the cache.

pub fn insert(&self, target: SocketAddr, state: EngineState)

Store engine state for a target.

If a max capacity is set and the cache is full, the least recently refreshed target identity is evicted.

pub fn update_time( &self, target: &SocketAddr, response_boots: u32, response_time: u32, ) -> bool

Update time for an existing entry after authenticating a message.

The caller must have verified the message HMAC and engine identity. Returns true if the entry was updated, false if not found or not updated.

pub fn remove(&self, target: &SocketAddr) -> Option<EngineState>

Remove cached identity for a target. Shared trusted time remains while another target still maps to the same authoritative engine.

pub fn clear(&self)

Clear all cached identities and trusted time.

pub fn len(&self) -> usize

Get the number of cached target identities (including expired entries).

pub fn is_empty(&self) -> bool

Check if the cache is empty.

Trait Implementations

impl Debug for EngineCache

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

Formats the value using the given formatter.

impl Default for EngineCache

fn default() -> Self

Returns the “default value” for a type.