Feat: support plugin in python

Author: haochengxia

libCacheSim-python/README.md

@@ -22,6 +22,8 @@ python -m pytest .
 
 ## Usage
 
+### Basic Cache Usage
+
 ```python
 import libcachesim as cachesim
 
@@ -38,7 +40,155 @@ hit = cache.get(req)
 print(f"Cache hit: {hit}")
 ```
 
-## Features
+### Custom Cache Policies
+
+The Python binding supports custom cache replacement algorithms using Python function hooks - no C/C++ compilation required:
+
+#### Python Hook Cache
+
+Define custom cache policies using pure Python functions:
+
+```python
+import libcachesim as cachesim
+from collections import OrderedDict
+
+# Create a Python hook-based cache
+cache = cachesim.PythonHookCachePolicy(cache_size=1024*1024, cache_name="MyLRU")
+
+# Define LRU policy hooks
+def init_hook(cache_size):
+    return OrderedDict()  # Track access order
+
+def hit_hook(lru_dict, obj_id, obj_size):
+    lru_dict.move_to_end(obj_id)  # Move to end (most recent)
+
+def miss_hook(lru_dict, obj_id, obj_size):
+    lru_dict[obj_id] = True  # Add to end
+
+def eviction_hook(lru_dict, obj_id, obj_size):
+    return next(iter(lru_dict))  # Return least recent
+
+def remove_hook(lru_dict, obj_id):
+    lru_dict.pop(obj_id, None)
+
+# Set the hooks
+cache.set_hooks(init_hook, hit_hook, miss_hook, eviction_hook, remove_hook)
+
+# Use it like any other cache
+req = cachesim.Request()
+req.obj_id = 1
+req.obj_size = 100
+hit = cache.get(req)
+```
+
+### Available Cache Algorithms
+
+The following built-in cache algorithms are available:
+
+- **FIFO**: First-In-First-Out
+- **LRU**: Least Recently Used
+- **ARC**: Adaptive Replacement Cache
+- **Clock**: Clock algorithm
+- **S3FIFO**: Simple, Fast, Fair FIFO
+- **Sieve**: Sieve cache algorithm
+- **TinyLFU**: TinyLFU with window
+- **TwoQ**: Two-Queue algorithm
+- **LRB**: Learning-based cache (if enabled)
+- **ThreeLCache**: Three-level cache (if enabled)
+
+Each algorithm can be used similarly:
+
+```python
+# Examples of different cache algorithms
+lru_cache = cachesim.LRU(cache_size=1024*1024)
+arc_cache = cachesim.ARC(cache_size=1024*1024)
+s3fifo_cache = cachesim.S3FIFO(cache_size=1024*1024)
+```
+
+### Custom Cache Implementation Example
+
+Here's a complete example implementing a custom FIFO cache using Python hooks:
+
+```python
+import libcachesim as cachesim
+from collections import deque
+
+# Create a custom FIFO cache
+cache = cachesim.PythonHookCachePolicy(cache_size=1024, cache_name="CustomFIFO")
+
+def init_hook(cache_size):
+    return deque()  # Use deque for FIFO order
+
+def hit_hook(fifo_queue, obj_id, obj_size):
+    pass  # FIFO doesn't reorder on hit
+
+def miss_hook(fifo_queue, obj_id, obj_size):
+    fifo_queue.append(obj_id)  # Add to end of queue
+
+def eviction_hook(fifo_queue, obj_id, obj_size):
+    return fifo_queue[0]  # Return first item (oldest)
+
+def remove_hook(fifo_queue, obj_id):
+    if fifo_queue and fifo_queue[0] == obj_id:
+        fifo_queue.popleft()
+
+# Set the hooks
+cache.set_hooks(init_hook, hit_hook, miss_hook, eviction_hook, remove_hook)
+
+# Test the cache
+req = cachesim.Request()
+req.obj_id = 1
+req.obj_size = 100
+hit = cache.get(req)
+print(f"Cache hit: {hit}")  # Should be False (miss)
+```
+
+### Testing and Validation
+
+To ensure your custom cache implementation is correct, you can compare it against the built-in implementations:
+
+```python
+import libcachesim as cachesim
+
+# Test your custom cache against the built-in LRU
+def test_custom_vs_builtin():
+    cache_size = 1024
+
+    # Your custom LRU implementation
+    custom_cache = cachesim.PythonHookCachePolicy(cache_size, "CustomLRU")
+    # ... set up your LRU hooks here ...
+
+    # Built-in LRU for comparison
+    builtin_cache = cachesim.LRU(cache_size)
+
+    # Test with same request sequence
+    test_requests = [(1, 100), (2, 100), (3, 100), (1, 100)]
+
+    for obj_id, obj_size in test_requests:
+        req1 = cachesim.Request()
+        req1.obj_id = obj_id
+        req1.obj_size = obj_size
+
+        req2 = cachesim.Request()
+        req2.obj_id = obj_id
+        req2.obj_size = obj_size
+
+        custom_result = custom_cache.get(req1)
+        builtin_result = builtin_cache.get(req2)
+
+        assert custom_result == builtin_result, f"Mismatch at obj_id {obj_id}"
+        print(f"obj_id {obj_id}: {'HIT' if custom_result else 'MISS'} ✓")
+```
+
+### Hook Function Reference
+
+When implementing `PythonHookCachePolicy`, you need to provide these hook functions:
+
+- **`init_hook(cache_size: int) -> Any`**: Initialize and return plugin data structure
+- **`hit_hook(plugin_data: Any, obj_id: int, obj_size: int) -> None`**: Handle cache hits
+- **`miss_hook(plugin_data: Any, obj_id: int, obj_size: int) -> None`**: Handle cache misses
+- **`eviction_hook(plugin_data: Any, obj_id: int, obj_size: int) -> int`**: Return object ID to evict
+- **`remove_hook(plugin_data: Any, obj_id: int) -> None`**: Clean up when object is removed
+- **`free_hook(plugin_data: Any) -> None`**: [Optional] Clean up plugin resources
 
