Moka

注意 v0.12.0 在 API 和内部行为上进行了重大破坏性更改。请阅读 MIGRATION-GUIDE.md 获取详细信息。

Moka 是一个快速的 Rust 并发缓存库。Moka 受 Java 的 Caffeine 缓存库的启发。

Moka 在哈希表之上提供了缓存实现。它们支持检索的全并发和更新的高预期并发性。

所有缓存都会使用一个条目替换算法来尝试对哈希表进行最佳努力限制，以确定在容量超出时哪些条目将被驱逐。

特性

Moka 提供了一个丰富且灵活的功能集，同时保持高命中率和高并发访问级别。

• 线程安全的、高度并发的内存缓存实现
  • 同步缓存，可以在操作系统线程之间共享。
  • 异步（对 futures 有感知）的缓存。
• 缓存可以通过以下之一进行限制
  • 条目数量的最大值。
  • 条目的总加权大小。（大小感知驱逐）
• 通过使用受 Caffeine 启发的条目替换算法来维护接近最优的命中率
  • 缓存访问控制由最不经常使用（LFU）策略控制。
  • 缓存驱逐由最近最少使用（LRU）策略控制。
  • 更多详细信息和一些基准测试结果在此处提供.
• 支持过期策略
  • 生存时间。
  • 空闲时间。
  • 每个条目可变过期。
• 支持驱逐监听器，当条目从缓存中删除时将被调用的回调函数。

为您的用例选择合适的缓存

没有缓存实现适合所有用例。Moka 是一个复杂的软件，可能不适合您的用例。有时，像 Mini Moka 或 Quick Cache 这样的简单缓存可能更适合。

下表显示了不同缓存实现之间的权衡

生产中的 Moka

Moka 正在为生产服务和嵌入式 Linux 设备（如家用路由器）提供动力。以下是亮点

• crates.io：官方crate注册已经使用 Moka 在其API服务中，以减少 PostgreSQL 的负载。Moka 维护 缓存命中率约为85% 的高流量下载端点。（Moka 使用：2021年11月至今）
• aliyundrive-webdav：这可能已经部署在数百个家用Wi-Fi路由器中，包括32位MIPS或基于ARMv5TE的SoC的低成本型号。Moka 用于缓存远程文件的元数据。（Moka 使用：2021年8月至今）

最近更改

注意 v0.12.0 在API和内部行为上进行了重大破坏性更改。请阅读 MIGRATION-GUIDE.md 了解详细信息。

• MIGRATION-GUIDE.md
• CHANGELOG.md

目录

• 特性
  • 为您的用例选择合适的缓存
• 生产中的 Moka
• 变更日志
• 支持的平台
• 用法
• 示例（第1部分）
  • 同步缓存
  • 异步缓存
• 避免在 get 处克隆值
• 示例（第2部分）
  • 大小感知驱逐
• 过期策略
• 最低支持的Rust版本
• 故障排除
  • 某些32位平台上的编译错误
• 开发 Moka
• 路线图
• 关于名称
• 致谢
• 许可

支持的平台

如果Rust std 库带有线程支持，则Moka 应该能在大多数64位和32位平台上运行。但是，WebAssembly（Wasm）和WASI目标不受支持。

以下平台已在CI上测试

• Linux 64位（x86_64，arm aarch64）
• Linux 32位（i646，armv7，armv5，mips）
  • 如果您在32位平台上遇到编译错误，请参阅 故障排除。

以下平台未在CI上测试但应工作

• macOS（arm64）
• Windows（x86_64 msvc 和 gnu）
• iOS（arm64）

以下平台不支持

• WebAssembly（Wasm）和WASI目标不受支持。（见 此项目任务）
• nostd 环境（没有 std 库的平台）不受支持。
• 16位平台不受支持。

用法

要将 Moka 添加到依赖项，运行以下命令

# To use the synchronous cache:
cargo add moka --features sync

# To use the asynchronous cache:
cargo add moka --features future

如果您想在 tokio 或 async-std 等异步运行时下使用缓存，您应指定 future 功能。否则，指定 sync 功能。

示例：同步缓存

线程安全的同步缓存在 sync 模块中定义。

使用 insert 或 get_with 方法手动添加缓存条目，并在缓存中存储，直到被驱逐或手动失效。

以下是使用多线程读取和更新缓存的示例

// Use the synchronous cache.
use moka::sync::Cache;

use std::thread;

fn value(n: usize) -> String {
    format!("value {n}")
}

fn main() {
    const NUM_THREADS: usize = 16;
    const NUM_KEYS_PER_THREAD: usize = 64;

    // Create a cache that can store up to 10,000 entries.
    let cache = Cache::new(10_000);

    // Spawn threads and read and update the cache simultaneously.
    let threads: Vec<_> = (0..NUM_THREADS)
        .map(|i| {
            // To share the same cache across the threads, clone it.
            // This is a cheap operation.
            let my_cache = cache.clone();
            let start = i * NUM_KEYS_PER_THREAD;
            let end = (i + 1) * NUM_KEYS_PER_THREAD;

            thread::spawn(move || {
                // Insert 64 entries. (NUM_KEYS_PER_THREAD = 64)
                for key in start..end {
                    my_cache.insert(key, value(key));
                    // get() returns Option<String>, a clone of the stored value.
                    assert_eq!(my_cache.get(&key), Some(value(key)));
                }

                // Invalidate every 4 element of the inserted entries.
                for key in (start..end).step_by(4) {
                    my_cache.invalidate(&key);
                }
            })
        })
        .collect();

    // Wait for all threads to complete.
    threads.into_iter().for_each(|t| t.join().expect("Failed"));

    // Verify the result.
    for key in 0..(NUM_THREADS * NUM_KEYS_PER_THREAD) {
        if key % 4 == 0 {
            assert_eq!(cache.get(&key), None);
        } else {
            assert_eq!(cache.get(&key), Some(value(key)));
        }
    }
}

