Bindings for cache admission policies

CMakeLists.txt

@@ -252,6 +252,7 @@ include_directories(${MAIN_PROJECT_SOURCE_DIR}/libCacheSim/bin)
 set(PYTHON_MODULE_SOURCES
  src/export.cpp
  src/export_cache.cpp
+ src/export_admissioner.cpp
  src/export_reader.cpp
  src/export_analyzer.cpp
  src/export_misc.cpp

docs/src/en/examples/plugins.md

@@ -1,8 +1,10 @@
 # Plugin System
 
-We enable user add any customized cache via libCacheSim's plugin system.
+## PluginCache
 
-With user-defined sive python hook functions, 
+We enable users to add any customized cache via libCacheSim's plugin system.
+
+With user-defined python hook functions,
 
 ```c++
  py::function cache_init_hook;
@@ -15,8 +17,7 @@ With user-defined sive python hook functions,
 
 We can simulate and determine the cache eviction behavior from the python side.
 
-Here is the signature requirement for these hook functions.
-
+Here are the signature requirements for these hook functions.
 ```python
 def cache_init_hook(ccparams: CommonCacheParams) -> CustomizedCacheData: ...
 def cache_hit_hook(data: CustomizedCacheData, req: Request) -> None: ...
@@ -25,3 +26,32 @@ def cache_eviction_hook(data: CustomizedCacheData, req: Request) -> int | str: .
 def cache_remove_hook(data: CustomizedCacheData, obj_id: int | str) ->: ...
 def cache_free_hook(data: CustomizedCacheData) ->: ...
 ```
+
+- **Note:** `CustomizedCacheData` is not a type provided by the library. It simply represents what ever object the user decides to return from `cache_init_hook` and pass to the other hook functions as `data`.
+
+## PluginAdmissioner
+
+We enable users to define their own admission policies via libCacheSim's plugin system, which can be used in conjunction with existing cache implementations (e.g., `LRU`, `S3FIFO`).
+
+With user-defined python hook functions:
+
+```c++
+ py::function admissioner_init_hook;
+ py::function admissioner_admit_hook;
+ py::function admissioner_update_hook;
+ py::function admissioner_clone_hook;
+ py::function admissioner_free_hook;
+```
+
+We have complete control over which objects are admitted into the underlying cache conveniently from Python.
+
+Here are the signature requirements for these hook functions.
+```python
+def admissioner_init_hook() -> CustomizedAdmissionerData: ...
+def admissioner_admit_hook(data: CustomizedAdmissionerData, req: Request) -> bool: ...
+def admissioner_update_hook(data: CustomizedAdmissionerData, req: Request, cache_size: int) -> None: ...
+def admissioner_clone_hook(data: CustomizedAdmissionerData) -> AdmissionerBase: ...
+def admissioner_free_hook(data: CustomizedAdmissionerData) -> None: ...
+```
+
+- **Note:** `CustomizedAdmissionerData` is not a type provided by the library. It simply represents what ever object the user decides to return from `admissioner_init_hook` and pass to the other hook functions as `data`.

docs/src/en/examples/simulation.md

@@ -1,3 +1,176 @@
 # Cache Simulation
 
-[TBD]
+## Basic Usage
+
+The cache classes are the core of cache simulation. When an instance of a cache is creates (e.g., `LRU`, `S3FIFO`), we can configure the cache size and any cache-specific parameters such as promotion thresholds.
+
+```py
+import libcachesim as lcs
+
+# Initialize cache
+cache = lcs.S3FIFO(
+ cache_size=1024 * 1024,
+ # Cache specific parameters
+ small_size_ratio=0.2,
+ ghost_size_ratio=0.8,
+ move_to_main_threshold=2,
+)
+```
+
+Admission policies are optional - if none is provided, the cache will simply admit all objects according to the replacement policy. An admissioner (e.g., `BloomFilterAdmissioner`) can be placed infront of the cache by specifying the `admissioner` argument.
+
+```py
+import libcachesim as lcs
+
+# Initialize admissioner
+admissioner = lcs.BloomFilterAdmissioner()
+
+# Step 2: Initialize cache
+cache = lcs.S3FIFO(
+ cache_size=1024 * 1024,
+ # Cache specific parameters
+ small_size_ratio=0.2,
+ ghost_size_ratio=0.8,
+ move_to_main_threshold=2,
+ # Optionally provide admissioner
+ admissioner=admissioner,
+)
+```
+
+Then we can run cache simulations using real world workloads leveraging trace readers (see [Trace Reader](reader.md) for more on using `TraceReader`):
+
+```py
+# Process entire trace efficiently (C++ backend)
+req_miss_ratio, byte_miss_ratio = cache.process_trace(reader)
+print(f"Request miss ratio: {req_miss_ratio:.4f}, Byte miss ratio: {byte_miss_ratio:.4f}")
+```
+
+## Caches
+The following cache classes all inherit from `CacheBase` and share a common interface, sharing the following arguments in all cache classes unless otherwise specified:
+
+- `cache_size: int`
+- `default_ttl: int` (optional)
+- `hashpower: int` (optional)
+- `consider_obj_metadata: bool` (optional)
+- `admissioner: AdmissionerBase` (optional)
+
+### LHD
+**Lest Hit Density** evicts objects based on each objects expected hits-per-space-consumed (hit density).
+
+- *No additional parameters beyond the common arguments*
+
+### LRU
+**Least Recently Used** evicts the object that has not been accessed for the longest time.
+
+- *No additional parameters beyond the common arguments*
+
+### FIFO
+**First-In, First-Out** evicts objects in order regardless of frequency or recency.
+
+- *No additional parameters beyond the common arguments*
+
+### LFU
+**Least Frequently Used** evicts the object with the lowest access frequency.
+
+- *No additional parameters beyond the common arguments*
+
+### Arc
+**Adaptive Replacement Cache** a hybrid algorithm which balances recency and frequency.
+
+- *No additional parameters beyond the common arguments*
+
+### Clock
+**Clock** is an low-complexity approximation of `LRU`.
+
+- `int_freq: int` - Initial frequency counter value which is used for new objects (default: `0`)
+- `n_bit_counter: int` - Number of bits used for the frequency counter (default: `1`)
+
+### Random
+**Random** evicts objects at random.
+
+- *No additional parameters beyond the common arguments*
+
+### S3FIFO
+[TBD]
+
+### Sieve
+[TBD]
+
+### LIRS
+[TBD]
+
+### TwoQ
+[TBD]
+
+### SLRU
+[TBD]
+
+### WTinyLFU
+[TBD]
+
+### LeCaR
+[TBD]
+
+### LFUDA
+[TBD]
+
+### ClockPro
+[TBD]
+
+### Cacheus
+[TBD]
+
+### Belady
+[TBD]
+
+### BeladySize
+[TBD]
+
+### LRUProb
+[TBD]
+
+### FlashProb
+[TBD]
+
+### GDSF
+[TBD]
+
+### Hyperbolic
+[TBD]
+
+### ThreeLCache
+[TBD]
+
+### GLCache
+[TBD]
+
+### LRB
+[TBD]
+
+## Admission Policies
+
+### BloomFilterAdmissioner
+Uses a Bloom filter to decide admissions based on how many times an object has been seen.
+
+- *No parameters*
+
+### ProbAdmissioner
+Admits objects with a fixed probability.
+
+- `prob: float` (optional) - Probability of admitting an object (default: `0.5`)
+
+### SizeAdmissioner
+Admits objects only if they are below a specified size threshold.
+
+- `size_threshold: int` (optional) - Maximum allowed object size (in bytes) for admission (default: `9_223_372_036_854_775_807`, or `INT64_MAX`)
+
+### SizeProbabilisticAdmissioner
+Admits objects with a probability that decreases with object size, favoring smaller objects over large.
+
+- `exponent: float` (optional) - Exponent controlling how aggressively larger objects are filtered out (default: `1e-6`)
+
+### AdaptSizeAdmissioner
+Implements **AdaptSize**, a feedback-driven policy that periodically adjusts its size threshold.
+
+- `max_iteration: int` (optional) - Maximum number of iterators for parameter tuning (default: `15`)
+- `reconf_interval: int` (optional) - Interval (with respect to request count) at which the threshold is re-evaluated (default: `30_000`)

examples/admission/bloomfilter.py

@@ -0,0 +1,31 @@
+from libcachesim import BloomFilterAdmissioner, SyntheticReader, LRU
+
+BloomFilter = BloomFilterAdmissioner()
+lru_without_admission = LRU(
+ cache_size=1024,
+ # admissioner=BloomFilter
+)
+lru_with_admission = LRU(
+ cache_size=1024,
+ admissioner=BloomFilter
+)
+
+reader = SyntheticReader(
+ num_of_req=100_000,
+ num_objects=10_000,
+ obj_size=100,
+ alpha=0.8,
+ dist="zipf",
+)
+
+without_admission_hits = 0
+with_admission_hits = 0
+
+for req in reader:
+ if lru_without_admission.get(req):
+ without_admission_hits += 1
+ if lru_with_admission.get(req):
+ with_admission_hits += 1
+
+print(f'Obtained {without_admission_hits} without using cache admission')
+print(f'Obtained {with_admission_hits} using cache admission')

examples/admission/plugin_admissioner.py

@@ -0,0 +1,65 @@
+from libcachesim import PluginAdmissioner, SyntheticReader, LRU
+import random
+
+'''
+A toy example where we admit ten percent of all requests
+at random. The admit rate is tracked and printed in the
+free hook to serve as a final sanity check.
+'''
+
+
+class AdmissionerStats:
+ admitted_requests: int = 0
+ total_requests: int = 0
+
+
+def init_hook():
+ return AdmissionerStats()
+
+
+def admit_hook(data, request):
+ admit = random.randint(1, 10) == 5
+ if admit:
+ data.admitted_requests += 1
+ data.total_requests += 1
+ return admit
+
+
+def clone_hook():
+ raise NotImplementedError("Cloning for this plugin admissioner is not supported.")
+
+
+def update_hook(data, request, cs):
+ pass
+
+
+def free_hook(data):
+ print(f'Admit rate: {100 * data.admitted_requests / data.total_requests}%')
+
+
+custom_admissioner = PluginAdmissioner(
+ "AdmitTenPercent",
+ init_hook,
+ admit_hook,
+ clone_hook,
+ update_hook,
+ free_hook,
+)
+lru_cache = LRU(
+ cache_size=1024,
+ admissioner=custom_admissioner
+)
+
+reader = SyntheticReader(
+ num_of_req=100_000,
+ num_objects=10_000,
+ obj_size=100,
+ alpha=0.8,
+ dist="zipf",
+)
+
+for req in reader:
+ lru_cache.get(req)
+
+# Invokes free_hook, percentage should be ~10%
+del lru_cache

libcachesim/__init__.py

@@ -56,6 +56,16 @@
  PluginCache,
 )
 
+from .admissioner import (
+ BloomFilterAdmissioner,
+ ProbAdmissioner,
+ SizeAdmissioner,
+ SizeProbabilisticAdmissioner,
+ AdaptSizeAdmissioner,
+ PluginAdmissioner,
+ AdmissionerBase,
+)
+
 from .trace_reader import TraceReader
 from .trace_analyzer import TraceAnalyzer
 from .synthetic_reader import SyntheticReader, create_zipf_requests, create_uniform_requests
@@ -110,6 +120,15 @@
  "LRB",
  # Plugin cache
  "PluginCache",
+ # Admission algorithms
+ "BloomFilterAdmissioner",
+ "ProbAdmissioner",
+ "SizeAdmissioner",
+ "SizeProbabilisticAdmissioner",
+ "AdaptSizeAdmissioner",
+ "PluginAdmissioner",
+ # Admissioner base class
+ "AdmissionerBase",
  # Readers and analyzers
  "TraceReader",
  "TraceAnalyzer",