[Feat] Add MQ, LRU-K and Clock2QPlus bindings

Bump the libCacheSim submodule to the latest develop (dbf8423..373aee9),
which brings three new eviction algorithms, and expose them in Python.

New algorithms:
- LRUK: evicts by largest backward K-distance (k)
- MQ: multi-queue hierarchy with a Qout ghost queue
  (n_queue, lifetime, qout_size_ratio)
- Clock2QPlus: 2Q variant over a Clock main cache
  (fifo_size_ratio, ghost_size_ratio, move_to_main_threshold,
  corr_window_ratio)

Each is wired through export_cache.cpp, cache.py, __init__.py and the
type stubs, covered by the shared parametrized tests, and documented in
both the English and Chinese algorithm reference.

Two fixes to existing bindings found while checking the docs against
the implementation:

- BeladySize was unusable: it emitted the key "n-samples" while the C
  parser only accepts "n-sample", so every construction hit ERROR() and
  aborted the interpreter. It was absent from every test parametrize
  list, which is why this went unnoticed. Added regression tests for
  BeladySize and Belady.
- WTinyLFU's window_size was described as a fraction of the main cache.
  WTinyLFU.c scales the total cache size by it and gives the main cache
  the remainder, so the docstring and both translations now say total.

Also completed the CacheBase type stub, which was missing its
admissioner parameter.

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

Author: 2 people

docs/src/en/examples/simulation.md

@@ -128,6 +128,11 @@ The following cache classes all inherit from `CacheBase` and share a common inte
 
 - *No additional parameters beyond the common arguments*
 
+### LRUK
+**LRU-K** evicts the object with the largest backward K-distance, that is the one whose K-th most recent access is oldest. Objects seen fewer than K times have an infinite backward K-distance and are evicted first in FIFO order, so a single access is not enough to earn a place in the cache.
+
+- `k: int` - Number of recent accesses tracked per object (default: `2`)
+
 ### FIFO
 **First-In, First-Out** evicts objects in order regardless of frequency or recency.
 
@@ -182,11 +187,18 @@ The following cache classes all inherit from `CacheBase` and share a common inte
 
 - *No additional parameters beyond the common arguments*
 
+### MQ
+**Multi-Queue** spreads objects over a hierarchy of LRU queues ordered by access frequency, promoting an object a queue at a time as it is reused and demoting it again if it goes untouched for its lifetime. Eviction always takes the tail of the lowest non-empty queue, and a FIFO ghost queue (`Qout`) remembers the frequency of evicted objects so a quick return restores an object to its former queue.
+
+- `n_queue: int` - Number of queues in the hierarchy, must be in `[1, 64]` (default: `8`)
+- `lifetime: int` - Requests an object may go unaccessed before it is demoted a queue (default: `10000`)
+- `qout_size_ratio: float` - Size of the `Qout` ghost queue as a multiple of the cache size, must be in `(0, 64]` (default: `4.0`)
+
 ### WTinyLFU
 **Window TinyLFU** places a small LRU window in front of a larger main cache, and uses a frequency sketch to decide whether an object leaving the window deserves to displace the main cache's eviction candidate.
 
 - `main_cache: str` - Eviction algorithm used for the main cache (default: `"SLRU"`)
-- `window_size: float` - Size of the LRU window as a fraction of the main cache (default: `0.01`)
+- `window_size: float` - Size of the LRU window as a fraction of the **total** cache size, must be in `[0, 1)`; the main cache receives the remainder (default: `0.01`)
 
 ### LeCaR
 **Learning Cache Replacement** maintains both an LRU and an LFU candidate and picks between them using weights updated by regret minimisation, so it adapts as the workload shifts between recency- and frequency-friendly.
@@ -205,6 +217,14 @@ The following cache classes all inherit from `CacheBase` and share a common inte
 - `init_ref: int` - Initial reference count given to newly admitted objects (default: `0`)
 - `init_ratio_cold: float` - Initial fraction of the cache designated as cold (default: `0.5`)
 
