@@ -17,11 +17,6 @@ libCacheSim is flexible and easy to use with:
1717- ** Detailed cache requests** and other internal data control
1818- ** Customized plugin cache development** without any compilation
1919
20- ## Prerequisites
21-
22- - OS: Linux / macOS
23- - Python: 3.9 -- 3.13
24-
2520## Installation
2621
2722### Quick Install
@@ -32,50 +27,15 @@ Binary installers for the latest released version are available at the [Python P
3227pip install libcachesim
3328```
3429
35- ### Recommended Installation with uv
36-
37- It's recommended to use [ uv] ( https://docs.astral.sh/uv/ ) , a very fast Python environment manager, to create and manage Python environments:
38-
39- ``` bash
40- uv venv --python 3.12 --seed
41- source .venv/bin/activate
42- uv pip install libcachesim
43- ```
44-
45- ### Advanced Features Installation
46-
47- For users who want to run LRB, ThreeLCache, and GLCache eviction algorithms:
48-
49- !!! important
50- If ` uv ` cannot find built wheels for your machine, the building system will skip these algorithms by default.
51-
52- To enable them, you need to install all third-party dependencies first:
53-
54- ``` bash
55- git clone https://github.com/cacheMon/libCacheSim-python.git
56- cd libCacheSim-python
57- bash scripts/install_deps.sh
58-
59- # If you cannot install software directly (e.g., no sudo access)
60- bash scripts/install_deps_user.sh
61- ```
62-
63- Then, you can reinstall libcachesim using the following commands (may need to add ` --no-cache-dir ` to force it to build from scratch):
64-
65- ``` bash
66- # Enable LRB
67- CMAKE_ARGS=" -DENABLE_LRB=ON" uv pip install libcachesim
68- # Enable ThreeLCache
69- CMAKE_ARGS=" -DENABLE_3L_CACHE=ON" uv pip install libcachesim
70- # Enable GLCache
71- CMAKE_ARGS=" -DENABLE_GLCACHE=ON" uv pip install libcachesim
72- ```
30+ Visit our [ documentation] ( https://cachemon.github.io/libCacheSim-python/getting_started/quickstart/ ) to learn more.
7331
7432### Installation from sources
7533
7634If there are no wheels suitable for your environment, consider building from source.
7735
7836``` bash
37+ git clone https://github.com/cacheMon/libCacheSim-python.git
38+ cd libCacheSim-python
7939bash scripts/install.sh
8040```
8141
@@ -123,64 +83,6 @@ obj_miss_ratio, byte_miss_ratio = cache.process_trace(
12383print (f " Object miss ratio: { obj_miss_ratio:.4f } , Byte miss ratio: { byte_miss_ratio:.4f } " )
12484```
12585
126- ### Basic Usage
127-
128- ``` python
129- import libcachesim as lcs
130-
131- # Create a cache
132- cache = lcs.LRU(cache_size = 1024 * 1024 ) # 1MB cache
133-
134- # Process requests
135- req = lcs.Request()
136- req.obj_id = 1
137- req.obj_size = 100
138-
139- print (cache.get(req)) # False (first access)
140- print (cache.get(req)) # True (second access)
141- ```
142-
143- ### Trace Analysis
144-
145- Here is an example demonstrating how to use ` TraceAnalyzer ` :
146-
147- ``` python
148- import libcachesim as lcs
149-
150- # Step 1: Get one trace from S3 bucket
151- URI = " cache_dataset_oracleGeneral/2007_msr/msr_hm_0.oracleGeneral.zst"
152- dl = lcs.DataLoader()
153- dl.load(URI )
154-
155- reader = lcs.TraceReader(
156- trace = dl.get_cache_path(URI ),
157- trace_type = lcs.TraceType.ORACLE_GENERAL_TRACE ,
158- reader_init_params = lcs.ReaderInitParam(ignore_obj_size = False )
159- )
160-
161- analysis_option = lcs.AnalysisOption(
162- req_rate = True , # Keep basic request rate analysis
163- access_pattern = False , # Disable access pattern analysis
164- size = True , # Keep size analysis
165- reuse = False , # Disable reuse analysis for small datasets
166- popularity = False , # Disable popularity analysis for small datasets (< 200 objects)
167- ttl = False , # Disable TTL analysis
168- popularity_decay = False , # Disable popularity decay analysis
169- lifetime = False , # Disable lifetime analysis
170- create_future_reuse_ccdf = False , # Disable experimental features
171- prob_at_age = False , # Disable experimental features
172- size_change = False , # Disable size change analysis
173- )
174-
175- analysis_param = lcs.AnalysisParam()
176-
177- analyzer = lcs.TraceAnalyzer(
178- reader, " example_analysis" , analysis_option = analysis_option, analysis_param = analysis_param
179- )
180-
181- analyzer.run()
182- ```
183-
18486## Plugin System
18587
18688libCacheSim allows you to develop your own cache eviction algorithms and test them via the plugin system without any C/C++ compilation required.
@@ -204,7 +106,7 @@ The `PluginCache` allows you to define custom caching behavior through Python ca
204106from collections import OrderedDict
205107from typing import Any
206108
207- from libcachesim import PluginCache, LRU , CommonCacheParams, Request
109+ from libcachesim import PluginCache, LRU , CommonCacheParams, Request, SyntheticReader
208110
209111def init_hook (_ : CommonCacheParams) -> Any:
210112 return OrderedDict()
@@ -235,11 +137,10 @@ plugin_lru_cache = PluginCache(
235137 cache_name = " Plugin_LRU" ,
236138)
237139
238- reader = lcs.SyntheticReader(num_objects = 1000 , num_of_req = 10000 , obj_size = 1 )
140+ reader = SyntheticReader(
141+ num_objects = 1000 , num_of_req = 10000 , obj_size = 1 , alpha = 1.0 , dist = " zipf"
142+ )
239143req_miss_ratio, byte_miss_ratio = plugin_lru_cache.process_trace(reader)
240- ref_req_miss_ratio, ref_byte_miss_ratio = LRU(128 ).process_trace(reader)
241- print (f " plugin req miss ratio { req_miss_ratio} , ref req miss ratio { ref_req_miss_ratio} " )
242- print (f " plugin byte miss ratio { byte_miss_ratio} , ref byte miss ratio { ref_byte_miss_ratio} " )
243144```
244145
245146By defining custom hook functions for cache initialization, hit, miss, eviction, removal, and cleanup, users can easily prototype and test their own cache eviction algorithms.
@@ -299,4 +200,4 @@ If you used libCacheSim in your research, please cite the above papers.
299200## License
300201See [ LICENSE] ( LICENSE ) for details.
301202
302- ---
203+ ---
0 commit comments