Struct NegativeCache 

pub struct NegativeCache { /* private fields */ }

Thread-safe negative cache for filesystem lookups.

Caches paths that are known to not exist, avoiding repeated system calls for non-existent files. Uses lock-free concurrent access via DashMap.

When adaptive TTL is configured, different paths receive different cache durations based on pattern matching. For example, lookups inside /node_modules/ get a 30s TTL while source files default to 5s.

Example

use std::time::Duration;
use std::path::PathBuf;
use arcbox_fs::cache::{NegativeCache, NegativeCacheConfig};

let config = NegativeCacheConfig {
    max_entries: 1000,
    timeout: Duration::from_millis(500),
    adaptive_ttl: None,
};
let cache = NegativeCache::new(config);

// File lookup failed, add to negative cache
cache.insert(PathBuf::from("/app/node_modules/missing-package"));

// Later lookup - returns true without syscall
assert!(cache.contains(&PathBuf::from("/app/node_modules/missing-package")));

// File created - invalidate cache
cache.invalidate(&PathBuf::from("/app/node_modules/missing-package"));
assert!(!cache.contains(&PathBuf::from("/app/node_modules/missing-package")));

Implementations

impl NegativeCache

pub fn new(config: NegativeCacheConfig) -> Self

Creates a new negative cache with the given configuration.

pub fn with_defaults() -> Self

Creates a new negative cache with default configuration (adaptive TTL enabled).

pub fn contains(&self, path: &Path) -> bool

Checks if the path is in the negative cache and not expired.

Returns true if the path was previously marked as non-existent and the cache entry has not expired.

pub fn insert(&self, path: PathBuf)

Adds a path to the negative cache.

The TTL is determined by adaptive TTL rules if configured, or by the global timeout value otherwise.

If the cache is at capacity, expired entries are evicted first.

pub fn invalidate(&self, path: &Path)

Invalidates a path in the negative cache.

This should be called when a file is created to ensure subsequent lookups don’t incorrectly return “not found” from the cache.

Also invalidates the parent directory path to handle cases where the parent’s directory listing was cached.

pub fn evict_expired(&self)

Removes all expired entries from the cache.

This is called automatically when the cache reaches capacity, but can also be called manually for maintenance.

pub fn stats(&self) -> NegativeCacheStats

Returns current cache statistics.

pub fn clear(&self)

Clears all entries from the cache.

pub fn len(&self) -> usize

Returns the current number of entries in the cache.

pub fn is_empty(&self) -> bool

Returns true if the cache is empty.

Trait Implementations

impl Debug for NegativeCache

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

Formats the value using the given formatter.