Skip to main content

Python bindings for libCacheSim

Project description

libCacheSim Python Binding

Build Documentation

libCacheSim is fast with the features from underlying libCacheSim lib:

  • High performance - over 20M requests/sec for a realistic trace replay
  • High memory efficiency - predictable and small memory footprint
  • Parallelism out-of-the-box - uses the many CPU cores to speed up trace analysis and cache simulations

libCacheSim is flexible and easy to use with:

  • Seamless integration with open-source cache dataset consisting of thousands traces hosted on S3
  • High-throughput simulation with the underlying libCacheSim lib
  • Detailed cache requests and other internal data control
  • Customized plugin cache development without any compilation

Installation

Quick Install

Binary installers for the latest released version are available at the Python Package Index (PyPI).

pip install libcachesim

Visit our documentation to learn more.

Installation from sources

If there are no wheels suitable for your environment, consider building from source.

git clone https://github.com/cacheMon/libCacheSim-python.git
cd libCacheSim-python
bash scripts/install.sh

Run all tests to ensure the package works.

python -m pytest tests/

Quick Start

Cache Simulation

With libcachesim installed, you can start cache simulation for some eviction algorithm and cache traces:

import libcachesim as lcs

# Step 1: Open a trace hosted on S3 (find more via https://github.com/cacheMon/cache_dataset)
URI = "s3://cache-datasets/cache_dataset_oracleGeneral/2007_msr/msr_hm_0.oracleGeneral.zst"
reader = lcs.TraceReader(
    trace = URI,
    trace_type = lcs.TraceType.ORACLE_GENERAL_TRACE,
    reader_init_params = lcs.ReaderInitParam(ignore_obj_size=False)
)

# Step 2: Initialize cache
# Note: cache_size as float (0.1) means 10% of the reader's total working set size in bytes.
# To specify an absolute size, pass an integer (e.g., 1024*1024 for 1MB).
cache = lcs.S3FIFO(
    cache_size=0.1,  # 0.1 = 10% of trace's working set size (requires reader parameter)
    # Cache specific parameters
    small_size_ratio=0.2,
    ghost_size_ratio=0.8,
    move_to_main_threshold=2,
    reader=reader,  # Required when cache_size is a float ratio
)

# Step 3: 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}")

# Step 3.1: Process the first 1000 requests
# Note: cache_size as float means a ratio of the working set size (requires reader parameter)
cache = lcs.S3FIFO(
    cache_size=0.1,  # 10% of trace's working set size
    # Cache specific parameters
    small_size_ratio=0.2,
    ghost_size_ratio=0.8,
    move_to_main_threshold=2,
    reader=reader,  # Required when cache_size is a float ratio
)
req_miss_ratio, byte_miss_ratio = cache.process_trace(reader, start_req=0, max_req=1000)
print(f"Request miss ratio: {req_miss_ratio:.4f}, Byte miss ratio: {byte_miss_ratio:.4f}")

Plugin System

libCacheSim allows you to develop your own cache eviction algorithms and test them via the plugin system without any C/C++ compilation required.

Plugin Cache Overview

The PluginCache allows you to define custom caching behavior through Python callback functions. You need to implement these callback functions:

Function Signature Description
init_hook (common_cache_params: CommonCacheParams) -> Any Initialize your data structure
hit_hook (data: Any, request: Request) -> None Handle cache hits
miss_hook (data: Any, request: Request) -> None Handle cache misses
eviction_hook (data: Any, request: Request) -> int Return object ID to evict
remove_hook (data: Any, obj_id: int) -> None Clean up when object removed
free_hook (data: Any) -> None [Optional] Final cleanup

Example: Implementing LRU via Plugin System

from collections import OrderedDict
from typing import Any

from libcachesim import PluginCache, LRU, CommonCacheParams, Request, SyntheticReader

def init_hook(_: CommonCacheParams) -> Any:
    return OrderedDict()

def hit_hook(data: Any, req: Request) -> None:
    data.move_to_end(req.obj_id, last=True)

def miss_hook(data: Any, req: Request) -> None:
    data.__setitem__(req.obj_id, req.obj_size)

