feat: add S3Fifo eviction for memory (#303)

* Add S3Fifo eviction for memory

* fix: refine s3fifo, fix some bugs

Signed-off-by: MrCroxx <mrcroxx@outlook.com>

* fix: fix license

Signed-off-by: MrCroxx <mrcroxx@outlook.com>

* refactor: expose s3fifo, fix hakari, add s3fifo fuzzy test

Signed-off-by: MrCroxx <mrcroxx@outlook.com>

* bench: add s3fifo to hit ratio bench

Signed-off-by: MrCroxx <mrcroxx@outlook.com>

* test: add s3fifo uts

Signed-off-by: MrCroxx <mrcroxx@outlook.com>

---------

Signed-off-by: MrCroxx <mrcroxx@outlook.com>
Co-authored-by: MrCroxx <mrcroxx@outlook.com>

Author: Ishiihara

foyer-intrusive/src/core/adapter.rs

@@ -117,6 +117,8 @@ pub unsafe trait PriorityAdapter: Adapter {
 /// # Examples
 ///
 /// ```
+/// #![feature(offset_of)]
+///
 /// use foyer_intrusive::{intrusive_adapter, key_adapter};
 /// use foyer_intrusive::core::adapter::{Adapter, KeyAdapter, Link};
 /// use foyer_intrusive::core::pointer::Pointer;
@@ -213,6 +215,8 @@ macro_rules! intrusive_adapter {
 /// # Examples
 ///
 /// ```
+/// #![feature(offset_of)]
+///
 /// use foyer_intrusive::{intrusive_adapter, key_adapter};
 /// use foyer_intrusive::core::adapter::{Adapter, KeyAdapter, Link};
 /// use foyer_intrusive::core::pointer::Pointer;
@@ -282,6 +286,8 @@ macro_rules! key_adapter {
 /// # Examples
 ///
 /// ```
+/// #![feature(offset_of)]
+///
 /// use foyer_intrusive::{intrusive_adapter, priority_adapter};
 /// use foyer_intrusive::core::adapter::{Adapter, PriorityAdapter, Link};
 /// use foyer_intrusive::core::pointer::Pointer;

foyer-intrusive/src/eviction/lfu.rs

@@ -468,7 +468,7 @@ where
                     link
                 }
                 (Some(link_main), Some(link_tiny)) => {
-                    // Eviction from tiny or main depending on whether the tiny handle woould be
+                    // Eviction from tiny or main depending on whether the tiny handle would be
                     // admitted to main cachce. If it would be, evict from main cache, otherwise
                     // from tiny cache.
                     if self.lfu.admit_to_main(link_main.raw(), link_tiny.raw()) {

foyer-intrusive/src/lib.rs

@@ -27,6 +27,8 @@ pub use memoffset::offset_of;
 /// # Examples
 ///
 /// ```
+/// #![feature(offset_of)]
+///
 /// use foyer_intrusive::container_of;
 ///
 /// struct S { x: u32, y: u32 };

foyer-memory/Cargo.toml

@@ -25,6 +25,7 @@ itertools = "0.12"
 libc = "0.2"
 parking_lot = "0.12"
 tokio = { workspace = true }
+
 [dev-dependencies]
 bytesize = "1"
 clap = { version = "4", features = ["derive"] }

foyer-memory/benches/bench_hit_ratio.rs

@@ -16,7 +16,8 @@ use std::sync::Arc;
 
 use ahash::RandomState;
 use foyer_memory::{
-    Cache, DefaultCacheEventListener, FifoCacheConfig, FifoConfig, LfuCacheConfig, LfuConfig, LruCacheConfig, LruConfig,
+    Cache, DefaultCacheEventListener, FifoCacheConfig, FifoConfig, LfuCacheConfig, LfuConfig, LruCacheConfig,
+    LruConfig, S3FifoCacheConfig, S3FifoConfig,
 };
 use rand::{distributions::Distribution, thread_rng};
 
@@ -32,32 +33,32 @@ const OBJECT_POOL_CAPACITY: usize = 16;
 inspired by pingora/tinyufo/benches/bench_hit_ratio.rs
 cargo bench --bench bench_hit_ratio
 
-zif_exp, cache_size             fifo            lru             lfu             moka
-0.90, 0.005                     16.26%          19.22%          32.38%          33.46%
-0.90, 0.01                      22.55%          26.21%          38.55%          37.93%
-0.90, 0.05                      41.10%          45.60%          55.45%          55.26%
-0.90,  0.1                      51.11%          55.72%          63.83%          64.21%
-0.90, 0.25                      66.81%          71.17%          76.21%          77.14%
-1.00, 0.005                     26.64%          31.08%          44.14%          45.61%
-1.00, 0.01                      34.37%          39.13%          50.60%          50.67%
-1.00, 0.05                      54.06%          58.79%          66.79%          66.99%
-1.00,  0.1                      63.12%          67.58%          73.92%          74.38%
-1.00, 0.25                      76.14%          79.92%          83.61%          84.33%
-1.05, 0.005                     32.63%          37.68%          50.24%          51.77%
-1.05, 0.01                      40.95%          46.09%          56.75%          57.15%
-1.05, 0.05                      60.47%          65.06%          72.07%          72.36%
-1.05,  0.1                      68.96%          73.15%          78.52%          78.96%
-1.05, 0.25                      80.42%          83.76%          86.79%          87.42%
-1.10, 0.005                     39.02%          44.52%          56.29%          57.90%
-1.10, 0.01                      47.66%          52.99%          62.64%          63.23%
-1.10, 0.05                      66.60%          70.95%          76.94%          77.25%
-1.10,  0.1                      74.26%          78.09%          82.56%          82.93%
-1.10, 0.25                      84.15%          87.06%          89.54%          90.05%
-1.50, 0.005                     81.19%          85.28%          88.91%          89.94%
-1.50, 0.01                      86.91%          89.87%          92.24%          92.78%
-1.50, 0.05                      94.75%          96.04%          96.95%          97.07%
-1.50,  0.1                      96.65%          97.51%          98.06%          98.15%
-1.50, 0.25                      98.35%          98.81%          99.04%          99.09%
+zif_exp, cache_size             fifo            lru             lfu             s3fifo          moka
+0.90, 0.005                     16.24%          19.22%          32.37%          32.39%          33.50%
+0.90, 0.01                      22.55%          26.20%          38.54%          39.20%          37.92%
+0.90, 0.05                      41.05%          45.56%          55.37%          56.63%          55.25%
+0.90,  0.1                      51.06%          55.68%          63.82%          65.06%          64.20%
+0.90, 0.25                      66.81%          71.17%          76.21%          77.26%          77.12%
+1.00, 0.005                     26.62%          31.10%          44.16%          44.15%          45.62%
+1.00, 0.01                      34.38%          39.17%          50.63%          51.29%          50.72%
+1.00, 0.05                      54.04%          58.76%          66.79%          67.85%          66.89%
+1.00,  0.1                      63.15%          67.60%          73.93%          74.92%          74.38%
+1.00, 0.25                      76.18%          79.95%          83.63%          84.39%          84.38%
+1.05, 0.005                     32.67%          37.71%          50.26%          50.21%          51.85%
+1.05, 0.01                      40.97%          46.10%          56.74%          57.40%          57.09%
+1.05, 0.05                      60.44%          65.03%          72.04%          73.02%          72.28%
+1.05,  0.1                      68.93%          73.12%          78.49%          79.37%          79.00%
+1.05, 0.25                      80.38%          83.73%          86.78%          87.42%          87.41%
+1.10, 0.005                     39.02%          44.50%          56.26%          56.20%          57.90%
+1.10, 0.01                      47.60%          52.93%          62.61%          63.24%          63.05%
+1.10, 0.05                      66.59%          70.95%          76.92%          77.76%          77.27%
+1.10,  0.1                      74.24%          78.07%          82.54%          83.28%          83.00%
+1.10, 0.25                      84.18%          87.10%          89.57%          90.06%          90.08%
+1.50, 0.005                     81.17%          85.27%          88.90%          89.10%          89.89%
+1.50, 0.01                      86.91%          89.87%          92.25%          92.56%          92.79%
+1.50, 0.05                      94.77%          96.04%          96.96%          97.10%          97.07%
+1.50,  0.1                      96.65%          97.50%          98.06%          98.14%          98.15%
+1.50, 0.25                      98.36%          98.81%          99.04%          99.06%          99.09%
 */
 fn cache_hit(cache: Arc<Cache<CacheKey, CacheValue>>, keys: Arc<Vec<CacheKey>>) -> f64 {
     let mut hit = 0;
@@ -131,6 +132,21 @@ fn new_lfu_cache(capacity: usize) -> Arc<Cache<CacheKey, CacheValue>> {
     Arc::new(Cache::lfu(config))
 }
 
+fn new_s3fifo_cache(capacity: usize) -> Arc<Cache<CacheKey, CacheValue>> {
+    let config = S3FifoCacheConfig {
+        capacity,
+        shards: SHARDS,
+        eviction_config: S3FifoConfig {
+            small_queue_capacity_ratio: 0.1,
+        },
+        object_pool_capacity: OBJECT_POOL_CAPACITY,
+        hash_builder: RandomState::default(),
+        event_listener: DefaultCacheEventListener::default(),
+    };
+
+    Arc::new(Cache::s3fifo(config))
+}
+
 fn bench_one(zif_exp: f64, cache_size_percent: f64) {
     print!("{zif_exp:.2}, {cache_size_percent:4}\t\t\t");
     let mut rng = thread_rng();
@@ -141,6 +157,7 @@ fn bench_one(zif_exp: f64, cache_size_percent: f64) {
     let fifo_cache = new_fifo_cache(cache_size);
     let lru_cache = new_lru_cache(cache_size);
     let lfu_cache = new_lfu_cache(cache_size);
+    let s3fifo_cache = new_s3fifo_cache(cache_size);
     let moka_cache = moka::sync::Cache::new(cache_size as u64);
 
     let mut keys = Vec::with_capacity(ITERATIONS);
@@ -170,6 +187,12 @@ fn bench_one(zif_exp: f64, cache_size_percent: f64) {
         move || cache_hit(cache, keys)
     });
 
+    let s3fifo_cache_hit_handle = std::thread::spawn({
+        let cache = s3fifo_cache.clone();
+        let keys = keys.clone();
+        move || cache_hit(cache, keys)
+    });
+
     let moka_cache_hit_handle = std::thread::spawn({
         let cache = moka_cache.clone();
         let keys = keys.clone();
@@ -179,16 +202,18 @@ fn bench_one(zif_exp: f64, cache_size_percent: f64) {
     let fifo_hit_ratio = fifo_cache_hit_handle.join().unwrap();
     let lru_hit_ratio = lru_cache_hit_handle.join().unwrap();
     let lfu_hit_ratio = lfu_cache_hit_handle.join().unwrap();
+    let s3fifo_hit_ratio = s3fifo_cache_hit_handle.join().unwrap();
     let moka_hit_ratio = moka_cache_hit_handle.join().unwrap();
 
     print!("{:.2}%\t\t", fifo_hit_ratio * 100.0);
     print!("{:.2}%\t\t", lru_hit_ratio * 100.0);
     print!("{:.2}%\t\t", lfu_hit_ratio * 100.0);
+    print!("{:.2}%\t\t", s3fifo_hit_ratio * 100.0);
     println!("{:.2}%", moka_hit_ratio * 100.0);
 }
 
 fn bench_zipf_hit() {
-    println!("zif_exp, cache_size\t\tfifo\t\tlru\t\tlfu\t\tmoka");
+    println!("zif_exp, cache_size\t\tfifo\t\tlru\t\tlfu\t\ts3fifo\t\tmoka");
     for zif_exp in [0.9, 1.0, 1.05, 1.1, 1.5] {
         for cache_capacity in [0.005, 0.01, 0.05, 0.1, 0.25] {
             bench_one(zif_exp, cache_capacity);