feat: Add S4-FIFO algo (#335)

* feat: Add S4-FIFO algo

* fix(s4fifo): address review findings on child sizing, warmup and feature tracking

Five fixes from the review of the S4-FIFO PR:

- Size each sub-FIFO's hash table from its own byte size, capped by any
  requested --hashpower, rather than inheriting the parent's. Previously a
  single S4FIFO allocated three full-size tables; at a 1GiB cache size peak
  RSS drops from 527MiB to 338MiB, matching S3FIFO's 340MiB, with an
  identical miss ratio.

- Leave WARMUP on the first capacity eviction instead of when occupancy
  reaches cache_size. Eviction runs before occupancy can exceed the limit,
  so the old test needed the trace to fill the cache exactly and in practice
  never fired: on cloudPhysicsIO the learned mode spent the whole trace in
  warmup and never predicted a configuration.

- Only pre-scan the trace for its request count when an algorithm actually
  reads it. Every cachesim and MRC run paid for a full extra pass, which on
  a txt or zstd trace costs as much as the simulation (LRU on a 1M-request
  csv: 0.48s -> 0.33s).

- Stop double-counting one-hit-wonders: S4FIFO_track_ghost_insert already
  records them, so the extra call doubled one_hit_count whenever a ghost
  FIFO was configured.

- Stamp clock reinsertions in the main FIFO with S4FIFO_track_main_insert.
  A reinserted object takes a fresh tail position but kept a stale
  insert_seq, skewing the main queue's hit-position histogram.

The eviction path itself is unchanged: the static heuristic still matches
S3-FIFO exactly, and the full test suite passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(s4fifo): propagate n_total_req through cloning, and fix ghost-queue tracking

Second round of review fixes.

- Adding n_total_req grew common_cache_params_t from 24 to 32 bytes, but
  clone_cache and create_cache_with_new_size still asserted the old size, so
  any assertion-enabled build aborted in simulate_at_multi_sizes (testSimulator
  exited 134 under -DCMAKE_BUILD_TYPE=Debug). That assert was a tripwire for
  exactly the bug that had happened - both functions rebuild the struct field
  by field and were silently dropping the new field - so copy n_total_req in
  both, retain it on cache_t to copy it from, and make the tripwire a
  _Static_assert. As a runtime assert it was compiled out of release builds and
  so never fired in CI; now it breaks the build for everyone, which is the
  point. Verified it still trips by adding a scratch field.

- MINISIM hardcoded n_total_req = 0 even though it had just counted the trace,
  so the default fractional feature-collect-reqs fell back to a fixed 10000 and
  MRC disagreed with cachesim. Pass sampled_cnt - not n_req_, since spatial
  sampling drops requests before the cache sees them, so sampled_cnt is what
  cache->n_req climbs to. On twitter_cluster52 at wss 0.055 the miss ratio goes
  0.216370 -> 0.205729, and the curve now matches cachesim exactly (0.299438
  and 0.185243 against 0.2994 and 0.1852).

- S4FIFO_track_ghost_insert returned early outside a collection window, so
  objects inserted during warmup or between windows kept a zero insert_seq and
  ghost_insert_seq froze. A later hit inside a window was then scored against a
  stamp from a different sequence. Always stamp and advance, as the small and
  main helpers do, and gate only the per-window one-hit counter. Costs ~1%
  throughput (4.82 -> 4.78 MQPS) for the extra lookup.

- record_ghost_removal ran on every ghost hit, but with a positive
  ghost-to-main-threshold the entry deliberately stays in the queue. The
  tracker subtracts recorded removals as holes from later hit positions, so
  this invented holes that were never there; record it only in the branch that
  actually removes.

Release and Debug both build clean and pass all 10 tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: haochengxia

CMakeLists.txt

@@ -26,6 +26,7 @@ option(SUPPORT_TTL "whether support TTL" OFF)
 option(OPT_SUPPORT_ZSTD_TRACE "whether support zstd trace" ON)
 option(ENABLE_LRB "enable LRB" OFF)
 option(ENABLE_3L_CACHE "enable 3LCache" OFF)
+option(ENABLE_S4FIFO "enable S4FIFO" OFF)
 option(BUILD_SHARED_LIBS "build shared library" ON)
 set(LOG_LEVEL "default" CACHE STRING "change the logging level")
 set_property(CACHE LOG_LEVEL PROPERTY STRINGS ERROR WARN INFO DEBUG VERBOSE DEFAULT)
@@ -192,6 +193,11 @@ foreach(FEATURE ENABLE_LRB ENABLE_3L_CACHE)
         add_compile_definitions(${FEATURE}=1)
     endif()
 endforeach()
+
+if(ENABLE_S4FIFO)
+    add_compile_definitions(ENABLE_S4FIFO=1)
+endif()
+
 # Put binary in bin directory
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
 
@@ -202,6 +208,7 @@ message(STATUS "CMAKE_CXX_FLAGS_RELEASE ${CMAKE_CXX_FLAGS_RELEASE}")
 message(STATUS "SUPPORT TTL ${SUPPORT_TTL}, USE_HUGEPAGE ${USE_HUGEPAGE}")
 message(STATUS "LOGLEVEL ${LOG_LEVEL}, ENABLE_GLCACHE ${ENABLE_GLCACHE}")
 message(STATUS "ENABLE_LRB ${ENABLE_LRB}, ENABLE_3L_CACHE ${ENABLE_3L_CACHE}")
+message(STATUS "ENABLE_S4FIFO ${ENABLE_S4FIFO}")
 message(STATUS "OPT_SUPPORT_ZSTD_TRACE ${OPT_SUPPORT_ZSTD_TRACE}")
 
 message(STATUS "<<++=====------------------\\/------------------=====++>>")

README.md

@@ -65,6 +65,7 @@ The name in `code` is what you pass to `cachesim` on the command line (names are
 * [WTinyLFU](/libCacheSim/cache/eviction/WTinyLFU.c) `wtinylfu`
 * [QD-LP](/libCacheSim/cache/eviction/QDLP.c) `qdlp`
 * [S3-FIFO](/libCacheSim/cache/eviction/S3FIFO.c) `s3fifo`, [S3-FIFOd](/libCacheSim/cache/eviction/S3FIFOd.c) `s3fifod`
+* [S4-FIFO](/libCacheSim/cache/eviction/S4FIFO/S4FIFO.c) `s4fifo` — build with `-DENABLE_S4FIFO=ON`
 * [Sieve](/libCacheSim/cache/eviction/Sieve.c) `sieve`
 
 ### Admission algorithms

libCacheSim/bin/MRC/parser_mini.c

@@ -329,13 +329,25 @@ void parse_mini_cmd(int argc, char *argv[], struct MINI_arguments *args) {
    * the working set size **/
   conv_cache_sizes(args->args[4], args->args[5], args);
 
+  /* lets an eviction parameter be given as a fraction of the trace rather
+   * than an absolute request count - see the same call in cachesim, which
+   * also explains why only the algorithms that read it pay for the scan. */
+  int64_t n_total_req = 0;
+  for (int i = 0; i < args->n_eviction_algo; i++) {
+    if (cache_needs_n_total_req(args->eviction_algo[i])) {
+      n_total_req = get_num_of_req(args->reader);
+      reset_reader(args->reader);
+      break;
+    }
+  }
+
   for (int i = 0; i < args->n_eviction_algo; i++) {
     for (int j = 0; j < args->n_cache_size; j++) {
       int idx = i * args->n_cache_size + j;
-      args->caches[idx] =
-          create_cache(args->trace_path, args->eviction_algo[i],
-                       args->cache_sizes[j], args->eviction_params,
-                       args->consider_obj_metadata, DEFAULT_HASHPOWER);
+      args->caches[idx] = create_cache(
+          args->trace_path, args->eviction_algo[i], args->cache_sizes[j],
+          args->eviction_params, args->consider_obj_metadata, DEFAULT_HASHPOWER,
+          n_total_req);
 
       if (args->admission_algo != NULL) {
         args->caches[idx]->admissioner =

libCacheSim/bin/cachesim/cache_init.h

@@ -17,6 +17,20 @@ extern "C" {
 /* log2 of the hash table size; 24 gives 16M entries */
 #define DEFAULT_HASHPOWER 24
 
+/**
+ * @brief does this algorithm read common_cache_params_t.n_total_req?
+ *
+ * Supplying it means counting the trace's requests before the simulation
+ * starts, which on a txt or zstd trace is a full extra pass — as expensive as
+ * the simulation itself. Only the algorithms listed here accept a parameter
+ * expressed as a fraction of the trace (s4fifo's feature-collect-reqs, whose
+ * default is fractional), so everything else should not pay for the pre-scan.
+ */
+static inline bool cache_needs_n_total_req(const char *eviction_algo) {
+  return strcasecmp(eviction_algo, "s4fifo") == 0 ||
+         strcasecmp(eviction_algo, "s4-fifo") == 0;
+}
+
 /**
  * @brief create a cache for the CLI, given the algorithm name
  *
@@ -32,12 +46,14 @@ static inline cache_t *create_cache(const char *trace_path,
                                     const uint64_t cache_size,
                                     const char *eviction_params,
                                     const bool consider_obj_metadata,
-                                    const int hashpower) {
+                                    const int hashpower,
+                                    const int64_t n_total_req) {
   common_cache_params_t cc_params = {
       .cache_size = cache_size,
       .default_ttl = 86400 * 300,
       .hashpower = hashpower,
       .consider_obj_metadata = consider_obj_metadata,
+      .n_total_req = n_total_req,
   };
   cache_t *cache;
 

libCacheSim/bin/cachesim/cli_parser.c

@@ -356,12 +356,29 @@ void parse_cmd(int argc, char *argv[], struct arguments *args) {
    * the working set size **/
   conv_cache_sizes(args->args[3], args);
 
+  /* so that an eviction parameter can be given as a fraction of the trace
+   * (e.g. s4fifo's feature-collect-reqs) rather than an absolute request
+   * count. Cheap for binary traces (derived from the file size); for txt
+   * and zstd traces it counts on a cloned reader, leaving this one
+   * untouched - reset anyway so nothing downstream depends on that. Only
+   * the algorithms that read it pay for the scan; for everything else it
+   * would be a wasted pass over the whole trace. */
+  int64_t n_total_req = 0;
+  for (int i = 0; i < args->n_eviction_algo; i++) {
+    if (cache_needs_n_total_req(args->eviction_algo[i])) {
+      n_total_req = get_num_of_req(args->reader);
+      reset_reader(args->reader);
+      break;
+    }
+  }
+
   for (int i = 0; i < args->n_eviction_algo; i++) {
     for (int j = 0; j < args->n_cache_size; j++) {
       int idx = i * args->n_cache_size + j;
       args->caches[idx] = create_cache(
           args->trace_path, args->eviction_algo[i], args->cache_sizes[j],
-          args->eviction_params, args->consider_obj_metadata, args->hashpower);
+          args->eviction_params, args->consider_obj_metadata, args->hashpower,
+          n_total_req);
 
       if (args->admission_algo != NULL) {
         args->caches[idx]->admissioner =

libCacheSim/bin/traceUtils/traceFilterMain.cpp

@@ -78,7 +78,8 @@ int main(int argc, char *argv[]) {
       .cache_size = static_cast<uint64_t>(args.cache_size),
       .default_ttl = 86400 * 300,
       .hashpower = 24,
-      .consider_obj_metadata = false};
+      .consider_obj_metadata = false,
+      .n_total_req = 0};
 
   if (strcasecmp(args.cache_name, "LRU") == 0) {
     args.cache = LRU_init(cc_params, NULL);

libCacheSim/cache/CMakeLists.txt

@@ -92,12 +92,22 @@ endif()
 
 # 3L Cache
 if (ENABLE_3L_CACHE)
-    set (eviction_sources_cpp ${eviction_sources_cpp} 
+    set (eviction_sources_cpp ${eviction_sources_cpp}
         eviction/3LCache/ThreeLCache_Interface.cpp
         eviction/3LCache/ThreeLCache.cpp
         )
 endif()
 
+# S4FIFO: plain C throughout, including its model, so no ML runtime
+# dependency and no eviction_sources_cpp entry.
+if (ENABLE_S4FIFO)
+    set(eviction_sources_c ${eviction_sources_c}
+        eviction/S4FIFO/S4FIFO.c
+        eviction/S4FIFO/S4FIFO_predictor.c
+        eviction/S4FIFO/S4FIFO_model_real.c
+        )
+endif()
+
 # GLCache
 if (ENABLE_GLCACHE)
     set(eviction_sources_c 

libCacheSim/cache/cache.c

@@ -17,6 +17,21 @@ extern "C" {
  *LRU and FIFO
  **/
 
+/* The two functions below rebuild a common_cache_params_t field by field, so
+ * a field added to that struct is silently dropped unless they are updated
+ * too. This is the tripwire for that: it breaks the build when the struct
+ * grows, pointing at the initializer that needs the new field.
+ *
+ * It used to be `assert(sizeof(cc_params) == 24)`, which caught nothing in a
+ * release build (NDEBUG) and aborted every simulate_at_multi_sizes() run in a
+ * debug one. A static assertion fires for everybody, at compile time, which is
+ * what a tripwire like this is for. Update the expected size together with the
+ * initializers. */
+#define CHECK_COMMON_CACHE_PARAMS_COPIED_ABOVE()                     \
+  _Static_assert(sizeof(common_cache_params_t) == 32,                \
+                 "common_cache_params_t changed size: copy the new " \
+                 "field in the initializer above, then update this size")
+
 /**
  * @brief this function is called by all eviction algorithms to initialize the
  * cache
@@ -37,6 +52,7 @@ cache_t *cache_struct_init(const char *const cache_name,
     cache->init_params[CACHE_INIT_PARAMS_LEN - 1] = '\0';
   }
   cache->cache_size = params.cache_size;
+  cache->n_total_req = params.n_total_req;
   cache->eviction_params = NULL;
   cache->admissioner = NULL;
   cache->prefetcher = NULL;
@@ -95,8 +111,9 @@ cache_t *clone_cache(const cache_t *old_cache) {
       .hashpower = old_cache->hashtable->hashpower,
       .default_ttl = old_cache->default_ttl,
       .consider_obj_metadata = old_cache->obj_md_size == 0 ? false : true,
+      .n_total_req = old_cache->n_total_req,
   };
-  assert(sizeof(cc_params) == 24);
+  CHECK_COMMON_CACHE_PARAMS_COPIED_ABOVE();
   cache_t *cache = old_cache->cache_init(cc_params, old_cache->init_params);
   if (old_cache->admissioner != NULL) {
     cache->admissioner = old_cache->admissioner->clone(old_cache->admissioner);
@@ -121,8 +138,9 @@ cache_t *create_cache_with_new_size(const cache_t *old_cache,
       .hashpower = old_cache->hashtable->hashpower,
       .default_ttl = old_cache->default_ttl,
       .consider_obj_metadata = old_cache->obj_md_size == 0 ? false : true,
+      .n_total_req = old_cache->n_total_req,
   };
-  assert(sizeof(cc_params) == 24);
+  CHECK_COMMON_CACHE_PARAMS_COPIED_ABOVE();
   cache_t *cache = old_cache->cache_init(cc_params, old_cache->init_params);
   if (old_cache->admissioner != NULL) {
     cache->admissioner = old_cache->admissioner->clone(old_cache->admissioner);

libCacheSim/cache/cacheAlgoRegistry.c

@@ -67,6 +67,10 @@ static const cache_algo_entry_t g_cache_algos[] = {
     {"s3fifo", S3FIFO_init},
     {"s3fifod", S3FIFOd_init},
     {"s3fifov0", S3FIFOv0_init},
+#ifdef ENABLE_S4FIFO
+    {"s4-fifo", S4FIFO_init},
+    {"s4fifo", S4FIFO_init},
+#endif
     {"sieve", Sieve_init},
     {"size", Size_init},
     {"slru", SLRU_init},