The procedural macros (#[cached], #[once], #[concurrent_cached]) offer a number of features, including async support. See the macros module for more samples, and the examples directory for runnable snippets.

Any custom cache that implements cached::Cached can be used with the #[cached]/#[once] macros in place of the built-ins (cached::CachedGetOrSetAsync additionally memoizes an async closure over such a store). Any custom cache that implements cached::ConcurrentCached/cached::ConcurrentCachedAsync can be used with the #[concurrent_cached] macro.

Macro quick reference

| Use case | Annotated signature | |---|---| | #[cached] | | | Unbounded memoize (default; concurrent misses each compute independently) | #[cached] fn fib(n: u64) -> u64 | | Unbounded memoize, explicit no-sync (same as default) | #[cached(sync_writes = false)] fn fib(n: u64) -> u64 | | LRU-bounded — evict past N entries | #[cached(maxsize = 1000)] fn lookup(id: u32) -> Row | | TTL — expire results after N whole seconds | #[cached(ttl_secs = 60)] fn config() -> Config | | TTL as a Duration expression (inlined verbatim, so Duration must be in scope; see note below) | #[cached(ttl = "Duration::from_secs(60)")] fn config() -> Config | | TTL in milliseconds (sub-second capable; Redis honors millisecond TTL via PSETEX/PEXPIRE) | #[cached(ttl_millis = 500)] fn poll(id: u64) -> Status | | LRU + TTL | #[cached(maxsize = 500, ttlsecs = 300)] fn search(q: String) -> Vec<Hit> | | Don't cache None returns (implicit for Option<T>) | #[cached] fn find(id: u64) -> Option<User> | | Don't cache Err returns (implicit for Result<T, E>) | #[cached] fn load(id: u64) -> Result<Data, E> | | Force-cache None returns | #[cached(cache_none = true)] fn find(id: u64) -> Option<User> | | Force-cache Err returns | #[cached(cache_err = true)] fn load(id: u64) -> Result<Data, E> | | Serve stale value when function returns Err | #[cached(resultfallback = true, ttlsecs = 60)] fn fetch(id: u64) -> Result<Data, E> | | Per-value / dynamic per-entry TTL (value carries its own expiry) | #[cached(expires = true)] fn token(scope: String) -> Token | | Deduplicate concurrent first calls per key (opt-in; do not use on recursive functions) | #[cached(ttlsecs = 30, syncwrites = "by_key")] fn expensive(id: u64) -> Payload | | Recompute when an expression over the args is true | #[cached(force_refresh = { id == 0 })] fn fetch(id: u64) -> Data | | Force-refresh via a dedicated flag (exclude it from the key) | #[cached(key = "u64", convert = { id }, forcerefresh = { refresh })] fn fetch(id: u64, refresh: bool) -> Data { let = refresh; … } — the generated guard reads refresh to decide whether to bypass the cache; the function body still receives refresh as a normal parameter, so if your body does not otherwise use it, add let = refresh; (or #[allow(unusedvariables)]) to silence the unused-variable warning | | Cache a method inside an impl block (one cache shared across all instances) | #[cached(in_impl = true)] fn load(&self, id: u64) -> Data | | Control visibility of generated nocache / primecache companions | #[cached(companions_vis = "pub(crate)")] pub fn compute(x: u64) -> u64 | | Async | #[cached(max_size = 100)] async fn remote(id: u64) -> Data | | #[once] | | | Compute and cache a global value forever | #[once] fn app_config() -> Config | | Refresh a global value periodically | #[once(ttlsecs = 300, syncwrites = true)] fn pubkey() -> Key | | TTL in milliseconds (sub-second capable) | #[once(ttl_millis = 500)] fn pubkey() -> Key | | Optional global — skip caching if None (implicit) | #[once] fn feature_flag() -> Option<Flag> | | Recompute when an expression is true | #[once(force_refresh = { flag })] fn config(flag: bool) -> Config | | Cache a method inside an impl block (one value shared across all instances) | #[once(in_impl = true)] fn config(&self) -> Config | | #[concurrent_cached] | | | Thread-safe sharded memoize (no global lock per call) | #[concurrent_cached] fn compute(x: u64) -> u64 | | Sharded with LRU | #[concurrentcached(maxsize = 1_000)] fn lookup(id: u64) -> Row | | Sharded with TTL | #[concurrentcached(ttlsecs = 60)] fn fetch(url: String) -> Body | | Sharded LRU + TTL with custom shard count | #[concurrentcached(maxsize = 1000, ttlsecs = 60, shards = 32)] fn query(id: u64) -> Row | | TTL in milliseconds (sub-second; Redis honors millisecond TTL via PSETEX/PEXPIRE) | #[concurrentcached(ttlmillis = 500)] fn poll(id: u64) -> Status | | Per-value expiry, thread-safe | #[concurrent_cached(expires = true)] fn session(id: u32) -> Token | | Per-value expiry with LRU bound | #[concurrentcached(expires = true, maxsize = 1_000)] fn session(id: u32) -> Token | | Cache only successful results (implicit for Result<T, E>) | #[concurrent_cached] fn load(id: u64) -> Result<Row, DbError> | | Don't cache None returns (implicit for Option<T>) | #[concurrent_cached] fn find(id: u64) -> Option<Row> | | Serve stale value when function returns Err | #[concurrentcached(resultfallback = true, ttl_secs = 60)] fn fetch(id: u64) -> Result<Data, E> | | Recompute when an expression over the args is true | #[concurrentcached(forcerefresh = { id == 0 })] fn fetch(id: u64) -> Data | | Force-refresh via a dedicated flag (exclude it from the key) | #[concurrentcached(key = "u64", convert = { id }, forcerefresh = { refresh })] fn fetch(id: u64, refresh: bool) -> Data { let = refresh; … } — the generated guard reads refresh to decide whether to bypass the cache; the body still receives it as a normal parameter, so add let = refresh; (or #[allow(unused_variables)]) if your body does not otherwise use it | | Cache a method inside an impl block (one cache shared across all instances) | #[concurrentcached(inimpl = true)] fn load(&self, id: u64) -> Data | | Persist results to disk (with maperror; or omit when E: From<RedbCacheError>) | #[concurrentcached(disk = true, map_error = \|e\| MyErr(e))] fn crunch(n: u64) -> Result<Data, MyErr> | | Redis-backed async cache (quoted or unquoted create/maperror) | #[concurrentcached(ty = "AsyncRedisCache<u64, String>", create = { ... }, map_error = \|e\| MyErr(e))] async fn api(id: u64) -> Result<Resp, MyErr> |

On #[cached] and #[concurrentcached], the LRU bound is set with maxsize = N (mirroring the maxsize builder/constructor methods on the stores). The size = N spelling — a deprecated alias in 2.x — has been removed; only maxsize = N is accepted.

The ttl attribute accepts a Duration expression as a quoted string: ttl = "Duration::fromsecs(60)". The expression is inlined verbatim, so Duration must be in scope at the call site (e.g. use cached::time::Duration;); the ttlsecs / ttlmillis forms need no import. For whole seconds, the shorter ttlsecs = N form is preferred. ttlmillis = N sets a TTL in milliseconds. The three attributes ttl, ttlsecs, and ttlmillis are mutually exclusive; using more than one is a compile error. All three are mutually exclusive with expires. Sub-second precision for ttlmillis is honored by the in-memory, disk (redb), and Redis stores; Redis applies the TTL with millisecond precision via PSETEX/PEXPIRE.

For the default in-memory sharded stores, #[concurrent_cached] accepts any return type — plain values, Option<T>, or Result<T, E>. Plain values are always cached as-is. Option<T> returns skip caching None by default; use cachenone = true to also cache None values. Result<T, E> only caches Ok values; Err is returned without being stored. Use cacheerr = true to also cache Err values. The macro detects Result<T, E> by matching the exact identifier Result (including fully-qualified paths such as std::result::Result<T, E>). Type aliases are not resolved at macro-expansion time, so any alias — even one whose name ends with Result (e.g. type MyResult<T> = Result<T, E>) — is treated as a plain value and its Err variant is cached. Use Result<T, E> directly when you need Ok-only caching behavior. The same applies to Option<T> detection: a type alias such as type MaybeRow<T> = Option<T> is treated as a plain value and its None variant is cached. Use Option<T> directly when you need None-skipping behavior. On the default in-memory path, do not specify map_error -- the sharded stores are infallible and supplying it is a compile error. For disk and redis stores, Result<T, E> is required. maperror is optional: when supplied it converts the store error into your E; when omitted the generated code uses .maperr(Into::into)?, so E must implement From<RedbCacheError> (disk) or From<RedisCacheError> (Redis). Both quoted-string and unquoted forms are accepted: maperror = |e| MyErr(e) and maperror = "|e| MyErr(e)" are equivalent.

Store comparison

| Store | Eviction policy | Size limit | TTL | Refresh on hit | on_evict | Concurrent | Async | |---|---|---|---|---|---|---|---| | UnboundCache | None (unbounded) | No | No | N/A | On explicit remove | No | Yes | | LruCache | LRU | Yes | No | N/A | Yes | No | Yes | | TtlCache | TTL (insert time) | No | Global | Optional | Yes | No | Yes | | LruTtlCache | LRU + TTL | Yes | Global | Optional | Yes | No | Yes | | TtlSortedCache | TTL (expiry-ordered) | Optional | Global | No | Yes | No | Yes | | ExpiringLruCache | LRU + value-defined | Yes | Per-value | N/A | Yes | No | Yes | | ExpiringCache | Value-defined | No | Per-value | N/A | Yes | No | Yes | | ShardedUnboundCache | None (unbounded) | No | No | N/A | On explicit remove | Yes (Arc) | Yes | | ShardedLruCache | LRU | Yes | No | N/A | Yes | Yes (Arc) | Yes | | ShardedTtlCache | TTL (insert time) | No | Global | Optional | Yes | Yes (Arc) | Yes | | ShardedLruTtlCache | LRU + TTL | Yes | Global | Optional | Yes (†) | Yes (Arc) | Yes | | ShardedExpiringCache | Value-defined | No | Per-value | N/A | Yes | Yes (Arc) | Yes | | ShardedExpiringLruCache | LRU + value-defined | Yes | Per-value | N/A | Yes | Yes (Arc) | Yes |

"On explicit remove" — onevict fires only on cacheremove; there is no capacity eviction or TTL expiry trigger for these stores.

† ShardedLruTtlCacheBuilder::on_evict requires K: 'static + V: 'static; see the builder docs for details.

TtlCache/LruTtlCache/TtlSortedCache/ShardedTtlCache/ShardedLruTtlCache require the time_stores feature.

ShardedUnboundCache and its variants are partitioned across power-of-two shards (default: availableparallelism() × 4, clamped to 8–1024; the 8–1024 clamp applies only to this computed default — an explicit shards = N is rounded up to a power of two but never clamped) each protected by a parkinglot::RwLock. Shard structs are padded to 128-byte alignment (covering Intel adjacent-line prefetch and Apple Silicon 128-byte L1 lines) to eliminate false sharing; on a 64-shard deployment this amounts to ~8 KB of padding overhead per cache array. The outer type is an Arc — cloning is a reference share, not a deep copy (use deepclone() for an independent copy; note that deepclone() is an inherent method on each concrete sharded type, not part of any trait). They implement ConcurrentCached/ConcurrentCachedAsync and are the default store selected by #[concurrent_cached]. For sharded LRU variants, eviction is enforced independently per shard. maxsize = N is divided across shards with ceiling division. Use the builder's pershardmaxsize method for an exact per-shard cap (builder-only; #[concurrentcached] does not expose a pershardmaxsize attribute — use shards to control parallelism and maxsize for total capacity). Capacity Fragmentation Warning: To protect against premature evictions due to hash collisions in extremely small caches (where a shard capacity could drop to 1-2 entries), when sharding is active (shards > 1) we enforce a minimum capacity of 16 entries per shard (e.g., minimum total capacity of 128 on a single-core machine with 8 shards, or 256 on a 4-core machine with 16 shards). If you require smaller, strict limits under low capacities, configure shards = 1 or specify pershardmaxsize directly (builder-only; not available via #[concurrent_cached]). Because LRU caches require updating access recency, ShardedLruCache, ShardedLruTtlCache, and ShardedExpiringLruCache must acquire an exclusive write lock on accessed shards during read hits, which can lead to contention under highly concurrent read-heavy workloads. Unbounded ShardedUnboundCache, time-only ShardedTtlCache (when refreshonhit is disabled -- enabling it promotes read hits to exclusive write locks), and expiring ShardedExpiringCache require only a shared read lock on read hits, avoiding this contention. To mitigate contention on LRU variants, consider increasing the number of shards to distribute writes. Note: this write-lock-on-read behavior is a known limitation of the strict-LRU sharded stores. A future read-optimized variant that relaxes strict recency ordering will ship as a separate store type; the existing stores will not change semantics.

Base types: Each sharded store has a corresponding Base generic (ShardedUnboundCacheBase<K, V, H>, ShardedLruCacheBase<K, V, H>, etc.) parameterized on a custom [ShardHasher]. The named aliases (ShardedUnboundCache, ShardedLruCache, …) use the default hasher and are what most users should reach for. Use the Base types only when implementing a custom ShardHasher for non-standard shard routing. Construct a custom-hasher cache through the alias builder and its hasher method: ShardedLruCache::builder().hasher(myhasher) switches the builder's hasher type and build yields a Base<K, V, H> over myhasher. new/builder are defined only on the default-hasher alias, so a custom hasher is always introduced through hasher, never a *Base::<, , H> turbofish (which would otherwise silently drop the hasher).

Behavioral guarantees

• Non-sharded in-memory stores (UnboundCache, LruCache, TtlCache, etc.) are not internally

• CachedExt::get (and the Cached::cache_get required method it wraps) requires mutable access

• cacheget/cacheset shapes differ per family, by design. Single-owner: Cached::cache_get

• The inherent-method asymmetry between the two families is deliberate. On a sharded store the

• len / size vs iter vs evict contract for timed and expiring stores:

• Expired values can remain allocated until a mutating operation, evict, or

• cacheremove fires the onevict callback (if set) and counts as an eviction for

• cacheclear() is fast and side-effect-free: it does not fire onevict and does

• Bounded caches enforce capacity on insertion. Time-bounded caches enforce freshness on lookup.
• Redis and disk stores serialize values and return owned values. Non-sharded in-memory stores

• Macro-generated #[cached] / #[once] cache statics use RwLock by default. Named cache

• CachedPeek provides non-mutating lookups that do not update recency, refresh TTLs, or record

• Sharded stores implement ConcurrentCached/ConcurrentCachedAsync instead of

Per-Value Expiry via the Expires Trait

While standard timed stores (TtlCache, LruTtlCache, TtlSortedCache) enforce a single, global Time-To-Live (TTL) duration applied to all entries in the cache, [ExpiringLruCache] and [ExpiringCache] let each individual value determine its own expiration. This is accomplished by storing values that implement the [Expires] trait.

This approach is highly useful when caching payloads like OAuth tokens, HTTP responses with varying Cache-Control headers, or database records that contain their own absolute expiration timestamps.

use cached::macros::cached;
use cached::Expires;
use cached::time::{Duration, Instant};
#[derive(Clone)] struct Token { value: String, expires_at: Instant }
impl Expires for Token {     fn isexpired(&self) -> bool { Instant::now() >= self.expiresat } }
// ttl_secs is a runtime argument — each user's token expires on its own schedule. #[cached(expires = true, key = "u64", convert = "{ user_id }")] fn fetchtoken(userid: u64, ttl_secs: u64) -> Token {     Token {         value: format!("token-{user_id}"),         expiresat: Instant::now() + Duration::fromsecs(ttl_secs),     } }

For concurrent (multi-thread, no external lock) use, the sharded equivalents [ShardedExpiringCache] and [ShardedExpiringLruCache] provide the same per-value expiry with internally-synchronized sharded storage. Use #[concurrent_cached(expires = true)] to select them automatically.

Memory note: ExpiringCache and ShardedExpiringCache are unbounded and only remove

expired entries when the same key is accessed again. CachedIter::iter() (implemented on the

non-sharded ExpiringCache / ExpiringLruCache only, not on the sharded variants) filters

expired entries from the iterator but does not remove them from the map. For high-cardinality workloads,

call evict() periodically — on the single-owner ExpiringCache via [CacheEvict]

(use cached::CacheEvict;, &mut self), and on the sharded ShardedExpiringCache via

[ConcurrentCacheEvict] (use cached::ConcurrentCacheEvict;, &self) or its inherent

evict(&self) method; note that evict() on sharded TTL and expiring stores requires

K: Clone. Alternatively, prefer ExpiringLruCache / ShardedExpiringLruCache with a

max_size bound.

use cached::{CachedExt, Expires, ExpiringCache, ExpiringLruCache};
use cached::time::{Duration, Instant};
#[derive(Clone)] struct Response {     payload: String,     expires_at: Instant, }
impl Expires for Response {     fn is_expired(&self) -> bool {         Instant::now() >= self.expires_at     } }
let now = Instant::now();
// ExpiringCache — unbounded, default for #[cached(expires = true)] let mut cache = ExpiringCache::builder().build().unwrap(); cache.set("key1", Response {     payload: "a".to_string(),     expiresat: now + Duration::fromsecs(1), }); cache.set("key2", Response {     payload: "b".to_string(),     expiresat: now + Duration::fromsecs(3600), });
// ExpiringLruCache — LRU-bounded, used with #[cached(expires = true, max_size = N)] let mut lru = ExpiringLruCache::builder().max_size(10).build().unwrap(); lru.set("key1", Response {     payload: "a".to_string(),     expiresat: now + Duration::fromsecs(1), });

The basic usage looks like:

,no_run,ignore
use cached::macros::cached;
/// Defines a function named fib that uses a cache implicitly named FIB. /// By default, the cache will be the function's name in all caps. /// The following line is equivalent to #[cached(name = "FIB")] #[cached] fn fib(n: u64) -> u64 {     if n == 0 || n == 1 { return n }     fib(n-1) + fib(n-2) } 
pub fn main() { }

,no_run,ignore
use std::thread::sleep;
use cached::time::Duration;
use cached::macros::cached;
use cached::LruCache;
/// Use an explicit cache-type with a custom creation block and custom cache-key generating block #[cached(     ty = "LruCache<String, usize>",     create = "{ LruCache::builder().max_size(100).build().unwrap() }",     convert = r#"{ format!("{}{}", a, b) }"# )] fn keyed(a: &str, b: &str) -> usize {     let size = a.len() + b.len();     sleep(Duration::new(size as u64, 0));     size } 
pub fn main() { }

,no_run,ignore
use cached::macros::once;
/// Only cache the initial function call. /// Function will be re-executed after the cache /// expires (according to ttl_secs). /// When no (or expired) cache, concurrent calls /// will synchronize (sync_writes) so the function /// is only executed once. #[once(ttlsecs=10, syncwrites = true)] fn keyed(a: String) -> Option<usize> {     if a == "a" {         Some(a.len())     } else {         None     } } 
pub fn main() { }

use cached::macros::cached;
/// Cannot use syncwrites and resultfallback together #[cached(     ttl_secs = 1,     sync_writes = "default",     result_fallback = true )] fn doesnt_compile() -> Result<String, ()> {     Ok("a".to_string()) }

cachegetorsetwith returns a shared reference (&V); binding it as &mut V no longer compiles. Use cachegetorsetwith_mut when you need a mutable reference.

use cached::{Cached, UnboundCache};
let mut cache: UnboundCache<u32, u32> = UnboundCache::builder().build().unwrap(); let : &mut u32 = cache.cachegetorset_with(1, || 2);

,no_run,ignore
use cached::macros::concurrent_cached;
use cached::AsyncRedisCache;
use cached::time::Duration;
use thiserror::Error;
#[derive(Error, Debug, PartialEq, Clone)] enum ExampleError {     #[error("error with redis cache {0}")]     RedisError(String), }
/// Cache the results of an async function in redis. Redis keys are laid out as /// {namespace}:{prefix}:{key}, where namespace defaults to cached-redis-store: /// and prefix is required (here cachedredisprefix). The prefix is what scopes /// cache_clear to this logical cache, so give each cache a distinct prefix. /// Redis and disk stores require Result&lt;T, E&gt;; supply a map_error closure /// to convert store errors into your error type. #[concurrent_cached(     map_error = r##"|e| ExampleError::RedisError(format!("{:?}", e))"##,     ty = "AsyncRedisCache<u64, String>",     create = r##" {         AsyncRedisCache::builder("cachedredisprefix")             .ttl(Duration::from_secs(1))             .refreshonhit(true)             .build()             .await             .expect("error building example redis cache")     } "## )] async fn asynccachedsleep_secs(secs: u64) -> Result<String, ExampleError> {     std::thread::sleep(cached::time::Duration::from_secs(secs));     Ok(secs.to_string()) }

,no_run,ignore
use cached::macros::concurrent_cached;
use cached::RedbCache;
use thiserror::Error;
#[derive(Error, Debug, PartialEq, Clone)] enum ExampleError {     #[error("error with disk cache {0}")]     DiskError(String), }
/// Cache the results of a function on disk. /// Cache files will be stored under the system cache dir /// unless otherwise specified with disk_dir or the create argument. /// Disk stores require Result&lt;T, E&gt;; supply a map_error closure /// to convert store errors into your error type. #[concurrent_cached(     map_error = r##"|e| ExampleError::DiskError(format!("{:?}", e))"##,     disk = true )] fn cachedsleepsecs(secs: u64) -> Result<String, ExampleError> {     std::thread::sleep(cached::time::Duration::from_secs(secs));     Ok(secs.to_string()) }

,no_run,ignore
use cached::macros::concurrent_cached;
/// Memoize with the default in-memory sharded store — no map_error, ty, /// or create needed. Add max_size for LRU eviction or ttl for time-based /// expiry (requires the time_stores feature). /// /// #[concurrentcached] does not support syncwrites. /// For Option<T> returns, None is skipped by default (use cache_none = true to cache it). /// For Result<T, E> returns, only Ok values are cached by default (use cache_err = true /// to also cache Err). resultfallback = true is supported (requires ttlsecs, ttl_millis, or ttl = "<Duration expr>"): on an Err /// return, the last cached Ok value for the same key is returned instead. The stale value /// is held in the primary cache slot and re-cached with a fresh TTL window on Err; no /// secondary store is created. #[concurrent_cached] fn slow_double(x: u64) -> u64 {     std::thread::sleep(cached::time::Duration::from_millis(10));     x * 2 }
/// LRU capacity of 1 000 entries spread across shards. #[concurrentcached(maxsize = 1000)] fn slow_triple(x: u64) -> u64 {     x * 3 }
/// Only cache successful lookups — Err is returned but not stored. #[concurrent_cached] fn load_user(id: u64) -> Result<String, std::io::Error> {     Ok(format!("user_{id}")) }

Functions defined via macros will have their results cached using the function's arguments as a key, or a convert expression specified on the macro.

When a macro-defined function is called, the function's cache is first checked for an already computed (and still valid) value before evaluating the function body.

Due to the requirements of storing arguments and return values in a global cache:

• Function return types:

• Function arguments:

• Arguments and return values will be cloned in the process of insertion and retrieval. For Redis and

• Macro-defined functions should not be used to produce side-effectual results!
• Macro-defined functions live at module scope by default (the macro expands to a static plus

• Macro-defined methods may take a self receiver only when in_impl = true; self is excluded

• Macro-defined functions can be generic over type parameters only when a key + convert is

License: MIT