-- [x] Support for multiple eviction policies (FIFO, LRU, ARC, Clock, etc.)
-- [ ] trace analysis tools
+The `plugin_data` is whatever object you return from `init_hook()` - it can be any Python object like a list, dict, class instance, etc.

libCacheSim-python/examples/python_hook_cache_example.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating how to create custom cache policies using Python hooks.
+
+This example shows how to implement LRU and FIFO cache policies using the
+PythonHookCachePolicy class, which allows users to define cache behavior using
+pure Python functions instead of C/C++ plugins.
+"""
+
+import libcachesim as lcs
+from collections import OrderedDict, deque
+
+
+class LRUPolicy:
+    """LRU (Least Recently Used) cache policy implementation."""
+
+    def __init__(self, cache_size):
+        self.cache_size = cache_size
+        self.access_order = OrderedDict()  # obj_id -> True (for ordering)
+
+    def on_hit(self, obj_id, obj_size):
+        """Move accessed object to end (most recent)."""
+        if obj_id in self.access_order:
+            # Move to end (most recent)
+            self.access_order.move_to_end(obj_id)
+
+    def on_miss(self, obj_id, obj_size):
+        """Add new object to end (most recent)."""
+        self.access_order[obj_id] = True
+
+    def evict(self, obj_id, obj_size):
+        """Return the least recently used object ID."""
+        if self.access_order:
+            # Return first item (least recent)
+            victim_id = next(iter(self.access_order))
+            return victim_id
+        raise RuntimeError("No objects to evict")
+
+    def on_remove(self, obj_id):
+        """Remove object from tracking."""
+        self.access_order.pop(obj_id, None)
+
+
+class FIFOPolicy:
+    """FIFO (First In First Out) cache policy implementation."""
+
+    def __init__(self, cache_size):
+        self.cache_size = cache_size
+        self.insertion_order = deque()  # obj_id queue
+
+    def on_hit(self, obj_id, obj_size):
+        """FIFO doesn't change order on hits."""
+        pass
+
+    def on_miss(self, obj_id, obj_size):
+        """Add new object to end of queue."""
+        self.insertion_order.append(obj_id)
+
+    def evict(self, obj_id, obj_size):
+        """Return the first inserted object ID."""
+        if self.insertion_order:
+            victim_id = self.insertion_order.popleft()
+            return victim_id
+        raise RuntimeError("No objects to evict")
+
+    def on_remove(self, obj_id):
+        """Remove object from tracking."""
+        try:
+            self.insertion_order.remove(obj_id)
+        except ValueError:
+            pass  # Object not in queue
+
+
+def create_lru_cache(cache_size):
+    """Create an LRU cache using Python hooks."""
+    cache = lcs.PythonHookCachePolicy(cache_size, "PythonLRU")
+
+    def init_hook(cache_size):
+        return LRUPolicy(cache_size)
+
+    def hit_hook(policy, obj_id, obj_size):
+        policy.on_hit(obj_id, obj_size)
+
+    def miss_hook(policy, obj_id, obj_size):
+        policy.on_miss(obj_id, obj_size)
+
+    def eviction_hook(policy, obj_id, obj_size):
+        return policy.evict(obj_id, obj_size)
+
+    def remove_hook(policy, obj_id):
+        policy.on_remove(obj_id)
+
+    def free_hook(policy):
+        # Python garbage collection handles cleanup
+        pass
+
+    cache.set_hooks(init_hook, hit_hook, miss_hook, eviction_hook, remove_hook, free_hook)
+    return cache
+
+
+def create_fifo_cache(cache_size):
+    """Create a FIFO cache using Python hooks."""
+    cache = lcs.PythonHookCachePolicy(cache_size, "PythonFIFO")
+
+    def init_hook(cache_size):
+        return FIFOPolicy(cache_size)
+
+    def hit_hook(policy, obj_id, obj_size):
+        policy.on_hit(obj_id, obj_size)
+
+    def miss_hook(policy, obj_id, obj_size):
+        policy.on_miss(obj_id, obj_size)
+
+    def eviction_hook(policy, obj_id, obj_size):
+        return policy.evict(obj_id, obj_size)
+
+    def remove_hook(policy, obj_id):
+        policy.on_remove(obj_id)
+
+    cache.set_hooks(init_hook, hit_hook, miss_hook, eviction_hook, remove_hook)
+    return cache
+
+
+def test_cache_policy(cache, name):
+    """Test a cache policy with sample requests."""
+    print(f"\n=== Testing {name} Cache ===")
+
+    # Test requests: obj_id, obj_size
+    test_requests = [
+        (1, 100), (2, 100), (3, 100), (4, 100), (5, 100),  # Fill cache
+        (1, 100),  # Hit
+        (6, 100),  # Miss, should evict something
+        (2, 100),  # Hit or miss depending on policy
+        (7, 100),  # Miss, should evict something
+    ]
+
+    hits = 0
+    misses = 0
+
+    for obj_id, obj_size in test_requests:
+        req = lcs.Request()
+        req.obj_id = obj_id
+        req.obj_size = obj_size
+
+        hit = cache.get(req)
+        if hit:
+            hits += 1
+            print(f"Request {obj_id}: HIT")
+        else:
+            misses += 1
+            print(f"Request {obj_id}: MISS")
+
+    print(f"Total: {hits} hits, {misses} misses")
+    print(f"Cache stats: {cache.n_obj} objects, {cache.occupied_byte} bytes occupied")
+
+
+def main():
+    """Main example function."""
+    cache_size = 400  # Bytes (can hold 4 objects of size 100 each)
+
+    # Test LRU cache
+    lru_cache = create_lru_cache(cache_size)
+    test_cache_policy(lru_cache, "LRU")
+
+    # Test FIFO cache
+    fifo_cache = create_fifo_cache(cache_size)
+    test_cache_policy(fifo_cache, "FIFO")
+
+    print("\n=== Comparison ===")
+    print("LRU keeps recently accessed items, evicting least recently used")
+    print("FIFO keeps items in insertion order, evicting oldest inserted")
+
+
+if __name__ == "__main__":
+    main()

libCacheSim-python/libcachesim/__init__.py

@@ -21,6 +21,7 @@
     ThreeLCache,
     TinyLFU,
     TwoQ,
+    PythonHookCachePolicy,
 )
 
 __all__ = [
@@ -38,6 +39,7 @@
     "TinyLFU",
     "TraceType",
     "TwoQ",
+    "PythonHookCachePolicy",
     "__doc__",
     "__version__",
     "create_cache",