您可以通过克隆存储库并运行以下cargo命令来尝试同步示例：

$ cargo run --example sync_example

如果您想在键不存在时原子性地初始化和插入值，您可能需要查看文档以获取其他插入方法get_with和try_get_with。

示例：异步缓存

异步（futures aware）缓存定义在future模块中。它与异步运行时环境（如Tokio、async-std或actix-rt）一起工作。要使用异步缓存，请启用名为"future"的crate功能。

缓存条目通过插入方法手动添加，并存储在缓存中，直到被驱逐或手动失效。

• 在异步上下文（async fn或async块）内部，使用insert或invalidate方法来更新缓存，并使用await它们。
• 在任何异步上下文之外，使用blocking方法来访问insert或invalidate方法的阻塞版本。

这是一个与上一个示例类似的程序，但使用Tokio运行时异步缓存。

// Cargo.toml
//
// [dependencies]
// moka = { version = "0.12", features = ["future"] }
// tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }
// futures-util = "0.3"

// Use the asynchronous cache.
use moka::future::Cache;

#[tokio::main]
async fn main() {
    const NUM_TASKS: usize = 16;
    const NUM_KEYS_PER_TASK: usize = 64;

    fn value(n: usize) -> String {
        format!("value {n}")
    }

    // Create a cache that can store up to 10,000 entries.
    let cache = Cache::new(10_000);

    // Spawn async tasks and write to and read from the cache.
    let tasks: Vec<_> = (0..NUM_TASKS)
        .map(|i| {
            // To share the same cache across the async tasks, clone it.
            // This is a cheap operation.
            let my_cache = cache.clone();
            let start = i * NUM_KEYS_PER_TASK;
            let end = (i + 1) * NUM_KEYS_PER_TASK;

            tokio::spawn(async move {
                // Insert 64 entries. (NUM_KEYS_PER_TASK = 64)
                for key in start..end {
                    // insert() is an async method, so await it.
                    my_cache.insert(key, value(key)).await;
                    // get() returns Option<String>, a clone of the stored value.
                    assert_eq!(my_cache.get(&key).await, Some(value(key)));
                }

                // Invalidate every 4 element of the inserted entries.
                for key in (start..end).step_by(4) {
                    // invalidate() is an async method, so await it.
                    my_cache.invalidate(&key).await;
                }
            })
        })
        .collect();

    // Wait for all tasks to complete.
    futures_util::future::join_all(tasks).await;

    // Verify the result.
    for key in 0..(NUM_TASKS * NUM_KEYS_PER_TASK) {
        if key % 4 == 0 {
            assert_eq!(cache.get(&key).await, None);
        } else {
            assert_eq!(cache.get(&key).await, Some(value(key)));
        }
    }
}

您可以通过克隆存储库并运行以下cargo命令来尝试异步示例：

$ cargo run --example async_example --features future

如果您想在键不存在时原子性地初始化和插入值，您可能需要查看文档以获取其他插入方法get_with和try_get_with。

避免在 get 处克隆值

对于并发缓存（sync和future缓存），get方法的返回类型是Option<V>，而不是Option<&V>，其中V是值类型。每次对现有键调用get时，它都会创建存储值的克隆V并将其返回。这是因为在任何给定时间，任何其他线程都可以更改或替换存储在缓存中的值。因此，get不能返回引用&V，因为这无法保证值会存活于引用。

如果您要存储复制成本高昂的值，请在存储到缓存之前，使用std::sync::Arc对其进行包装。Arc是一个线程安全的引用计数指针，其clone方法成本低廉。

use std::sync::Arc;

let key = ...
let large_value = vec![0u8; 2 * 1024 * 1024]; // 2 MiB

// When insert, wrap the large_value by Arc.
cache.insert(key.clone(), Arc::new(large_value));

// get() will call Arc::clone() on the stored value, which is cheap.
cache.get(&key);

use moka::sync::Cache;

fn main() {
    let cache = Cache::builder()
        // A weigher closure takes &K and &V and returns a u32 representing the
        // relative size of the entry. Here, we use the byte length of the value
        // String as the size.
        .weigher(|_key, value: &String| -> u32 {
            value.len().try_into().unwrap_or(u32::MAX)
        })
        // This cache will hold up to 32MiB of values.
        .max_capacity(32 * 1024 * 1024)
        .build();
    cache.insert(0, "zero".to_string());
}

$ cargo run --example size_aware_eviction

error[E0432]: unresolved import `std::sync::atomic::AtomicU64`
  --> ... /moka-0.5.3/src/sync.rs:10:30
   |
10 |         atomic::{AtomicBool, AtomicU64, Ordering},
   |                              ^^^^^^^^^
   |                              |
   |                              no `AtomicU64` in `sync::atomic`

[dependencies]
moka = { version = "0.12", default-features = false, features = ["sync"] }
# Or
moka = { version = "0.12", default-features = false, features = ["future"] }

$ RUSTFLAGS='--cfg trybuild' cargo test --all-features

$ RUSTFLAGS='--cfg trybuild' cargo test \
    --no-default-features --features 'future, sync'

$ cargo +nightly -Z unstable-options --config 'build.rustdocflags="--cfg docsrs"' \
    doc --no-deps --features 'future, sync'