cachelito_async/
lib.rs

1//! # Cachelito Async
2//!
3//! A flexible and efficient async caching library for Rust async functions.
4//!
5//! This crate provides automatic memoization for async functions through the `#[cache_async]` macro.
6//! It uses [DashMap](https://docs.rs/dashmap) for lock-free concurrent caching, making it ideal
7//! for high-concurrency async applications.
8//!
9//! ## Features
10//!
11//! - 🚀 **Lock-free caching**: Uses DashMap for concurrent access without blocking
12//! - 🎯 **Multiple eviction policies**: FIFO, LRU, LFU, ARC, Random, and TLRU
13//! - ⏰ **TLRU with frequency_weight**: Fine-tune recency vs frequency balance (v0.15.0)
14//! - 💾 **Memory-based limits**: Control cache size by memory usage
15//! - ⏱️ **TTL support**: Automatic expiration of cached entries
16//! - 📊 **Limit control**: Set maximum cache size by entry count or memory
17//! - 🔍 **Result caching**: Only caches `Ok` values from `Result` types
18//! - 🌐 **Global cache**: Shared across all tasks and threads
19//! - ⚡ **Zero async overhead**: No `.await` needed for cache operations
20//! - 📈 **Statistics**: Track hit/miss rates via `stats_registry`
21//! - 🎛️ **Conditional caching**: Cache only valid results with `cache_if` predicates
22//! - 🔥 **Smart invalidation**: Tag-based, event-driven, and conditional invalidation
23//!
24//! ## Quick Start
25//!
26//! Add this to your `Cargo.toml`:
27//!
28//! ```toml
29//! [dependencies]
30//! cachelito-async = "0.1.0"
31//! tokio = { version = "1", features = ["full"] }
32//! ```
33//!
34//! ## Examples
35//!
36//! ### Basic Usage
37//!
38//! ```rust,ignore
39//! use cachelito_async::cache_async;
40//! use std::time::Duration;
41//!
42//! #[cache_async]
43//! async fn expensive_operation(x: u32) -> u32 {
44//!     tokio::time::sleep(Duration::from_secs(1)).await;
45//!     x * 2
46//! }
47//!
48//! #[tokio::main]
49//! async fn main() {
50//!     // First call: sleeps for 1 second
51//!     let result = expensive_operation(5).await;
52//!     
53//!     // Second call: returns immediately from cache
54//!     let result = expensive_operation(5).await;
55//! }
56//! ```
57//!
58//! ### With Cache Limit and LRU Policy
59//!
60//! ```rust,ignore
61//! use cachelito_async::cache_async;
62//!
63//! #[cache_async(limit = 100, policy = "lru")]
64//! async fn fetch_user(id: u64) -> User {
65//!     // Only 100 users cached at a time
66//!     // Least recently used entries evicted first
67//!     database::fetch_user(id).await
68//! }
69//! ```
70//!
71//! ### With TTL (Time To Live)
72//!
73//! ```rust,ignore
74//! use cachelito_async::cache_async;
75//!
76//! #[cache_async(ttl = 60)]
77//! async fn fetch_weather(city: String) -> Weather {
78//!     // Cache expires after 60 seconds
79//!     api::get_weather(&city).await
80//! }
81//! ```
82//!
83//! ### Result Caching (Only Ok Values)
84//!
85//! ```rust,ignore
86//! use cachelito_async::cache_async;
87//!
88//! #[cache_async(limit = 50)]
89//! async fn api_call(endpoint: String) -> Result<Response, Error> {
90//!     // Only successful responses are cached
91//!     // Errors are not cached and always re-executed
92//!     make_request(&endpoint).await
93//! }
94//! ```
95//!
96//! ## Macro Parameters
97//!
98//! - `limit`: Maximum number of entries (default: unlimited)
99//! - `policy`: Eviction policy - `"fifo"`, `"lru"`, `"lfu"`, `"arc"`, `"random"`, or `"tlru"` (default: `"fifo"`)
100//! - `ttl`: Time-to-live in seconds (default: none)
101//! - `frequency_weight`: Weight factor for frequency in TLRU policy (default: 1.0)
102//! - `name`: Custom cache identifier (default: function name)
103//! - `max_memory`: Maximum memory usage (e.g., "100MB", default: none)
104//! - `tags`: Tags for group invalidation (default: none)
105//! - `events`: Events that trigger invalidation (default: none)
106//! - `dependencies`: Cache dependencies (default: none)
107//! - `invalidate_on`: Function to check if entry should be invalidated (default: none)
108//! - `cache_if`: Function to determine if result should be cached (default: none)
109//!
110//! ## Performance
111//!
112//! - Uses DashMap for lock-free concurrent access
113//! - No `.await` overhead for cache operations
114//! - Minimal memory footprint with configurable limits
115//! - O(1) cache lookups and insertions
116//!
117//! ## Thread Safety
118//!
119//! All caches are thread-safe and can be safely used across multiple tasks and threads.
120//! The underlying DashMap provides excellent concurrent performance without traditional locks.
121//!
122
123// Re-export the macro
124pub use cachelito_async_macros::cache_async;
125
126// Re-export stats functionality from cachelito-core
127pub use cachelito_core::{stats_registry, CacheStats};
128
129// Re-export common dependencies that users might need
130pub use dashmap;
131pub use parking_lot;
132
133/// Prelude module for convenient imports
134pub mod prelude {
135    pub use crate::cache_async;
136    pub use crate::stats_registry;
137    pub use crate::CacheStats;
138}
cachelito_async/lib.rs

cachelito_async/
lib.rs
