feat: unify foyer in-memory cache and disk cache

.github/template/template.yml

@@ -98,6 +98,13 @@ jobs:
           CI: true
         run: |
           cargo llvm-cov --no-report nextest
+      - name: Run examples with coverage
+        env:
+          RUST_BACKTRACE: 1
+          CI: true
+        run: |
+          cargo llvm-cov --no-report run --example memory
+          cargo llvm-cov --no-report run --example hybrid
       - name: Generate codecov report
         run: |
           cargo llvm-cov report --lcov --output-path lcov.info
@@ -137,7 +144,7 @@ jobs:
         run: |-
           cargo build --all --features deadlock
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock
-          timeout 2m ./target/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
   asan:
     name: run with address saniziter
     runs-on: ubuntu-latest
@@ -175,7 +182,7 @@ jobs:
         run: |-
           cargo +${{ env.RUST_TOOLCHAIN_NIGHTLY }} build --all --target x86_64-unknown-linux-gnu
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan
-          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
       - name: Prepare Artifacts on Failure
         if: ${{ failure() }}
         run: |-
@@ -223,7 +230,7 @@ jobs:
         run: |-
           cargo +${{ env.RUST_TOOLCHAIN_NIGHTLY }} build --all --target x86_64-unknown-linux-gnu
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan
-          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
       - name: Prepare Artifacts on Failure
         if: ${{ failure() }}
         run: |-

.github/workflows/main.yml

@@ -105,6 +105,13 @@ jobs:
           CI: true
         run: |
           cargo llvm-cov --no-report nextest
+      - name: Run examples with coverage
+        env:
+          RUST_BACKTRACE: 1
+          CI: true
+        run: |
+          cargo llvm-cov --no-report run --example memory
+          cargo llvm-cov --no-report run --example hybrid
       - name: Generate codecov report
         run: |
           cargo llvm-cov report --lcov --output-path lcov.info
@@ -144,7 +151,7 @@ jobs:
         run: |-
           cargo build --all --features deadlock
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock
-          timeout 2m ./target/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
   asan:
     name: run with address saniziter
     runs-on: ubuntu-latest
@@ -182,7 +189,7 @@ jobs:
         run: |-
           cargo +${{ env.RUST_TOOLCHAIN_NIGHTLY }} build --all --target x86_64-unknown-linux-gnu
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan
-          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
       - name: Prepare Artifacts on Failure
         if: ${{ failure() }}
         run: |-
@@ -230,7 +237,7 @@ jobs:
         run: |-
           cargo +${{ env.RUST_TOOLCHAIN_NIGHTLY }} build --all --target x86_64-unknown-linux-gnu
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan
-          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
       - name: Prepare Artifacts on Failure
         if: ${{ failure() }}
         run: |-

.github/workflows/pull-request.yml

@@ -104,6 +104,13 @@ jobs:
           CI: true
         run: |
           cargo llvm-cov --no-report nextest
+      - name: Run examples with coverage
+        env:
+          RUST_BACKTRACE: 1
+          CI: true
+        run: |
+          cargo llvm-cov --no-report run --example memory
+          cargo llvm-cov --no-report run --example hybrid
       - name: Generate codecov report
         run: |
           cargo llvm-cov report --lcov --output-path lcov.info
@@ -143,7 +150,7 @@ jobs:
         run: |-
           cargo build --all --features deadlock
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock
-          timeout 2m ./target/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/deadlock --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
   asan:
     name: run with address saniziter
     runs-on: ubuntu-latest
@@ -181,7 +188,7 @@ jobs:
         run: |-
           cargo +${{ env.RUST_TOOLCHAIN_NIGHTLY }} build --all --target x86_64-unknown-linux-gnu
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan
-          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/asan --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
       - name: Prepare Artifacts on Failure
         if: ${{ failure() }}
         run: |-
@@ -229,7 +236,7 @@ jobs:
         run: |-
           cargo +${{ env.RUST_TOOLCHAIN_NIGHTLY }} build --all --target x86_64-unknown-linux-gnu
           mkdir -p $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan
-          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan --capacity 256 --file-size 16 --lookup-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
+          timeout 2m ./target/x86_64-unknown-linux-gnu/debug/foyer-storage-bench --dir $GITHUB_WORKSPACE/foyer-data/foyer-storage-bench/lsan --capacity 256 --file-size 16 --get-range 1000 --w-rate 1 --r-rate 1 --ticket-insert-rate-limit 10 --time 60
       - name: Prepare Artifacts on Failure
         if: ${{ failure() }}
         run: |-

