Crate cachelito_core 

Cachelito Core

Core traits and utilities for the Cachelito caching library.

This module provides the fundamental building blocks for cache key generation, thread-local cache management, global cache management, eviction policies, invalidation strategies, and memory management.

Features

• Cache Key Generation: Flexible traits for custom or default cache keys
• Thread-Local Storage: Safe, lock-free caching using thread_local!
• Global Cache: Thread-safe cache shared across all threads using parking_lot::RwLock
• Async Cache: Lock-free async cache using DashMap for concurrent async operations
• Eviction Policies: Support for FIFO, LRU (default), LFU, ARC, Random, and TLRU
  • FIFO: First In, First Out - simple and predictable
  • LRU: Least Recently Used - evicts least recently accessed entries
  • LFU: Least Frequently Used - evicts least frequently accessed entries
  • ARC: Adaptive Replacement Cache - self-tuning policy combining recency and frequency
  • Random: Random replacement - O(1) eviction with minimal overhead
  • TLRU: Time-aware LRU - combines recency, frequency, and time-based expiration
    • Customizable with frequency_weight parameter to control recency vs frequency balance
    • Formula: score = frequency^weight × position × age_factor
    • frequency_weight < 1.0: Emphasize recency (good for time-sensitive data)
    • frequency_weight > 1.0: Emphasize frequency (good for popular content)
• Cache Limits: Control cache size with entry count limits (limit) or memory limits (max_memory)
• Memory Estimation: MemoryEstimator trait for accurate memory usage tracking
• TTL Support: Time-to-live expiration for automatic cache invalidation
• Result-Aware Caching: Smart handling of Result<T, E> types
• Smart Invalidation: Tag-based, event-driven, and dependency-based cache invalidation
• Conditional Invalidation: Runtime invalidation with custom check functions
• Statistics Tracking: Optional hit/miss rate monitoring (requires stats feature)

Module Organization

The library is organized into focused modules:

• [cache_entry] - Entry wrapper with timestamp and frequency tracking for TTL and LFU support
• [eviction_policy] - Eviction strategies: FIFO, LRU, LFU, ARC, and Random
• [keys] - Cache key generation traits and implementations
• [thread_local_cache] - Thread-local caching with zero synchronization overhead
• [global_cache] - Thread-safe global cache with parking_lot::RwLock for concurrent reads
• [async_global_cache] - Lock-free async cache using DashMap
• [memory_estimator] - Trait for estimating memory usage of cached values
• invalidation - Cache invalidation registry and strategies
• utils - Common utility functions for cache operations
• [stats] - Cache statistics tracking (optional, requires stats feature)
• stats_registry - Global statistics registry for querying cache metrics

Invalidation Strategies

The invalidation module provides multiple strategies for cache invalidation:

• Tag-based: invalidate_by_tag("user_data") - Invalidate all caches with a specific tag
• Event-driven: invalidate_by_event("user_updated") - Invalidate based on application events
• Dependency-based: invalidate_by_dependency("get_user") - Cascade invalidation to dependent caches
• Manual: invalidate_cache("cache_name") - Direct cache invalidation
• Conditional: invalidate_with("cache_name", |key| predicate) - Selective invalidation with custom logic
• Global conditional: invalidate_all_with(|cache_name, key| predicate) - Apply check function across all caches

Memory Management

Cachelito supports both entry-count and memory-based limits:

• Entry limit: limit = 1000 - Maximum number of entries
• Memory limit: max_memory = "100MB" - Maximum memory usage
• Custom estimators: Implement MemoryEstimator for user-defined types

Statistics (Optional)

When compiled with the stats feature, cachelito tracks cache performance:

• Hit/miss counts
• Hit rate percentage
• Total access count
• Per-cache statistics via stats_registry::get("cache_name")

Re-exports

pub use invalidation::invalidate_all_with;

pub use invalidation::invalidate_by_dependency;

pub use invalidation::invalidate_by_event;

pub use invalidation::invalidate_by_tag;

pub use invalidation::invalidate_cache;

pub use invalidation::invalidate_with;

pub use invalidation::InvalidationMetadata;

pub use invalidation::InvalidationRegistry;

pub use invalidation::InvalidationStrategy;

Modules

invalidation

Cache Invalidation

stats_registry

utils

Structs

AsyncGlobalCache

A thread-safe async global cache with configurable eviction policies and TTL support.

CacheEntry

Internal wrapper that tracks when a value was inserted into the cache. Used for TTL expiration support.

CacheStats

Cache statistics for monitoring hit/miss rates and performance.

GlobalCache

A thread-safe global cache that can be shared across multiple threads.

ThreadLocalCache

Core cache abstraction that stores values in a thread-local HashMap with configurable limits.

Enums

CacheScope

Cache scope: thread-local or global

EvictionPolicy

Represents the policy used for evicting elements from a cache when it reaches its limit.

Traits

CacheableKey

Trait defining how to generate a cache key for a given type.

DefaultCacheableKey

Marker trait for types that want to use the default cache key behavior.

MemoryEstimator

Trait for estimating the memory size of cached values.