foyer

foyer 旨在成为Rust中高效且用户友好的混合缓存库。

foyer从Facebook/CacheLib（一个用C++编写的备受推崇的混合缓存库）和其他项目，如ben-manes/caffeine（一个流行的Java缓存库）中汲取灵感。

然而，foyer 不只是一个用Rust重写的努力；它引入了各种新颖和优化的特性。

特性

• 混合缓存：无缝集成内存和基于磁盘的缓存，以实现最佳性能和灵活性。
• 即插即用算法：使用户能够轻松替换缓存算法，确保适应各种用例。
• 无畏的并发：构建用于处理高并发的强大线程安全机制，确保在重负载下可靠的性能。
• 零拷贝内存缓存抽象：利用Rust强大的类型系统，foyer中的内存缓存通过零拷贝抽象实现更好的性能。
• 用户友好的接口：提供简单直观的API，使缓存集成对各个级别的开发者来说既轻松又容易访问。
• 开箱即用可观测性：只需一行代码即可集成流行的观测系统，如Prometheus、Grafana、Opentelemetry和Jaeger。

使用foyer的项目

欢迎提交PR并添加您的项目

• RisingWave：SQL流处理、分析和管理。
• Chroma：嵌入式数据库用于LLM应用。

使用方法

要在项目中使用foyer，请将此行添加到依赖部分的Cargo.toml。

foyer = "0.11"

如果您的项目正在使用nightly rust工具链，则需要启用nightly功能。

foyer = { version = "0.11", features = ["nightly"] }

开箱即用的内存缓存

use foyer::{Cache, CacheBuilder};

fn main() {
    let cache: Cache<String, String> = CacheBuilder::new(16).build();

    let entry = cache.insert("hello".to_string(), "world".to_string());
    let e = cache.get("hello").unwrap();

    assert_eq!(entry.value(), e.value());
}

易于使用的混合缓存

use foyer::{DirectFsDeviceOptionsBuilder, HybridCache, HybridCacheBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let dir = tempfile::tempdir()?;

    let hybrid: HybridCache<u64, String> = HybridCacheBuilder::new()
        .memory(64 * 1024 * 1024)
        .storage()
        .with_device_config(
            DirectFsDeviceOptionsBuilder::new(dir.path())
                .with_capacity(256 * 1024 * 1024)
                .build(),
        )
        .build()
        .await?;

    hybrid.insert(42, "The answer to life, the universe, and everything.".to_string());
    assert_eq!(
        hybrid.get(&42).await?.unwrap().value(),
        "The answer to life, the universe, and everything."
    );

    Ok(())
}

完全配置的混合缓存

use std::sync::Arc;

use anyhow::Result;
use chrono::Datelike;
use foyer::{
    DirectFsDeviceOptionsBuilder, FifoPicker, HybridCache, HybridCacheBuilder, LruConfig, RateLimitPicker, RecoverMode,
    RuntimeConfig, TokioRuntimeConfig, TombstoneLogConfigBuilder,
};
use tempfile::tempdir;

#[tokio::main]
async fn main() -> Result<()> {
    let dir = tempdir()?;

    let hybrid: HybridCache<u64, String> = HybridCacheBuilder::new()
        .memory(1024)
        .with_shards(4)
        .with_eviction_config(LruConfig {
            high_priority_pool_ratio: 0.1,
        })
        .with_object_pool_capacity(1024)
        .with_hash_builder(ahash::RandomState::default())
        .with_weighter(|_key, value: &String| value.len())
        .storage()
        .with_device_config(
            DirectFsDeviceOptionsBuilder::new(dir.path())
                .with_capacity(64 * 1024 * 1024)
                .with_file_size(4 * 1024 * 1024)
                .build(),
        )
        .with_flush(true)
        .with_indexer_shards(64)
        .with_recover_mode(RecoverMode::Quiet)
        .with_recover_concurrency(8)
        .with_flushers(2)
        .with_reclaimers(2)
        .with_buffer_threshold(256 * 1024 * 1024)
        .with_clean_region_threshold(4)
        .with_eviction_pickers(vec![Box::<FifoPicker>::default()])
        .with_admission_picker(Arc::new(RateLimitPicker::new(100 * 1024 * 1024)))
        .with_reinsertion_picker(Arc::new(RateLimitPicker::new(10 * 1024 * 1024)))
        .with_compression(foyer::Compression::Lz4)
        .with_tombstone_log_config(
            TombstoneLogConfigBuilder::new(dir.path().join("tombstone-log-file"))
                .with_flush(true)
                .build(),
        )
        .with_runtime_config(RuntimeConfig::Separated {
            read_runtime_config: TokioRuntimeConfig {
                worker_threads: 4,
                max_blocking_threads: 8,
            },
            write_runtime_config: TokioRuntimeConfig {
                worker_threads: 4,
                max_blocking_threads: 8,
            },
        })
        .build()
        .await?;

    hybrid.insert(42, "The answer to life, the universe, and everything.".to_string());
    assert_eq!(
        hybrid.get(&42).await?.unwrap().value(),
        "The answer to life, the universe, and everything."
    );

    let e = hybrid
        .fetch(20230512, || async {
            let value = mock().await?;
            Ok(value)
        })
        .await?;
    assert_eq!(e.key(), &20230512);
    assert_eq!(e.value(), "Hello, foyer.");

    hybrid.close().await.unwrap();

    Ok(())
}

async fn mock() -> Result<String> {
    let now = chrono::Utc::now();
    if format!("{}{}{}", now.year(), now.month(), now.day()) == "20230512" {
        return Err(anyhow::anyhow!("Hi, time traveler!"));
    }
    Ok("Hello, foyer.".to_string())
}

其他示例

• 事件监听器
• 基于尾部的跟踪

更多示例和详情可以在这里找到：这里。

支持的 Rust 版本

foyer 是基于最近的稳定版本构建的。最低支持版本为 1.77。当前的 foyer 版本不一定能在低于最低支持版本的 Rust 版本上构建。

开发状态 & 路线图

目前，foyer 仍在积极开发中。

开发状态和路线图可以在 foyer - 开发路线图 中找到。

贡献

欢迎为 foyer 贡献！🥰

提交 PR 之前，别忘了在本地执行 make fast（表示快速检查 & 测试）。🚀

如果您想在本地运行更广泛的检查，请运行 make full。🙌

星号历史