Makefile

@@ -1,5 +1,5 @@
 SHELL := /bin/bash
-.PHONY: deps check test test-ignored test-all all fast monitor clear madsim
+.PHONY: deps check test test-ignored test-all all fast monitor clear madsim example
 
 deps:
 	./scripts/install-deps.sh
@@ -46,9 +46,13 @@ madsim:
 	RUSTFLAGS="--cfg madsim --cfg tokio_unstable" RUST_BACKTRACE=1 cargo nextest run --all
 	RUSTFLAGS="--cfg madsim --cfg tokio_unstable" RUST_BACKTRACE=1 cargo test --doc
 
-all: check-all test-all
+example:
+	cargo run --example memory
+	cargo run --example hybrid
 
-fast: check test
+all: check-all test-all example
+
+fast: check test example
 
 monitor:
 	./scripts/monitor.sh

examples/Cargo.toml

@@ -12,8 +12,17 @@ readme = "../README.md"
 publish = false
 
 [dependencies]
+ahash = "0.8"
+anyhow = "1"
+chrono = "0.4"
 foyer = { version = "*", path = "../foyer" }
+tempfile = "3"
+tokio = { version = "1", features = ["rt"] }
 
 [[example]]
 name = "memory"
 path = "memory.rs"
+
+[[example]]
+name = "hybrid"
+path = "hybrid.rs"

examples/hybrid.rs

@@ -0,0 +1,95 @@
+//  Copyright 2024 Foyer Project Authors
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+use std::sync::Arc;
+
+use chrono::Datelike;
+use foyer::{
+    CacheContext, FsDeviceConfigBuilder, HybridCache, HybridCacheBuilder, LfuConfig, LruConfig,
+    RatedTicketAdmissionPolicy, RatedTicketReinsertionPolicy, RuntimeConfigBuilder,
+};
+use tempfile::tempdir;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let dir = tempdir()?;
+
+    let hybrid: HybridCache<u64, Arc<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: &Arc<String>| value.len())
+        .storage()
+        .with_name("foyer")
+        .with_eviction_config(LfuConfig {
+            window_capacity_ratio: 0.1,
+            protected_capacity_ratio: 0.8,
+            cmsketch_eps: 0.001,
+            cmsketch_confidence: 0.9,
+        })
+        .with_device_config(
+            FsDeviceConfigBuilder::new(dir.path())
+                .with_capacity(64 * 1024 * 1024)
+                .with_file_size(4 * 1024 * 1024)
+                .with_align(4 * 1024)
+                .with_io_size(16 * 1024)
+                .build(),
+        )
+        .with_admission_policy(Arc::new(RatedTicketAdmissionPolicy::new(10 * 1024 * 1024)))
+        .with_reinsertion_policy(Arc::new(RatedTicketReinsertionPolicy::new(10 * 1024 * 1024)))
+        .with_flushers(2)
+        .with_reclaimers(2)
+        .with_clean_region_threshold(2)
+        .with_recover_concurrency(4)
+        .with_compression(foyer::Compression::Lz4)
+        .with_runtime_config(
+            RuntimeConfigBuilder::new()
+                .with_thread_name("foyer")
+                .with_worker_threads(4)
+                .build(),
+        )
+        .with_lazy(true)
+        .build()
+        .await?;
+
+    hybrid.insert(
+        42,
+        Arc::new("The answer to life, the universe, and everything.".to_string()),
+    );
+
+    assert_eq!(
+        hybrid.get(&42).await?.unwrap().value().as_ref(),
+        "The answer to life, the universe, and everything."
+    );
+
+    hybrid.entry(20230512, || async {
+        // fetch a value from a remote service
+        let future = async {
+            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())
+        };
+
+        let value = Arc::new(future.await?);
+        Ok((value, CacheContext::default()))
+    });
+
+    Ok(())
+}

examples/memory.rs