+### Clock2QPlus
+**Clock-2Q+** is a 2Q variant that puts a small FIFO probationary queue in front of a Clock main cache. A ghost queue tracks recently evicted identifiers, and an adaptive correlation window tunes how long an object must survive the FIFO queue before it is considered worth promoting.
+
+- `fifo_size_ratio: float` - Size of the FIFO queue as a fraction of the cache (default: `0.1`)
+- `ghost_size_ratio: float` - Size of the ghost queue as a fraction of the cache (default: `0.9`)
+- `move_to_main_threshold: int` - Number of hits before an object is promoted to the main cache (default: `1`)
+- `corr_window_ratio: float` - Initial size of the correlation window as a fraction of the FIFO queue (default: `0.5`)
+
 ### Cacheus
 **Cacheus** builds on `LeCaR`, adding lightweight adaptation of the learning rate and scan/churn detection so that it degrades gracefully on the workloads where `LeCaR` struggles.
 

docs/src/zh/examples/simulation.md

@@ -121,6 +121,11 @@ for req in reader:
 
 - *除公共参数外无额外参数*
 
+### LRUK
+**LRU-K** 淘汰后向 K 距离（backward K-distance）最大的对象，也就是第 K 次最近访问时间最早的那个。访问次数不足 K 次的对象后向 K 距离视为无穷大，会按 FIFO 顺序被优先淘汰，因此仅被访问一次的对象不足以在缓存中站稳脚跟。
+
+- `k: int` —— 每个对象跟踪的最近访问次数（默认：`2`）
+
 ### FIFO
 **First-In, First-Out（先进先出）** 按进入顺序淘汰对象，不考虑访问频率和时间局部性。
 
@@ -175,11 +180,18 @@ for req in reader:
 
 - *除公共参数外无额外参数*
 
+### MQ
+**Multi-Queue（多队列）** 把对象分布在一组按访问频率排序的 LRU 队列中：对象被重复访问时逐级晋升，在其生命期（lifetime）内未被访问则逐级降级。淘汰总是从最低的非空队列尾部取出，同时用一个 FIFO 幽灵队列（`Qout`）记录被淘汰对象的频率，使得很快再次被访问的对象能够回到原来的队列。
+
+- `n_queue: int` —— 队列层数，取值需在 `[1, 64]` 内（默认：`8`）
+- `lifetime: int` —— 对象未被访问多少个请求后降级一层（默认：`10000`）
+- `qout_size_ratio: float` —— `Qout` 幽灵队列大小相对缓存大小的倍数，取值需在 `(0, 64]` 内（默认：`4.0`）
+
 ### WTinyLFU
 **Window TinyLFU** 在一个较大的主缓存前面放置一个小的 LRU 窗口，并用频率草图（frequency sketch）来判断离开窗口的对象是否值得挤掉主缓存中的淘汰候选者。
 
 - `main_cache: str` —— 主缓存所用的淘汰算法（默认：`"SLRU"`）
-- `window_size: float` —— LRU 窗口大小占主缓存的比例（默认：`0.01`）
+- `window_size: float` —— LRU 窗口大小占**总缓存大小**的比例，取值需在 `[0, 1)` 内，主缓存获得剩余部分（默认：`0.01`）
 
 ### LeCaR
 **Learning Cache Replacement** 同时维护一个 LRU 候选者和一个 LFU 候选者，并用基于后悔最小化（regret minimisation）更新的权重在二者之间做选择，从而能随着负载在偏时间局部性与偏频率之间切换而自适应调整。
@@ -198,6 +210,14 @@ for req in reader:
 - `init_ref: int` —— 新准入对象的初始引用计数（默认：`0`）
 - `init_ratio_cold: float` —— 缓存中初始被划为冷页的比例（默认：`0.5`）
 