def eviction_hook(data: Any, _: Request) -> int:
    return data.popitem(last=False)[0]

def remove_hook(data: Any, obj_id: int) -> None:
    data.pop(obj_id, None)

def free_hook(data: Any) -> None:
    data.clear()

plugin_lru_cache = PluginCache(
    cache_size=128,
    cache_init_hook=init_hook,
    cache_hit_hook=hit_hook,
    cache_miss_hook=miss_hook,
    cache_eviction_hook=eviction_hook,
    cache_remove_hook=remove_hook,
    cache_free_hook=free_hook,
    cache_name="Plugin_LRU",
)

reader = SyntheticReader(
    num_objects=1000, num_of_req=10000, obj_size=1, alpha=1.0, dist="zipf"
)
req_miss_ratio, byte_miss_ratio = plugin_lru_cache.process_trace(reader)

By defining custom hook functions for cache initialization, hit, miss, eviction, removal, and cleanup, users can easily prototype and test their own cache eviction algorithms.

Getting Help


Reference

Please cite the following papers if you use libCacheSim.
@inproceedings{yang2020-workload,
    author = {Juncheng Yang and Yao Yue and K. V. Rashmi},
    title = {A large-scale analysis of hundreds of in-memory cache clusters at Twitter},
    booktitle = {14th USENIX Symposium on Operating Systems Design and Implementation (OSDI 20)},
    year = {2020},
    isbn = {978-1-939133-19-9},
    pages = {191--208},
    url = {https://www.usenix.org/conference/osdi20/presentation/yang},
    publisher = {USENIX Association},
}

@inproceedings{yang2023-s3fifo,
  title = {FIFO Queues Are All You Need for Cache Eviction},
  author = {Juncheng Yang and Yazhuo Zhang and Ziyue Qiu and Yao Yue and K.V. Rashmi},
  isbn = {9798400702297},
  publisher = {Association for Computing Machinery},
  booktitle = {Symposium on Operating Systems Principles (SOSP'23)},
  pages = {130–149},
  numpages = {20},
  year={2023}
}

@inproceedings{yang2023-qdlp,
  author = {Juncheng Yang and Ziyue Qiu and Yazhuo Zhang and Yao Yue and K.V. Rashmi},
  title = {FIFO Can Be Better than LRU: The Power of Lazy Promotion and Quick Demotion},
  year = {2023},
  isbn = {9798400701955},
  publisher = {Association for Computing Machinery},
  doi = {10.1145/3593856.3595887},
  booktitle = {Proceedings of the 19th Workshop on Hot Topics in Operating Systems (HotOS23)},
  pages = {70–79},
  numpages = {10},
}

If you used libCacheSim in your research, please cite the above papers.


License

See LICENSE for details.


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

libcachesim-0.3.3.post4.tar.gz (81.2 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

libcachesim-0.3.3.post4-cp313-cp313-manylinux_2_34_x86_64.whl (10.3 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post4-cp313-cp313-macosx_15_0_arm64.whl (4.6 MB view details)

Uploaded CPython 3.13macOS 15.0+ ARM64

libcachesim-0.3.3.post4-cp312-cp312-manylinux_2_34_x86_64.whl (10.3 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post4-cp312-cp312-macosx_15_0_arm64.whl (4.6 MB view details)

Uploaded CPython 3.12macOS 15.0+ ARM64

libcachesim-0.3.3.post4-cp311-cp311-manylinux_2_34_x86_64.whl (10.2 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post4-cp311-cp311-macosx_15_0_arm64.whl (4.6 MB view details)

Uploaded CPython 3.11macOS 15.0+ ARM64

libcachesim-0.3.3.post4-cp310-cp310-manylinux_2_34_x86_64.whl (10.2 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post4-cp310-cp310-macosx_15_0_arm64.whl (4.6 MB view details)

Uploaded CPython 3.10macOS 15.0+ ARM64

File details

Details for the file libcachesim-0.3.3.post4.tar.gz.

File metadata

  • Download URL: libcachesim-0.3.3.post4.tar.gz
  • Upload date:
  • Size: 81.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for libcachesim-0.3.3.post4.tar.gz
Algorithm Hash digest
SHA256 dbb7af3cee279efbe00ad8d9b651ae43ff397dc94a74dd80311f625a3e106faa
MD5 7a85d08fa1075d246fff883a36fb5734
BLAKE2b-256 28547a9eac1ffcc6340fc03a0d2e03d29cdddcc834e5d6f04ce175034837c26d

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4.tar.gz:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file libcachesim-0.3.3.post4-cp313-cp313-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post4-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 913e29a3e2e9789f2f53040170a9810b89516daad514fa7fa5ed70bd34033bdc
MD5 442c860ae94092af2262ef41966d3229
BLAKE2b-256 88511d2ffa2b8ad22d0b7689466f812614d48e87307277f8b4309ea1d2d7b722

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4-cp313-cp313-manylinux_2_34_x86_64.whl:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file libcachesim-0.3.3.post4-cp313-cp313-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post4-cp313-cp313-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 229e23a6455ec200d778d9fade622cbd288835345772949e8d000e17204d6d86
MD5 5a0700f68ec6152136cf83083e3de7af
BLAKE2b-256 36e3fdb562b151a90adcd85da6d352e11ffa753fd67037162334f027f78b4698

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4-cp313-cp313-macosx_15_0_arm64.whl:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file libcachesim-0.3.3.post4-cp312-cp312-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post4-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 e886ea282855adff2db406a95d6fc47fbed730781616ac3f9ee7699493cadb6a
MD5 87ce0f538490093ae1cb6e3f0ab8ad98
BLAKE2b-256 806283f7a9e10042a6633027ec3c68adc0593886d6314fd1df8d5847598ddd55

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4-cp312-cp312-manylinux_2_34_x86_64.whl:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file libcachesim-0.3.3.post4-cp312-cp312-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post4-cp312-cp312-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 9a526581d519f723a6f4dabed909cc4e0b3073de9ac4ded239c277a207588433
MD5 3940b54abb87f7abe9d0e0482e82de9f
BLAKE2b-256 917821b06cc6cdc2720ee6b76e4a3a97c6831b140e5fb29e6990c47dbae7ae85

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4-cp312-cp312-macosx_15_0_arm64.whl:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file libcachesim-0.3.3.post4-cp311-cp311-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post4-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 859d00ed7158247731ecad75135fbcef75db9ceec7421b477eff528fa7dd1e19
MD5 7e537aa79faa813e7f9d08f527275011
BLAKE2b-256 4e5ed4d630cf967b6b388a933b4433eb0aa9cb0ac1b9fc3fee9c4069d1212b7a

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4-cp311-cp311-manylinux_2_34_x86_64.whl:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file libcachesim-0.3.3.post4-cp311-cp311-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post4-cp311-cp311-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 344fa4295da3fdef23096b39f11eb5460c872ec7cc49c21951ca1bae8b73647c
MD5 543e1b3462edc6849eb46be9dbf1c841
BLAKE2b-256 4ce592d18e813a270933426837b2f75e9e38efe17c134ba4fb18335fe852b400

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4-cp311-cp311-macosx_15_0_arm64.whl:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file libcachesim-0.3.3.post4-cp310-cp310-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post4-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 462f8d7cb98427a690e8a99f131dbf64767144c8fa6807742050294fa87b3ae6
MD5 24ad1ed892768c76fd2d879658eb78b9
BLAKE2b-256 94748334b1a355dc7fd8bf1f8f29c21be9dc925631574a5e53c46baf8a7494eb

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4-cp310-cp310-manylinux_2_34_x86_64.whl:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file libcachesim-0.3.3.post4-cp310-cp310-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post4-cp310-cp310-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 d562de13a82671734979b58f6f6bd461192628812b41d340fb3b37f4d1fcafa5
MD5 d4d5a84b389cbddda62e86bbca52bcaa
BLAKE2b-256 55d4ba771ffb04d4694281bb0b5710b9085e5089193da1cdee5f23c2c2b32f1f

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post4-cp310-cp310-macosx_15_0_arm64.whl:

Publisher: pypi-release.yml on cacheMon/libCacheSim-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page