@@ -12,7 +12,7 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
-use foyer::memory::CacheBuilder;
+use foyer::CacheBuilder;
 
 fn main() {
     let cache = CacheBuilder::new(16).build();

foyer-memory/Cargo.toml

@@ -15,6 +15,7 @@ normal = ["foyer-workspace-hack"]
 
 [dependencies]
 ahash = "0.8"
+anyhow = "1"
 bitflags = "2"
 cmsketch = "0.2"
 foyer-common = { version = "0.5", path = "../foyer-common" }

foyer-memory/src/cache.rs

@@ -587,7 +587,6 @@ pub enum Entry<K, V, ER, L = DefaultCacheEventListener<K, V>, S = RandomState>
 where
     K: Key + Clone,
     V: Value,
-    ER: std::error::Error,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
 {
@@ -601,7 +600,6 @@ impl<K, V, ER, L, S> From<FifoEntry<K, V, ER, L, S>> for Entry<K, V, ER, L, S>
 where
     K: Key + Clone,
     V: Value,
-    ER: std::error::Error,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
 {
@@ -614,7 +612,6 @@ impl<K, V, ER, L, S> From<LruEntry<K, V, ER, L, S>> for Entry<K, V, ER, L, S>
 where
     K: Key + Clone,
     V: Value,
-    ER: std::error::Error,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
 {
@@ -627,7 +624,6 @@ impl<K, V, ER, L, S> From<LfuEntry<K, V, ER, L, S>> for Entry<K, V, ER, L, S>
 where
     K: Key + Clone,
     V: Value,
-    ER: std::error::Error,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
 {
@@ -640,7 +636,6 @@ impl<K, V, ER, L, S> From<S3FifoEntry<K, V, ER, L, S>> for Entry<K, V, ER, L, S>
 where
     K: Key + Clone,
     V: Value,
-    ER: std::error::Error,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
 {
@@ -653,7 +648,7 @@ impl<K, V, ER, L, S> Future for Entry<K, V, ER, L, S>
 where
     K: Key + Clone,
     V: Value,
-    ER: std::error::Error + From<oneshot::error::RecvError>,
+    ER: From<oneshot::error::RecvError>,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
 {
@@ -680,7 +675,6 @@ impl<K, V, ER, L, S> Entry<K, V, ER, L, S>
 where
     K: Key + Clone,
     V: Value,
-    ER: std::error::Error,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
 {
@@ -717,7 +711,7 @@ where
     where
         F: FnOnce() -> FU,
         FU: Future<Output = std::result::Result<(V, CacheContext), ER>> + Send + 'static,
-        ER: std::error::Error + Send + 'static,
+        ER: Send + 'static,
     {
         match self {
             Cache::Fifo(cache) => Entry::from(cache.entry(key, f)),

foyer-memory/src/generic.rs

@@ -394,7 +394,6 @@ where
     I: Indexer<Key = K, Handle = E::Handle>,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
-    ER: std::error::Error,
 {
     Invalid,
     Hit(GenericCacheEntry<K, V, E, I, L, S>),
@@ -411,7 +410,6 @@ where
     I: Indexer<Key = K, Handle = E::Handle>,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
-    ER: std::error::Error,
 {
     fn default() -> Self {
         Self::Invalid
@@ -427,7 +425,7 @@ where
     I: Indexer<Key = K, Handle = E::Handle>,
     L: CacheEventListener<K, V>,
     S: BuildHasher + Send + Sync + 'static,
-    ER: std::error::Error + From<oneshot::error::RecvError>,
+    ER: From<oneshot::error::RecvError>,
 {
     type Output = std::result::Result<GenericCacheEntry<K, V, E, I, L, S>, ER>;
 
@@ -705,7 +703,7 @@ where
     where
         F: FnOnce() -> FU,
         FU: Future<Output = std::result::Result<(V, CacheContext), ER>> + Send + 'static,
-        ER: std::error::Error + Send + 'static,
+        ER: Send + 'static,
     {
         let hash = self.hash_builder.hash_one(&key);
 

foyer-memory/src/prelude.rs

@@ -16,6 +16,7 @@ pub use crate::{
     cache::{Cache, CacheBuilder, CacheEntry, Entry, EntryState, EvictionConfig},
     context::CacheContext,
     eviction::{fifo::FifoConfig, lfu::LfuConfig, lru::LruConfig, s3fifo::S3FifoConfig},
+    generic::Weighter,
     listener::{CacheEventListener, DefaultCacheEventListener},
     metrics::Metrics,
 };