Expand description
Memoize Rust functions with one attribute. In-memory, sharded, Redis, and disk caches.
use cached::macros::cached;
/// Cache up to 1,000 users for 60 seconds each.
/// `Err` results are not cached, so a failed request is retried on the next call.
#[cached(max_size = 1_000, ttl_secs = 60)]
fn get_user(id: u64) -> Result<User, ApiError> {
api::fetch_user(id) // slow network call
}
let user = get_user(1)?; // calls the API
let user = get_user(1)?; // returned from the cacheThe same attribute works on async fn (with the async feature), and #[concurrent_cached]
swaps in a sharded store, Redis, or an on-disk cache without changing the function.
[dependencies]
cached = "4"§Contents
- Memoizing functions
- Redis and disk caches
- Using cache stores directly
- Choosing a store
- Per-value expiry
- Feature flags
- Requirements
- Further reading
- Upgrading
§Memoizing functions
The macros cache a function’s return value keyed by its arguments. On each call the cache is
checked first, and the function body only runs on a miss. Each macro also generates
{fn}_no_cache (calls the body directly) and {fn}_prime_cache (recomputes and stores a fresh
value).
§The #[cached] macro
The general-purpose macro. Unbounded by default; add max_size for LRU eviction and ttl_secs
for expiry.
use cached::macros::cached;
#[cached]
fn fib(n: u64) -> u64 {
if n == 0 || n == 1 {
return n;
}
fib(n - 1) + fib(n - 2)
}
assert_eq!(fib(80), 23_416_728_348_467_685);§The #[once] macro
Caches a single value regardless of arguments, for global config or tokens that are refreshed periodically.
use cached::macros::once;
#[once(ttl_secs = 300)]
fn config() -> Config {
load_config() // re-run at most once every 5 minutes
}§The #[concurrent_cached] macro
Uses a sharded store with per-shard locks instead of one lock around the whole cache, so concurrent callers on different keys do not contend. It also backs the Redis and disk caches.
use cached::macros::concurrent_cached;
#[concurrent_cached(max_size = 10_000)]
fn lookup(id: u64) -> Row {
query(id)
}§Common attributes
| Attribute | Effect |
|---|---|
max_size = N | LRU eviction past N entries |
ttl_secs = N / ttl_millis = N | Expire entries after a fixed duration |
refresh = true | Reset an entry’s TTL on every hit |
expires = true | Each value decides its own expiry (see Per-value expiry) |
key = "Type", convert = { expr } | Build the cache key from the arguments yourself |
sync_writes = "by_key" | Concurrent first calls for the same key run the body once |
result_fallback = true | On Err, return the last cached Ok value |
name = "NAME" | Name of the generated cache static (defaults to the function name in caps) |
in_impl = true | Cache a method inside an impl block |
See the macros module for the full
attribute reference, including synchronization options and argument and return-type
requirements.
§Result and Option returns
A function returning Result<T, E> caches only Ok values, and one returning Option<T> caches
only Some. Opt back in with cache_err = true or cache_none = true. Detection matches the
literal Result / Option type names, so a type alias is cached as a plain value.
§Async functions
Enable the async feature and annotate an async fn. The feature is runtime-agnostic and does
not depend on tokio.
use cached::macros::cached;
#[cached(max_size = 100, ttl_secs = 30)]
async fn get(url: String) -> Body {
fetch(&url).await
}§Redis and disk caches
#[concurrent_cached] can store results in Redis (redis_* features) or on disk with
redb (redb_store feature). Values are serialized, so they must
implement serde::Serialize and serde::DeserializeOwned, and the function must return
Result so store errors have somewhere to go.
use cached::macros::concurrent_cached;
/// Reads the connection string from `CACHED_REDIS_CONNECTION_STRING`.
#[concurrent_cached(redis = true, ttl_secs = 300, map_error = |e| MyError(format!("{e:?}")))]
async fn report(id: u64) -> Result<String, MyError> {
fetch_report(id).await
}use cached::macros::concurrent_cached;
/// Stored under the system cache directory unless `disk_dir` is set.
#[concurrent_cached(disk = true, map_error = |e| MyError(format!("{e:?}")))]
fn thumbnail(n: u64) -> Result<String, MyError> {
Ok(render(n))
}See examples/redis-async-tokio.rs
and examples/disk.rs for
complete programs, including explicit store construction with ty and create.
§Using cache stores directly
Every store the macros use is also a plain type. Import the store and the
prelude, which brings the cache
traits into scope:
use cached::LruCache;
use cached::prelude::*;
let mut cache: LruCache<String, u32> = LruCache::new(100);
cache.set("a".to_string(), 1);
assert_eq!(cache.get("a"), Some(&1));
assert_eq!(cache.len(), 1);Single-owner stores like LruCache take &mut self and need your own lock to share across
threads. The Sharded* stores lock internally and can be shared directly:
use cached::ShardedLruCache;
let cache: ShardedLruCache<String, u32> = ShardedLruCache::new(1_000);
cache.set("a".to_string(), 1);
assert_eq!(cache.get("a"), Some(1));Builders configure TTLs, eviction callbacks, and the rest:
use cached::LruTtlCache;
use cached::time::Duration;
let cache: LruTtlCache<u64, String> = LruTtlCache::builder()
.max_size(1_000)
.ttl(Duration::from_secs(60))
.on_evict(|key, _value| println!("evicted {key}"))
.build()
.unwrap();§Choosing a store
| Need | Single-owner | Concurrent |
|---|---|---|
| Unbounded | UnboundCache | ShardedUnboundCache |
| Size limit (LRU) | LruCache | ShardedLruCache |
| Fixed TTL | TtlCache | ShardedTtlCache |
| Size limit + fixed TTL | LruTtlCache | ShardedLruTtlCache |
| Per-value expiry | ExpiringCache | ShardedExpiringCache |
| Size limit + per-value expiry | ExpiringLruCache | ShardedExpiringLruCache |
| Shared across processes | RedisCache, AsyncRedisCache | |
| Persisted to disk | RedbCache |
TtlSortedCache is a TTL
cache ordered by expiry with an optional size limit. Custom stores work with the macros by
implementing Cached (for
#[cached] / #[once]) or
ConcurrentCached (for
#[concurrent_cached]).
The stores module documents each
store’s eviction, locking, and on_evict behavior in detail.
§Per-value expiry
When each value knows its own lifetime (an OAuth token, an HTTP response with Cache-Control),
implement Expires and set
expires = true:
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 is_expired(&self) -> bool {
Instant::now() >= self.expires_at
}
}
#[cached(expires = true)]
fn token(scope: String) -> Token {
Token { value: format!("token-{scope}"), expires_at: Instant::now() + Duration::from_secs(3600) }
}See examples/expires_per_key.rs.
§Feature flags
| Feature | Default | Enables |
|---|---|---|
proc_macro | yes | #[cached], #[once], #[concurrent_cached] |
time_stores | yes | TTL stores and the ttl_* macro attributes (disable for wasm32-unknown-unknown without time support) |
ahash | yes | ahash as the default hasher |
async | Async functions and async store traits (runtime-agnostic) | |
async_core | Async traits only, without the async-lock dependency | |
redis_store | Synchronous Redis store | |
redis_tokio / redis_smol | Async Redis on tokio or smol | |
redis_tokio_native_tls / redis_tokio_rustls | redis_tokio with TLS | |
redis_smol_native_tls / redis_smol_rustls | redis_smol with TLS | |
redis_connection_manager | Auto-reconnecting Redis connections (pair with a runtime feature) | |
redis_async_cache | Redis client-side caching over RESP3 (pair with a runtime feature) | |
redb_store | Disk store backed by redb |
§Requirements
- Rust 1.92 or later.
- Arguments must be
Hash + Eq + Clone, or supplykeyandconvertto build a key that is. Floats are the common case that needsconvert, e.g.convert = { format!("{x:.6}") }. - Return values must be
Clone; they are cloned on every hit. ReturnArc<T>whenTis expensive to clone. - Cached functions should not have side effects, since a hit skips the body.
- Generic functions need
keyandconvertto produce a concrete key type.
§Further reading
macros: every attribute, synchronization options, and more examplesstores: store comparison, method naming, sharding, and behavioral guaranteesclaim: single-flight guard for background refreshesexamples/: runnable programs, including stale-while-revalidate and refresh-before-expiry
§Upgrading
Migration guides for each release are in
docs/migrations. The major
ones:
Re-exports§
Modules§
- claim
- Single-flight claims on a key, released when the claim is dropped.
- macros
proc_macro - Procedural macros for defining functions that wrap a static-ref cache object.
- prelude
- Convenience re-exports of the commonly-needed cache traits.
- stores
- Cache store implementations.
Structs§
- Async
Redis Cache redis_smol_native_tlsorredis_smol_rustlsorredis_smolorredis_tokio_native_tlsorredis_tokio_rustlsorredis_tokio - Async cache store backed by redis.
- Async
Redis Cache Builder redis_smol_native_tlsorredis_smol_rustlsorredis_smolorredis_tokio_native_tlsorredis_tokio_rustlsorredis_tokio - Builder for
AsyncRedisCache. - Cache
Metrics - A snapshot of cache hit/miss and size statistics.
- Cache
Value - A cached value plus store-specific per-entry metadata, returned by the
LRU-family order methods (
LruCache::iter_order,LruCache::value_order, and theirLruTtlCache/ExpiringLruCachecounterparts). - Connection
String redis_store - A Redis connection URL stored in memory with credentials redacted in
Debug/Display. - Default
Shard Hasher - Default shard hasher backed by
ahash::RandomState(orstd::collections::hash_map::RandomStatewhen theahashfeature is disabled). - Expiring
Cache - Size-unbounded cache where each value controls its own expiry via
Expires. - Expiring
Cache Builder - Builder for
ExpiringCache. - Expiring
LruCache - LRU-bounded cache with per-value expiry.
- Expiring
LruCache Builder - Builder for
ExpiringLruCache. - HasEvict
time_stores - Typestate marker for
LruTtlCacheBuilder: eviction callback has been set. - LruCache
- Least Recently Used /
SizedCache - LruCache
Builder - Builder for
LruCache. - LruTtl
Cache time_stores - Timed LRU Cache
- LruTtl
Cache Builder time_stores - Builder for
LruTtlCache. - NoEvict
time_stores - Typestate marker for
LruTtlCacheBuilder: no eviction callback set. - Redb
Cache redb_store - Cache store backed by disk, using an embedded
redbdatabase (one file per cache). - Redb
Cache Builder redb_store - Redb
Cache Stats redb_store - Result of
RedbCache::scan_stats(andasync_scan_statsunder theasyncfeature). - Redis
Cache redis_store - Cache store backed by redis
- Redis
Cache Builder redis_store - Return
proc_macro - Used to wrap a function result so callers can see whether the result was cached.
- Sharded
Expiring Cache - A fully-concurrent, partitioned, unbounded in-memory cache with per-value expiry.
- Sharded
Expiring Cache Builder - Builder for
ShardedExpiringCache. - Sharded
Expiring LruCache - A fully-concurrent, partitioned, LRU size-bounded in-memory cache with per-value expiry.
- Sharded
Expiring LruCache Builder - Builder for
ShardedExpiringLruCache. - Sharded
LruCache - A fully-concurrent, partitioned, LRU-bounded in-memory cache.
- Sharded
LruCache Builder - Builder for
ShardedLruCache. - Sharded
LruTtl Cache time_stores - A fully-concurrent, partitioned, LRU-bounded, TTL-expiring in-memory cache.
- Sharded
LruTtl Cache Builder time_stores - Builder for
ShardedLruTtlCache. - Sharded
TtlCache time_stores - A fully-concurrent, partitioned, TTL-bounded in-memory cache.
- Sharded
TtlCache Builder time_stores - Builder for
ShardedTtlCache. - Sharded
Unbound Cache - A fully-concurrent, partitioned, unbounded in-memory cache.
- Sharded
Unbound Cache Builder - Builder for
ShardedUnboundCache. - TtlCache
time_stores - Cache store bound by time
- TtlCache
Builder time_stores - Builder for
TtlCache. - TtlSorted
Cache time_stores - A cache enforcing time expiration and an optional maximum size. When a maximum size is specified, the values are dropped in the order of expiration date, e.g. the next value to expire is dropped. This cache is intended for high read scenarios to allow for concurrent reads while still enforcing expiration and an optional maximum cache size.
- TtlSorted
Cache Builder time_stores - Builder for
TtlSortedCache. - TtlSorted
SetBuilder time_stores - Builder returned by
TtlSortedCache::set_withfor chaining a per-entry TTL override and/or opt-in eviction before performing the insertion. - Unbound
Cache - Default unbounded cache
- Unbound
Cache Builder - Builder for
UnboundCache.
Enums§
- Build
Error - Error returned by cache builder
build()methods. - Redb
Cache Build Error redb_store - Error returned when building a
RedbCache. - Redb
Cache Error redb_store - Redis
Cache Build Error redis_store - Error returned when building a
RedisCache/AsyncRedisCache. - Redis
Cache Error redis_store - Error returned by Redis cache operations.
- SetMax
Size Error - Error returned by
CacheSetMaxSize::try_set_max_sizeandConcurrentCacheSetMaxSize::try_set_max_size, and by the inherenttry_set_max_sizeon the bounded stores. - SetTtl
Error - Error returned by
CacheTtl::try_set_ttl.
Traits§
- Cache
Clear With OnEvict - Clearing a single-owner store with
on_evictnotification. - Cache
Evict - Trait for cache stores that support explicit eviction of expired entries.
- Cache
Expiry - Side-effect-free per-key expiry read on the single-owner stores.
- Cache
Refresh OnHit - Refresh-on-hit control for single-owner time-bounded cache stores.
- Cache
SetMax Size - Capacity resize for single-owner stores that carry a size bound.
- Cache
Ttl - TTL management for single-owner time-bounded cache stores.
- Cached
- Core cache operations for single-owner (non-concurrent) stores.
- Cached
Ext - Short-alias extension for
Cachedstores. - Cached
GetOr SetAsync async_core - Memoize an async closure over a synchronous in-memory
Cachedstore. - Cached
Iter - Iteration over cache contents for stores that can expose borrowed entries.
- Cached
Peek - Non-mutating cache lookup for stores that can expose a value by shared reference.
- Cached
Read - Shared-reference cache lookup for stores that can preserve normal read semantics without an exclusive mutable borrow.
- Clone
Cached - Extra cache operations for types that implement
Clone. - Concurrent
Cache Base - Shared base of the concurrent cache traits.
- Concurrent
Cache Clear With OnEvict - Clearing a concurrent store with
on_evictnotification. - Concurrent
Cache Evict - Concurrent counterpart of
CacheEvictfor internally-synchronized stores. - Concurrent
Cache Expiry - Concurrent analogue of
CacheExpiryfor the internally-synchronized sharded stores: a side-effect-free per-key expiry read. - Concurrent
Cache Peek - Side-effect-free cache lookup for concurrent stores that can expose a value cheaply.
- Concurrent
Cache Peek Async async_core - Async mirror of
ConcurrentCachePeek: a side-effect-free cache lookup for concurrent stores that can expose a value cheaply. - Concurrent
Cache Refresh OnHit - Refresh-on-hit control for concurrent stores that have a global TTL.
- Concurrent
Cache SetMax Size - Capacity resize for concurrent stores that carry a size bound.
- Concurrent
Cache Ttl - Global-TTL controls for concurrent stores that have one.
- Concurrent
Cached - Cache operations on a store that manages its own synchronization (a shared,
&selfAPI with owned return values and a fallibleError). Implemented by the six in-memory sharded stores (ShardedUnboundCache,ShardedLruCache,ShardedTtlCache,ShardedLruTtlCache,ShardedExpiringCache,ShardedExpiringLruCache) and by the IO storesRedisCache/RedbCache; implement it directly for a custom concurrent or IO-backed store (this is the ~10-line pattern the 1.0 migration guide recommends in place of the removedInMemoryAdapter): - Concurrent
Cached Async async_core - Direct-call syntax warning:
- Concurrent
Cached Async Ext async_core - Short-alias extension for
ConcurrentCachedAsyncstores, the async counterpart ofConcurrentCachedExt. - Concurrent
Cached Ext - Short-alias extension for
ConcurrentCachedstores. - Concurrent
Clone Cached - Concurrent analogue of
CloneCachedfor the internally-synchronized sharded stores. - Expires
- Implemented by values stored in
ExpiringLruCacheandExpiringCacheso the value itself decides when it is stale. Expired values are not returned by lookups and are removed on access: - Into
Values - Bulk-unwrap the
CacheValuewrapper out of the collections returned by the LRU-family order methods (LruCache::iter_order,LruCache::value_order, and theirLruTtlCache/ExpiringLruCachecounterparts), so collecting plainVs does not require.into_iter().map(CacheValue::into_value).collect(). - Serialize
Cached - Borrowed-set extension for serialize-based concurrent stores.
- Serialize
Cached Async async_core - Async borrowed-set extension for serialize-based concurrent stores.
- Shard
Hasher - Trait for types that deterministically map a key to a
u64shard hash.
Type Aliases§
- Default
Hash Builder ahash - Default hash builder for non-sharded in-memory stores.
Attribute Macros§
- cached
proc_macro - Define a memoized function using a cache store that implements
cached::Cached - concurrent_
cached proc_macro - Define a memoized function using a cache store that implements
cached::ConcurrentCached(andcached::ConcurrentCachedAsyncfor async functions). - once
proc_macro - Define a memoized function using a cache store that implements
cached::Cached. Function arguments are not used to identify a cached value, only one value is cached unless attlexpiry is specified.