Skip to main content

Crate cached

Crate cached 

Source
Expand description

Build Status crates.io docs

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 cache

The 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

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

AttributeEffect
max_size = NLRU eviction past N entries
ttl_secs = N / ttl_millis = NExpire entries after a fixed duration
refresh = trueReset an entry’s TTL on every hit
expires = trueEach 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 = trueOn Err, return the last cached Ok value
name = "NAME"Name of the generated cache static (defaults to the function name in caps)
in_impl = trueCache 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

NeedSingle-ownerConcurrent
UnboundedUnboundCacheShardedUnboundCache
Size limit (LRU)LruCacheShardedLruCache
Fixed TTLTtlCacheShardedTtlCache
Size limit + fixed TTLLruTtlCacheShardedLruTtlCache
Per-value expiryExpiringCacheShardedExpiringCache
Size limit + per-value expiryExpiringLruCacheShardedExpiringLruCache
Shared across processesRedisCache, AsyncRedisCache
Persisted to diskRedbCache

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

FeatureDefaultEnables
proc_macroyes#[cached], #[once], #[concurrent_cached]
time_storesyesTTL stores and the ttl_* macro attributes (disable for wasm32-unknown-unknown without time support)
ahashyesahash as the default hasher
asyncAsync functions and async store traits (runtime-agnostic)
async_coreAsync traits only, without the async-lock dependency
redis_storeSynchronous Redis store
redis_tokio / redis_smolAsync Redis on tokio or smol
redis_tokio_native_tls / redis_tokio_rustlsredis_tokio with TLS
redis_smol_native_tls / redis_smol_rustlsredis_smol with TLS
redis_connection_managerAuto-reconnecting Redis connections (pair with a runtime feature)
redis_async_cacheRedis client-side caching over RESP3 (pair with a runtime feature)
redb_storeDisk store backed by redb

§Requirements

  • Rust 1.92 or later.
  • Arguments must be Hash + Eq + Clone, or supply key and convert to build a key that is. Floats are the common case that needs convert, e.g. convert = { format!("{x:.6}") }.
  • Return values must be Clone; they are cloned on every hit. Return Arc<T> when T is expensive to clone.
  • Cached functions should not have side effects, since a hit skips the body.
  • Generic functions need key and convert to produce a concrete key type.

§Further reading

§Upgrading

Migration guides for each release are in docs/migrations. The major ones:

Re-exports§

pub use macros as proc_macro;proc_macro
pub use web_time as time;

Modules§

claim
Single-flight claims on a key, released when the claim is dropped.
macrosproc_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§

AsyncRedisCacheredis_smol_native_tls or redis_smol_rustls or redis_smol or redis_tokio_native_tls or redis_tokio_rustls or redis_tokio
Async cache store backed by redis.
AsyncRedisCacheBuilderredis_smol_native_tls or redis_smol_rustls or redis_smol or redis_tokio_native_tls or redis_tokio_rustls or redis_tokio
Builder for AsyncRedisCache.
CacheMetrics
A snapshot of cache hit/miss and size statistics.
CacheValue
A cached value plus store-specific per-entry metadata, returned by the LRU-family order methods (LruCache::iter_order, LruCache::value_order, and their LruTtlCache / ExpiringLruCache counterparts).
ConnectionStringredis_store
A Redis connection URL stored in memory with credentials redacted in Debug/Display.
DefaultShardHasher
Default shard hasher backed by ahash::RandomState (or std::collections::hash_map::RandomState when the ahash feature is disabled).
ExpiringCache
Size-unbounded cache where each value controls its own expiry via Expires.
ExpiringCacheBuilder
Builder for ExpiringCache.
ExpiringLruCache
LRU-bounded cache with per-value expiry.
ExpiringLruCacheBuilder
Builder for ExpiringLruCache.
HasEvicttime_stores
Typestate marker for LruTtlCacheBuilder: eviction callback has been set.
LruCache
Least Recently Used / Sized Cache
LruCacheBuilder
Builder for LruCache.
LruTtlCachetime_stores
Timed LRU Cache
LruTtlCacheBuildertime_stores
Builder for LruTtlCache.
NoEvicttime_stores
Typestate marker for LruTtlCacheBuilder: no eviction callback set.
RedbCacheredb_store
Cache store backed by disk, using an embedded redb database (one file per cache).
RedbCacheBuilderredb_store
RedbCacheStatsredb_store
Result of RedbCache::scan_stats (and async_scan_stats under the async feature).
RedisCacheredis_store
Cache store backed by redis
RedisCacheBuilderredis_store
Returnproc_macro
Used to wrap a function result so callers can see whether the result was cached.
ShardedExpiringCache
A fully-concurrent, partitioned, unbounded in-memory cache with per-value expiry.
ShardedExpiringCacheBuilder
Builder for ShardedExpiringCache.
ShardedExpiringLruCache
A fully-concurrent, partitioned, LRU size-bounded in-memory cache with per-value expiry.
ShardedExpiringLruCacheBuilder
Builder for ShardedExpiringLruCache.
ShardedLruCache
A fully-concurrent, partitioned, LRU-bounded in-memory cache.
ShardedLruCacheBuilder
Builder for ShardedLruCache.
ShardedLruTtlCachetime_stores
A fully-concurrent, partitioned, LRU-bounded, TTL-expiring in-memory cache.
ShardedLruTtlCacheBuildertime_stores
Builder for ShardedLruTtlCache.
ShardedTtlCachetime_stores
A fully-concurrent, partitioned, TTL-bounded in-memory cache.
ShardedTtlCacheBuildertime_stores
Builder for ShardedTtlCache.
ShardedUnboundCache
A fully-concurrent, partitioned, unbounded in-memory cache.
ShardedUnboundCacheBuilder
Builder for ShardedUnboundCache.
TtlCachetime_stores
Cache store bound by time
TtlCacheBuildertime_stores
Builder for TtlCache.
TtlSortedCachetime_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.
TtlSortedCacheBuildertime_stores
Builder for TtlSortedCache.
TtlSortedSetBuildertime_stores
Builder returned by TtlSortedCache::set_with for chaining a per-entry TTL override and/or opt-in eviction before performing the insertion.
UnboundCache
Default unbounded cache
UnboundCacheBuilder
Builder for UnboundCache.

