Skip to content

Commit f986db2

Browse files
committed
Add description for Pybind in main README.md
1 parent deb3134 commit f986db2

11 files changed

Lines changed: 339 additions & 344 deletions

File tree

README.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@
2929
- [Miss ratio curves profiling](#miss-ratio-curves-profiling)
3030
- [Using libCacheSim as a library](#using-libcachesim-as-a-library)
3131
- [Extending libCacheSim (new algorithms and trace types)](#extending-libcachesim-new-algorithms-and-trace-types)
32+
- [Python package](#python-package)
33+
- [Simulation with python](#simulation-with-python)
34+
- [Extending new algorithm](#extending-new-algorithm)
3235
- [Open source cache traces](#open-source-cache-traces)
3336
- [Contributions](#contributions)
3437
- [Reference](#reference)
@@ -309,6 +312,66 @@ If you need to add a new trace type or a new algorithm, please see [here](/doc/a
309312

310313
We encourage the users to check [deepWiki](https://deepwiki.com/1a1a11a/libCacheSim) for a more detailed documentation.
311314

315+
---
316+
<!-- TOC --><a name="python-package"></a>
317+
## Python package
318+
319+
If you are not extremely senstive to the performance, our python binding can offer you a easiler way to access the core feature of libCacheSim.
320+
321+
```shell
322+
pip install libcachesim
323+
```
324+
325+
> [!NOTE]
326+
> Built python package only support linux now. We will support more platform soon. You can also install it from source, see [instructions](./libCacheSim-python/README.md#installation-from-sources).
327+
328+
### Simulation with python
329+
330+
```python
331+
import libcachesim as lcs
332+
333+
reader = lcs.open_trace("./data/cloudPhysicsIO.oracleGeneral.bin")
334+
cache = lcs.FIFO(cache_size=1024*1024)
335+
miss_ratio = cache.process_trace(reader)
336+
print(f"Miss ratio: {miss_ratio:.4f}")
337+
```
338+
339+
### Extending new algorithm
340+
341+
With python package, you can extend new algorithm to test your own eviction design *without any C/C++ compilation**.
342+
343+
```python
344+
import libcachesim as lcs
345+
from collections import deque
346+
347+
cache = lcs.PythonHookCachePolicy(cache_size=1024, cache_name="CustomFIFO")
348+
349+
def init_hook(cache_size):
350+
return deque() # Use deque for FIFO order
351+
352+
def hit_hook(fifo_queue, obj_id, obj_size):
353+
pass # FIFO doesn't reorder on hit
354+
355+
def miss_hook(fifo_queue, obj_id, obj_size):
356+
fifo_queue.append(obj_id) # Add to end of queue
357+
358+
def eviction_hook(fifo_queue, obj_id, obj_size):
359+
return fifo_queue[0] # Return first item (oldest)
360+
361+
def remove_hook(fifo_queue, obj_id):
362+
if fifo_queue and fifo_queue[0] == obj_id:
363+
fifo_queue.popleft()
364+
365+
# Set the hooks and test
366+
cache.set_hooks(init_hook, hit_hook, miss_hook, eviction_hook, remove_hook)
367+
368+
reader = lcs.open_trace("./data/cloudPhysicsIO.oracleGeneral.bin")
369+
miss_ratio = cache.process_trace(reader)
370+
print(f"Miss ratio: {miss_ratio:.4f}")
371+
```
372+
373+
374+
See more information in [README.md](./libCacheSim-python/README.md) of the Python binding.
312375

313376
---
314377
<!-- TOC --><a name="open-source-cache-traces"></a>

0 commit comments

Comments
 (0)