+### Clock2QPlus
+**Clock-2Q+** 是 2Q 的变体，在 Clock 主缓存前面放置一个小的 FIFO 试用队列。幽灵队列记录最近被淘汰的对象标识，自适应的关联窗口（correlation window）则用于调节对象需要在 FIFO 队列中存活多久才值得晋升。
+
+- `fifo_size_ratio: float` —— FIFO 队列大小占缓存的比例（默认：`0.1`）
+- `ghost_size_ratio: float` —— 幽灵队列大小占缓存的比例（默认：`0.9`）
+- `move_to_main_threshold: int` —— 对象晋升到主缓存前所需的命中次数（默认：`1`）
+- `corr_window_ratio: float` —— 关联窗口初始大小占 FIFO 队列的比例（默认：`0.5`）
+
 ### Cacheus
 **Cacheus** 在 `LeCaR` 的基础上增加了对学习率的轻量自适应以及扫描/抖动检测，使其在 `LeCaR` 表现不佳的负载上退化得更平缓。
 

libcachesim/__init__.py

@@ -26,16 +26,19 @@
     ARC,
     Clock,
     Random,
+    LRUK,
     # Advanced algorithms
     S3FIFO,
     Sieve,
     LIRS,
     TwoQ,
     SLRU,
+    MQ,
     WTinyLFU,
     LeCaR,
     LFUDA,
     ClockPro,
+    Clock2QPlus,
     Cacheus,
     # Optimal algorithms
     Belady,
@@ -92,16 +95,19 @@
     "ARC",
     "Clock",
     "Random",
+    "LRUK",
     # Advanced cache algorithms
     "S3FIFO",
     "Sieve",
     "LIRS",
     "TwoQ",
     "SLRU",
+    "MQ",
     "WTinyLFU",
     "LeCaR",
     "LFUDA",
     "ClockPro",
+    "Clock2QPlus",
     "Cacheus",
     # Optimal algorithms
     "Belady",

libcachesim/__init__.pyi

@@ -140,7 +140,7 @@ class Cache:
 
 class CacheBase:
     """Base class for all cache implementations"""
-    def __init__(self, _cache: Cache): ...
+    def __init__(self, _cache: Cache, admissioner: Optional["AdmissionerBase"] = None): ...
     def get(self, req: Request) -> bool: ...
     def find(self, req: Request, update_cache: bool = True) -> CacheObject: ...
     def can_insert(self, req: Request) -> bool: ...
@@ -195,6 +195,11 @@ class Random(CacheBase):
         self, cache_size: int | float, default_ttl: int = 25920000, hashpower: int = 24, consider_obj_metadata: bool = False, admissioner: Optional["AdmissionerBase"] = None, reader: Optional[ReaderProtocol] = None
     ): ...
 
+class LRUK(CacheBase):
+    def __init__(
+        self, cache_size: int | float, default_ttl: int = 25920000, hashpower: int = 24, consider_obj_metadata: bool = False, k: int = 2, admissioner: Optional["AdmissionerBase"] = None, reader: Optional[ReaderProtocol] = None
+    ): ...
+
 # Advanced algorithms
 class S3FIFO(CacheBase):
     def __init__(
@@ -221,6 +226,11 @@ class SLRU(CacheBase):
         self, cache_size: int | float, default_ttl: int = 25920000, hashpower: int = 24, consider_obj_metadata: bool = False, admissioner: Optional["AdmissionerBase"] = None, reader: Optional[ReaderProtocol] = None
     ): ...
 
+class MQ(CacheBase):
+    def __init__(
+        self, cache_size: int | float, default_ttl: int = 25920000, hashpower: int = 24, consider_obj_metadata: bool = False, n_queue: int = 8, lifetime: int = 10000, qout_size_ratio: float = 4.0, admissioner: Optional["AdmissionerBase"] = None, reader: Optional[ReaderProtocol] = None
+    ): ...
+
 class WTinyLFU(CacheBase):
     def __init__(
         self, cache_size: int | float, default_ttl: int = 25920000, hashpower: int = 24, consider_obj_metadata: bool = False, main_cache: str = "SLRU", window_size: float = 0.01, admissioner: Optional["AdmissionerBase"] = None, reader: Optional[ReaderProtocol] = None
@@ -241,6 +251,11 @@ class ClockPro(CacheBase):
         self, cache_size: int | float, default_ttl: int = 25920000, hashpower: int = 24, consider_obj_metadata: bool = False, init_ref: int = 0, init_ratio_cold: float = 0.5, admissioner: Optional["AdmissionerBase"] = None, reader: Optional[ReaderProtocol] = None
     ): ...
 