Enums§

BuildError
Error returned by cache builder build() methods.
RedbCacheBuildErrorredb_store
Error returned when building a RedbCache.
RedbCacheErrorredb_store
RedisCacheBuildErrorredis_store
Error returned when building a RedisCache/AsyncRedisCache.
RedisCacheErrorredis_store
Error returned by Redis cache operations.
SetMaxSizeError
Error returned by CacheSetMaxSize::try_set_max_size and ConcurrentCacheSetMaxSize::try_set_max_size, and by the inherent try_set_max_size on the bounded stores.
SetTtlError
Error returned by CacheTtl::try_set_ttl.

Traits§

CacheClearWithOnEvict
Clearing a single-owner store with on_evict notification.
CacheEvict
Trait for cache stores that support explicit eviction of expired entries.
CacheExpiry
Side-effect-free per-key expiry read on the single-owner stores.
CacheRefreshOnHit
Refresh-on-hit control for single-owner time-bounded cache stores.
CacheSetMaxSize
Capacity resize for single-owner stores that carry a size bound.
CacheTtl
TTL management for single-owner time-bounded cache stores.
Cached
Core cache operations for single-owner (non-concurrent) stores.
CachedExt
Short-alias extension for Cached stores.
CachedGetOrSetAsyncasync_core
Memoize an async closure over a synchronous in-memory Cached store.
CachedIter
Iteration over cache contents for stores that can expose borrowed entries.
CachedPeek
Non-mutating cache lookup for stores that can expose a value by shared reference.
CachedRead
Shared-reference cache lookup for stores that can preserve normal read semantics without an exclusive mutable borrow.
CloneCached
Extra cache operations for types that implement Clone.
ConcurrentCacheBase
Shared base of the concurrent cache traits.
ConcurrentCacheClearWithOnEvict
Clearing a concurrent store with on_evict notification.
ConcurrentCacheEvict
Concurrent counterpart of CacheEvict for internally-synchronized stores.
ConcurrentCacheExpiry
Concurrent analogue of CacheExpiry for the internally-synchronized sharded stores: a side-effect-free per-key expiry read.
ConcurrentCachePeek
Side-effect-free cache lookup for concurrent stores that can expose a value cheaply.
ConcurrentCachePeekAsyncasync_core
Async mirror of ConcurrentCachePeek: a side-effect-free cache lookup for concurrent stores that can expose a value cheaply.
ConcurrentCacheRefreshOnHit
Refresh-on-hit control for concurrent stores that have a global TTL.
ConcurrentCacheSetMaxSize
Capacity resize for concurrent stores that carry a size bound.
ConcurrentCacheTtl
Global-TTL controls for concurrent stores that have one.
ConcurrentCached
Cache operations on a store that manages its own synchronization (a shared, &self API with owned return values and a fallible Error). Implemented by the six in-memory sharded stores (ShardedUnboundCache, ShardedLruCache, ShardedTtlCache, ShardedLruTtlCache, ShardedExpiringCache, ShardedExpiringLruCache) and by the IO stores RedisCache/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 removed InMemoryAdapter):
ConcurrentCachedAsyncasync_core
Direct-call syntax warning:
ConcurrentCachedAsyncExtasync_core
Short-alias extension for ConcurrentCachedAsync stores, the async counterpart of ConcurrentCachedExt.
ConcurrentCachedExt
Short-alias extension for ConcurrentCached stores.
ConcurrentCloneCached
Concurrent analogue of CloneCached for the internally-synchronized sharded stores.
Expires
Implemented by values stored in ExpiringLruCache and ExpiringCache so the value itself decides when it is stale. Expired values are not returned by lookups and are removed on access:
IntoValues
Bulk-unwrap the CacheValue wrapper out of the collections returned by the LRU-family order methods (LruCache::iter_order, LruCache::value_order, and their LruTtlCache / ExpiringLruCache counterparts), so collecting plain Vs does not require .into_iter().map(CacheValue::into_value).collect().
SerializeCached
Borrowed-set extension for serialize-based concurrent stores.
SerializeCachedAsyncasync_core
Async borrowed-set extension for serialize-based concurrent stores.
ShardHasher
Trait for types that deterministically map a key to a u64 shard hash.

Type Aliases§

DefaultHashBuilderahash
Default hash builder for non-sharded in-memory stores.

Attribute Macros§

cachedproc_macro
Define a memoized function using a cache store that implements cached::Cached
concurrent_cachedproc_macro
Define a memoized function using a cache store that implements cached::ConcurrentCached (and cached::ConcurrentCachedAsync for async functions).
onceproc_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 a ttl expiry is specified.