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
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,
)

# 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
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,
)
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.post3.tar.gz (80.7 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.post3-cp313-cp313-manylinux_2_34_x86_64.whl (9.8 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post3-cp313-cp313-macosx_15_0_arm64.whl (4.4 MB view details)

Uploaded CPython 3.13macOS 15.0+ ARM64

libcachesim-0.3.3.post3-cp312-cp312-manylinux_2_34_x86_64.whl (9.8 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post3-cp312-cp312-macosx_15_0_arm64.whl (4.4 MB view details)

Uploaded CPython 3.12macOS 15.0+ ARM64

libcachesim-0.3.3.post3-cp311-cp311-manylinux_2_34_x86_64.whl (9.8 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post3-cp311-cp311-macosx_15_0_arm64.whl (4.4 MB view details)

Uploaded CPython 3.11macOS 15.0+ ARM64

libcachesim-0.3.3.post3-cp310-cp310-manylinux_2_34_x86_64.whl (9.8 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post3-cp310-cp310-macosx_15_0_arm64.whl (4.4 MB view details)

Uploaded CPython 3.10macOS 15.0+ ARM64

libcachesim-0.3.3.post3-cp39-cp39-manylinux_2_34_x86_64.whl (9.8 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.34+ x86-64

libcachesim-0.3.3.post3-cp39-cp39-macosx_15_0_arm64.whl (4.4 MB view details)

Uploaded CPython 3.9macOS 15.0+ ARM64

File details

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

File metadata

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

File hashes

Hashes for libcachesim-0.3.3.post3.tar.gz
Algorithm Hash digest
SHA256 04b1fc6f1108295985664e692f47189a50643185b7b8e956e2ce74b8d4a72312
MD5 5b519d50818a4b5a03f3c6fc7751f763
BLAKE2b-256 0a9b84e56be805dce8fb9ab9859b9666b672ad16f440769afe79ce6bd6a58951

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3.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.post3-cp313-cp313-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 4477948040ea5a74c15361e64b29437c154a6645bfd5f3bf1e2b8a909e8e854f
MD5 119fea91c1d2b37a5a860bb250cf24d0
BLAKE2b-256 67515053a9def725cd1029654db2c263a5009110a5b11251bbdcb101bf52a40c

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-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.post3-cp313-cp313-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp313-cp313-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 9a45b7e8db394b2677b48c589f55005744ba1fefd64ab1fcdd9e390b15235add
MD5 4895cbf1fa339338b356c77660283061
BLAKE2b-256 34db5f02cccd58bb36b55d15584945599c7392e6ad572adf418efbeb0ad36787

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-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.post3-cp312-cp312-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 d186741f444e881921f3a33fcd7c83d36bd8bb50ef665c5e624e5a70138c461c
MD5 908d34bda4cc303e0fa75f4671db9a8d
BLAKE2b-256 8ef427df81a1f441079c1a0b47760d5c2a418231d282425b80e3faec0c7bdba1

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-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.post3-cp312-cp312-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp312-cp312-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 0109f6aa8f85b3c27261fdcd223bdd7aefc21f7cf42be101835ff1a497556d47
MD5 d0b9d077e0a658dfdb49b93775cf126b
BLAKE2b-256 c98e568f11ec9a26d766c672956e052b9142d2d147bd970a1b53df4e1e17ebbf

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-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.post3-cp311-cp311-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 43dc55f1243d65a97cc3ed49a692d6defa92a36fc10a56fd06c8fbe5c875dc8c
MD5 969eb6aeb47d8505f73669b5b1c525bf
BLAKE2b-256 7cfa5ec69308ba767f99c60f02e23079693b8716cde55ac8417afbf7c9d734df

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-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.post3-cp311-cp311-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp311-cp311-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 ffade39d2019560891b56eccc104672eda4ffd28cb4f8c958788a0e6cbc24b3c
MD5 8c1c57deb20e9cc1507293471f62bfb4
BLAKE2b-256 a6b0cfa425601519a8104a9109e0bc2a90b55365bf09321f9c7ecff01006991f

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-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.post3-cp310-cp310-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 3eae78258b9f3047630223c2d93615972c7c0f1730924b9b7bb12f31c9e749d5
MD5 ef2b90fc52f8893701f43e01681ca9f7
BLAKE2b-256 9136b284c9af5f4cc7242b5407287435d5445bdeadd35ccd6f5952a269dc0b8e

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-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.post3-cp310-cp310-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp310-cp310-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 afba47d6aebffcde48bc58de64b1810dd58b284e43fc44837cc01792f5d08edd
MD5 87e14270f7a878dd81b29e975fde4d4b
BLAKE2b-256 c12f0a14c03f627a04b2ec230d9bbca5be6ee019f5d83bcd56e345209d871858

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-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.

File details

Details for the file libcachesim-0.3.3.post3-cp39-cp39-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp39-cp39-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 3228fe6edcb6a9a661be04a422ccbe2d03bf909a249ab1ac471b2b4732ee56ed
MD5 80cb6c06033d49daae2856050c03a4bc
BLAKE2b-256 2237f982a6f45d2fd621ef0151ffa02d7800bb3906982ddf98d7336751e62a42

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-cp39-cp39-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.post3-cp39-cp39-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for libcachesim-0.3.3.post3-cp39-cp39-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 f574c866e728abbc5657949801d628c8dac61ee8f539149461dd7acb8ee5550c
MD5 826eab2036edcb9b82de496cfb2d548b
BLAKE2b-256 61ba0f0ad27d9b277aa511eccebf02632522a9f0495411b8ce2b5277990fa24d

See more details on using hashes here.

Provenance

The following attestation bundles were made for libcachesim-0.3.3.post3-cp39-cp39-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