Skip to main content

Crate oxcache

Crate oxcache 

Source
Expand description

oxcache - 高性能多层缓存库

§Example

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

#[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-filter 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 + tracing + metrics + serialization + chrono)
  • core: L1 + L2 Redis (minimal + redis + futures)
  • 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
  • tracing: Tracing support
  • metrics: OpenTelemetry metrics & observability
  • batch-write: Buffered L2 writes (tokio-util)
  • lua-script: Lua script execution (requires redis)
  • cli: CLI tools (clap)
  • testing: Testing support (exposes internal functions)
  • bloom-filter: Negative-query filtering (not in full)
  • i18n: ICU4X-backed locale-aware formatting (not in full)
  • kit: trait-kit AsyncKit integration (OxcacheModule) (not in full)

Re-exports§

pub use error::OxCacheError;
pub use error::OxCacheResult;
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
cache
Unified Cache interface for the modernized cache API
error
该模块定义了缓存系统的错误类型和处理机制。
features
Features module
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§

EventPublisher
事件发布器 Trait