+class Clock2QPlus(CacheBase):
+    def __init__(
+        self, cache_size: int | float, default_ttl: int = 25920000, hashpower: int = 24, consider_obj_metadata: bool = False, fifo_size_ratio: float = 0.1, ghost_size_ratio: float = 0.9, move_to_main_threshold: int = 1, corr_window_ratio: float = 0.5, admissioner: Optional["AdmissionerBase"] = None, reader: Optional[ReaderProtocol] = None
+    ): ...
+
 class Cacheus(CacheBase):
     def __init__(
         self, cache_size: int | float, default_ttl: int = 25920000, hashpower: int = 24, consider_obj_metadata: bool = False, admissioner: Optional["AdmissionerBase"] = None, reader: Optional[ReaderProtocol] = None

libcachesim/cache.py

@@ -17,13 +17,16 @@
     LIRS_init,
     TwoQ_init,
     SLRU_init,
+    LRU_K_init,
+    MQ_init,
     # Advanced algorithms
     S3FIFO_init,
     Sieve_init,
     WTinyLFU_init,
     LeCaR_init,
     LFUDA_init,
     ClockPro_init,
+    Clock2QPlus_init,
     Cacheus_init,
     # Optimal algorithms
     Belady_init,
@@ -231,6 +234,36 @@ def __init__(
         )
 
 
+class LRUK(CacheBase):
+    """LRU-K: evict the object with the largest backward K-distance
+
+    Objects accessed fewer than K times have an infinite backward K-distance
+    and are evicted first in FIFO order.
+
+    Special parameters:
+    k: the number of recent accesses to track (default: 2)
+    """
+
+    def __init__(
+        self,
+        cache_size: int | float,
+        default_ttl: int = 86400 * 300,
+        hashpower: int = 24,
+        consider_obj_metadata: bool = False,
+        k: int = 2,
+        admissioner: AdmissionerBase = None,
+        reader: ReaderProtocol = None,
+    ):
+        cache_specific_params = f"k={k}"
+        super().__init__(
+            _cache=LRU_K_init(
+                _create_common_params(cache_size, default_ttl, hashpower, consider_obj_metadata, reader),
+                cache_specific_params,
+            ),
+            admissioner=admissioner
+        )
+
+
 class FIFO(CacheBase):
     """First In First Out cache (no special parameters)"""
 
@@ -447,12 +480,51 @@ def __init__(
         )
 
 
+class MQ(CacheBase):
+    """Multi-Queue replacement algorithm
+
+    Objects are held in a hierarchy of LRU queues ordered by access frequency;
+    an object that is not re-accessed within its lifetime is demoted to the
+    next lower queue. Evicted objects keep their frequency in a FIFO ghost
+    queue (Qout).
+
+    Special parameters:
+    n_queue: number of queues in the hierarchy, must be in [1, 64] (default: 8)
+    lifetime: number of requests an object may stay in its queue without being
+        accessed before it is demoted (default: 10000)
+    qout_size_ratio: size of the Qout ghost queue relative to the cache size,
+        must be in (0, 64] (default: 4.0)
+    """
+
+    def __init__(
+        self,
+        cache_size: int | float,
+        default_ttl: int = 86400 * 300,
+        hashpower: int = 24,
+        consider_obj_metadata: bool = False,
+        n_queue: int = 8,
+        lifetime: int = 10000,
+        qout_size_ratio: float = 4.0,
+        admissioner: AdmissionerBase = None,
+        reader: ReaderProtocol = None,
+    ):
+        cache_specific_params = f"n-queue={n_queue}, lifetime={lifetime}, Qout-size-ratio={qout_size_ratio}"
+        super().__init__(
+            _cache=MQ_init(
+                _create_common_params(cache_size, default_ttl, hashpower, consider_obj_metadata, reader),
+                cache_specific_params,
+            ),
+            admissioner=admissioner
+        )
+
+
 class WTinyLFU(CacheBase):
     """Window TinyLFU
 
     Special parameters:
     main_cache: the type of the main cache (default: "SLRU")
-    window_size: ratio of the window size to the main cache size (default: 0.01)
+    window_size: ratio of the window LRU size to the total cache size, must be
+        in [0, 1); the main cache receives the remainder (default: 0.01)
     """
 
     def __init__(
@@ -552,6 +624,45 @@ def __init__(
         )
 
 
+class Clock2QPlus(CacheBase):
+    """Clock-2Q+ replacement algorithm
+
+    A 2Q variant that uses a small FIFO probationary queue in front of a Clock
+    main cache, with a ghost queue and an adaptive correlation window.
+
+    Special parameters:
+    fifo_size_ratio: ratio of the FIFO queue size to the total cache size (default: 0.1)
+    ghost_size_ratio: ratio of the ghost queue size to the total cache size (default: 0.9)
+    move_to_main_threshold: number of hits before an object is promoted to the main cache (default: 1)
+    corr_window_ratio: initial ratio of the correlation window to the FIFO queue size (default: 0.5)
+    """
+
+    def __init__(
+        self,
+        cache_size: int | float,
+        default_ttl: int = 86400 * 300,
+        hashpower: int = 24,
+        consider_obj_metadata: bool = False,
+        fifo_size_ratio: float = 0.1,
+        ghost_size_ratio: float = 0.9,
+        move_to_main_threshold: int = 1,
+        corr_window_ratio: float = 0.5,
+        admissioner: AdmissionerBase = None,
+        reader: ReaderProtocol = None,
+    ):
+        cache_specific_params = (
+            f"fifo-size-ratio={fifo_size_ratio}, ghost-size-ratio={ghost_size_ratio}, "
+            f"move-to-main-threshold={move_to_main_threshold}, corr-window-ratio={corr_window_ratio}"
+        )
+        super().__init__(
+            _cache=Clock2QPlus_init(
+                _create_common_params(cache_size, default_ttl, hashpower, consider_obj_metadata, reader),
+                cache_specific_params,
+            ),
+            admissioner=admissioner
+        )
+
+
 class Cacheus(CacheBase):
     """Cacheus algorithm (no special parameters)"""
 
@@ -606,7 +717,8 @@ def __init__(
         admissioner: AdmissionerBase = None,
         reader: ReaderProtocol = None,
     ):
-        cache_specific_params = f"n-samples={n_samples}"
+        # NOTE: the C parser accepts "n-sample" (singular)
+        cache_specific_params = f"n-sample={n_samples}"
         super().__init__(
             _cache=BeladySize_init(
                 _create_common_params(cache_size, default_ttl, hashpower, consider_obj_metadata, reader),

src/export_cache.cpp

@@ -482,6 +482,7 @@ void export_cache(py::module& m) {
   make_cache_wrapper<CAR_init>("CAR_init")(m);
   make_cache_wrapper<Cacheus_init>("Cacheus_init")(m);
   make_cache_wrapper<Clock_init>("Clock_init")(m);
+  make_cache_wrapper<Clock2QPlus_init>("Clock2QPlus_init")(m);
   make_cache_wrapper<ClockPro_init>("ClockPro_init")(m);
   make_cache_wrapper<FIFO_init>("FIFO_init")(m);
   make_cache_wrapper<FIFO_Merge_init>("FIFO_Merge_init")(m);
@@ -495,7 +496,9 @@ void export_cache(py::module& m) {
   make_cache_wrapper<LFUDA_init>("LFUDA_init")(m);
   make_cache_wrapper<LIRS_init>("LIRS_init")(m);
   make_cache_wrapper<LRU_init>("LRU_init")(m);
+  make_cache_wrapper<LRU_K_init>("LRU_K_init")(m);
   make_cache_wrapper<LRU_Prob_init>("LRU_Prob_init")(m);
+  make_cache_wrapper<MQ_init>("MQ_init")(m);
   make_cache_wrapper<nop_init>("nop_init")(m);
 
   make_cache_wrapper<QDLP_init>("QDLP_init")(m);