Skip to main content

Crate oxcache

Crate oxcache 

Source
Expand description

oxcache - 高性能多层缓存库

§Example

ⓘ
use oxcache::Cache;
use oxcache::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
struct User { id: u64, name: String }

#[tokio::main]
async fn main() -> OxCacheResult<(), Box<dyn std::error::Error>> {
    let cache: Cache<String, User> = Cache::builder().build().await?;
    cache.set(&"user:1".to_string(), &User { id: 1, name: "Alice".into() }).await?;
    let user = cache.get(&"user:1".to_string()).await?;
    Ok(())
}

§Tiered Cache

ⓘ
use oxcache::cache::{ChainCache, ChainLink};
use oxcache::backend::MokaMemoryBackend;

let l1 = MokaMemoryBackend::builder().capacity(10000).build();
let l2 = oxcache::backend::RedisBackend::new("redis://localhost:6379").await?;

let chain = ChainCache::builder()
    .link(ChainLink::from_backend(l1))
    .link(ChainLink::from_backend(l2))
    .enable_backfill()
    .build();

§Sync API (0.3.0)

Enable sync_mode(true) on the builder to get synchronous methods (get_sync / set_sync / set_with_ttl_sync / delete_sync / exists_sync / get_or_sync / clear_sync) alongside the async API. Requires multi_thread tokio runtime for Moka-backed caches.

ⓘ
let cache: Cache<String, String> = Cache::builder().sync_mode(true).build().await?;
cache.set_sync(&"k".to_string(), &"v".to_string())?;
let v = cache.get_sync(&"k".to_string())?;

§Bloom Filter (0.3.0)

Enable the bloom feature (not in full) for negative-query filtering. BloomFilterBackend wraps any CacheBackend and skips the inner backend on BF miss.

ⓘ
use oxcache::backend::MokaMemoryBackend;
use oxcache::features::BloomFilterBackend;
let backend = BloomFilterBackend::new(MokaMemoryBackend::new());

§Universal per-entry TTL (0.3.0)

All backends (Moka / DashMap / Redis / Mock / Chain / Bloom) honor per-entry set(key, value, Some(ttl)). Moka uses the moka::Expiry trait for real per-entry TTL (overriding the global TTL set on the builder).

§Features

§Tiered Feature Sets

  • minimal: L1 memory cache only (memory + metrics + serialization + chrono)
  • core: L1 + L2 Redis (minimal + redis)
  • full: All features enabled (opt-in via features = [“full”])

§Core Component Features

  • memory: L1 memory cache (Moka + DashMap)
  • redis: L2 distributed cache (Redis + regex)
  • macros: Proc macros for #[cached]
  • serialization: JSON serialization (serde + serde_json)
  • compression: Flate2 compression
  • metrics: Built-in performance metrics (latency histograms, operation counters, JSON export); OTLP export handled at application layer
  • batch: Buffered L2 writes
  • lua: Lua script execution (requires redis)
  • cli: CLI tools
  • testing: Testing support (exposes internal functions)
  • bloom: Negative-query filtering (not in full)
  • kit: trait-kit AsyncKit integration (OxcacheModule) (not in full)
  • lock: Distributed lock via Redis (TTL, reentrant, watchdog auto-renew)

§Distributed Lock (lock feature)

Cross-instance mutual exclusion backed by Redis. Supports TTL, automatic watchdog renewal, and reentrant acquire/release.

ⓘ
use oxcache::features::dist_lock::DistLockBuilder;
use std::time::Duration;

let mut lock = DistLockBuilder::new(backend, "task:webhook-delivery".into())
    .ttl(Duration::from_secs(30))
    .watchdog_enabled(true)
    .build();
if lock.acquire().await? {
    // critical section
    lock.release().await?;
}

§Cache Penetration Guard

Two-layer protection against cache stampede and penetration:

  • Single-flight (get_or / get_or_sync): 64-shard dedup ensures only one fallback executes per key under concurrent cache misses.
  • Null sentinel (get_or_option): caches a sentinel for None results when null_cache_ttl is configured, preventing repeated DB lookups for non-existent keys.
  • TTL jitter (ttl_jitter): randomizes actual TTL within base_ttl * (1.0 ± factor) to prevent mass expiration stampede.
ⓘ
let cache: Cache<String, User> = Cache::builder()
    .null_cache_ttl(Duration::from_secs(30))
    .ttl_jitter(0.1)
    .build().await?;

// Returns None and caches sentinel if DB also returns None
let user = cache.get_or_option(&"user:999".to_string(), || async {
    db.find_user(999).await  // returns OxCacheResult<Option<User>>
}).await?;

Re-exports§

pub use error::OxCacheError;
pub use error::OxCacheResult;
pub use cache::BytesCache;
pub use cache::Cache;
pub use cache::CacheBuilder;
pub use infra::CacheStats;
pub use infra::export_json_format;
pub use infra::export_prometheus_format;
pub use infra::get_enhanced_stats;
pub use cache::UnifiedCache;
pub use cache::ChainCache;
pub use cache::ChainCacheBuilder;
pub use traits::CacheKey;
pub use backend::BackendScore;
pub use backend::DashMapMemoryBackend;
pub use backend::MemoryBackendType;
pub use backend::MokaMemoryBackend;
pub use backend::Scores;
pub use backend::dashmap_memory;
pub use backend::default_memory_backend;
pub use backend::moka_memory;

Modules§

backend
Backend provider module for oxcache.
cache
Unified Cache interface for the modernized cache API
error
该模块定义了缓存系统的错误类型和处理机制。
features
Features module
i18n
ICU4X-backed internationalization formatting for cache operations.
infra
Infrastructure module
registry
Global cache registry for #[cached] macro support
traits
Core traits for the modernized cache API

Macros§

check_feature_dependence
编译时特性依赖检查（支持 full 特性）
impl_backend_builder
Macro to implement the common new() and builder() pattern for backends.

Structs§

CacheEvent
缓存事件
KeyGenerator
缓存键生成器

Enums§

BackendType
缓存后端类型
CacheEventType
缓存事件类型
CacheLayer
缓存层级
RedisModeType
Redis 连接模式
SerializationType
序列化格式类型

Constants§

VERSION
oxcache 版本号

Traits§

Deserialize
A data structure that can be deserialized from any data format supported by Serde.
EventPublisher
事件发布器 Trait
Serialize
A data structure that can be serialized into any data format supported by Serde.

Derive Macros§

Deserialize
Serialize