diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b07cfce9..68488d6e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,55 +1,63 @@ # Contributing to CacheLib -We want to make contributing to this project as easy and transparent as -possible. + +We want to make contributing to this project as easy and transparent as possible. We appreciate all contributions, from bug fixes and documentation improvements to new features. ## Code of Conduct -The code of conduct is described in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). -## Contributor License Agreement ("CLA") -In order to accept your pull request, we need you to submit a CLA. You only need -to do this once to work on any of Facebook's open source projects. +All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). + +## Contributor License Agreement (CLA) + +To accept your pull request, we need you to submit a CLA. You only need to do this once to work on any of Meta's open source projects. Complete your CLA here: -## Contributing improvements to CacheLib +## How to Contribute + +We welcome contributions in many forms: + +- **Bug Reports**: If you find a bug, please file a detailed issue on GitHub. +- **Feature Requests**: If you have an idea for a new feature, open an issue to discuss it. +- **Pull Requests**: We actively welcome your pull requests for bug fixes, improvements, and new features. +- **Documentation**: Improvements to our documentation are always welcome. + +### Documentation Contributions -We love seeing CacheLib being widely adopted and useful among the industry and -in other open source projects. If you'd like to leverage CacheLib in your -project and are facing challenges, please reach out to us on any feedback to -enable your adoption. This feedback is useful for us to help shape the future -features of CacheLib. +Our documentation is built with Docusaurus and is located in the `website/` directory. To contribute to the documentation: -If you are leveraging CacheLib in your application, we welcome any bug fixes, -build fixes, documentation improvements -and feature improvements that you would like to see become part of CacheLib. +1. Edit the Markdown files in `website/docs/`. +2. To preview your changes locally, run `cd website && npm install && npm start`. +3. Submit a pull request with your changes. -We look forward to seeing CacheLib be used to prototype new innovative designs -for cache hueristics and cache storage. When doing so, please open pull -request for the new feature with a good summary describing the change, the -design and how the feature was tested. Additionally, CacheBench offers a -platform to evaluate these prototypes against industry standard workloads. We -would like to represent significant caching workloads in CacheBench to help -the community understand caching challenges. +### Pull Requests +1. **Fork the repository** and create your branch from `main`. +2. **Add tests** if you've added code that should be tested. +3. **Update documentation** if you've changed APIs or added new features. +4. **Ensure the test suite passes** by running `python3 ./build/fbcode_builder/getdeps.py --allow-system-packages test cachelib`. +5. **Format your code** using `clang-format` with the provided `.clang-format` configuration. +6. **Complete the CLA** if you haven't already. -## Pull Requests -We actively welcome your pull requests. +We use a "rebase and merge" workflow. Please ensure your branch is up-to-date with `main` before submitting your PR. -1. Fork the repo and create your branch from `main`. -2. If you've added code that should be tested, add tests. -3. If you've changed APIs, update the documentation. -4. Ensure the test suite passes. -5. If you haven't already, complete the Contributor License Agreement ("CLA"). +#### Pull Request Template +When you open a pull request, please use the provided template and fill out the following sections: -## Issues -We use GitHub issues to track public bugs. Please ensure your description is -clear and has sufficient instructions to be able to reproduce the issue. +- **Summary**: A brief description of the changes. +- **Test Plan**: How you tested your changes. +- **Documentation**: A description of any documentation updates. -Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe -disclosure of security bugs. In those cases, please go through the process -outlined on that page and do not file a public issue. +### Issues + +We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to reproduce the issue. + +For security bugs, please do not file a public issue. Instead, report it through Meta's [Whitehat Bug Bounty program](https://www.facebook.com/whitehat/). + +## Code Style + +We use `clang-format` to enforce a consistent code style. Please run `clang-format` on your changes before submitting a pull request. You can find the configuration in the `.clang-format` file in the root of the repository. ## License -By contributing to CacheLib, you agree that your contributions will be licensed -under the LICENSE file in the root directory of this source tree. + +By contributing to CacheLib, you agree that your contributions will be licensed under the Apache-2.0 License that covers the project.md project uses in this project. diff --git a/README.md b/README.md index ddea75c93..711dcdca1 100644 --- a/README.md +++ b/README.md @@ -1,112 +1,120 @@ +# CacheLib: A Pluggable Caching Engine for High-Performance Services +

CacheLib

-# CacheLib - -Pluggable caching engine to build and scale high performance cache services. See -[www.cachelib.org](https://cachelib.org) for documentation and more information. +CacheLib is a C++ library that provides a powerful, flexible, and high-performance in-process caching engine. It is designed to build and scale services that require efficient memory management, low-latency access to cached data, and the ability to leverage both DRAM and SSD storage transparently. +See [www.cachelib.org](https://cachelib.org) for comprehensive documentation and more information. -## What is CacheLib ? +## Quick Start -CacheLib is a C++ library providing in-process high performance caching -mechanism. CacheLib provides a thread safe API to build high throughput, -low overhead caching services, with built-in ability to leverage -DRAM and SSD caching transparently. +Here is a minimal example of how to set up and use a simple CacheLib cache: +```cpp +#include +#include -## Performance benchmarking +using Cache = facebook::cachelib::CacheAllocator; +using PoolId = facebook::cachelib::PoolId; -CacheLib provides a standalone executable `CacheBench` that can be used to -evaluate the performance of heuristics and caching hardware platforms against -production workloads. Additionally `CacheBench` enables stress testing -implementation and design changes to CacheLib to catch correctness and -performance issues. +int main() { + // 1. Configure the cache + Cache::Config config; + config.setCacheSize(1024 * 1024 * 1024); // 1GB + config.setCacheName("MyFirstCache"); + config.setAccessConfig({25, 10}); // Use 25 buckets and 10 locks -See [CacheBench](https://cachelib.org/docs/Cache_Library_User_Guides/Cachebench_Overview) for usage details -and examples. + // 2. Create the cache instance + std::unique_ptr cache = std::make_unique(config); + PoolId defaultPool = cache->addPool("default", cache->getCacheMemoryStats().cacheSize); -## Versioning -CacheLib has one single version number `facebook::cachelib::kCachelibVersion` that can be located at [CacheVersion.h](https://github.com/facebook/CacheLib/blob/main/cachelib/allocator/CacheVersion.h#L31). This version number must be incremented when incompatible changes are introduced. A change is incompatible if it could cause a complication failure due to removing public API or requires dropping the cache. Details about the compatibility information when the version number increases can be found in the [changelog](https://github.com/facebook/CacheLib/blob/main/CHANGELOG.md). + // 3. Allocate and write to an item + auto handle = cache->allocate(defaultPool, "my_key", 100); + if (handle) { + std::strcpy(reinterpret_cast(handle->getMemory()), "Hello, CacheLib!"); + cache->insert(handle); + } + // 4. Read from the cache + auto readHandle = cache->find("my_key"); + if (readHandle) { + std::cout << reinterpret_cast(readHandle->getMemory()) << std::endl; + } -## Building and installation with `getdeps.py` + // 5. Remove from the cache + cache->remove("my_key"); -This script is used by many of Meta's OSS tools. It will download and build all of the necessary dependencies first, and will then invoke cmake etc to build folly. This will help ensure that you build with relevant versions of all of the dependent libraries, taking into account what versions are installed locally on your system. + return 0; +} +``` -### Dependencies +## Key Features -You can install system dependencies to save building them: +- **High Performance**: Thread-safe, low-overhead API for concurrent access with zero-copy semantics. +- **Hybrid Caching**: Transparently caches data across both DRAM and SSDs. +- **Flexible Eviction Policies**: Includes a variety of caching algorithms like LRU, Segmented LRU, FIFO, 2Q, and TinyLFU. +- **Memory Management**: Provides hard RSS memory constraints to prevent OOMs and efficiently caches variable-sized objects. +- **Persistence**: Supports shared-memory based persistence of the cache across process restarts. +- **Intelligent Tuning**: Automatically tunes the cache for dynamic changes in workload. +- **Extensible**: Pluggable architecture for custom eviction policies and storage backends. - # Clone the repo - git clone https://github.com/facebook/CacheLib - # Install dependencies - cd CacheLib - sudo ./build/fbcode_builder/getdeps.py install-system-deps --recursive cachelib +## Why Use CacheLib? -If you'd like to see the packages before installing them: +CacheLib is ideal for services that manage gigabytes of cached data and require fine-grained control over memory. Consider using CacheLib if your service needs: - ./build/fbcode_builder/getdeps.py install-system-deps --dry-run --recursive cachelib +- **Efficient Memory Use**: Caching for variable-sized objects without fragmentation. +- **High Concurrency**: Lock-free access patterns for high-throughput services. +- **OOM Protection**: Strict memory limits to ensure cache usage does not impact service stability. +- **Advanced Caching Algorithms**: Sophisticated eviction policies to maximize hit ratio. +- **Fast Restarts**: The ability to restore cache state quickly after a process restart. -On other platforms or if on Linux and without system dependencies `getdeps.py` will mostly download and build them for you during the build step. +## Architecture Overview -Some of the dependencies `getdeps.py` uses and installs are: +CacheLib's architecture is designed for modularity and performance. It consists of three main components: - * a version of boost compiled with C++14 support. - * googletest is required to build and run folly's tests. +1. **Access Container**: The indexing mechanism that maps keys to cached items. The default is a `ChainedHashTable` for O(1) lookups. +2. **MM (Memory Management) Container**: Manages the eviction policy (e.g., LRU) and tracks item lifecycle. +3. **Allocator**: Handles memory allocation from slabs, which are large chunks of memory carved from the total cache size. -### Build +These components work together to provide a highly concurrent and efficient caching system. -This script will download and build all of the necessary dependencies first, -and will then invoke cmake etc to build CacheLib. This will help ensure that you build with relevant versions of all of the dependent libraries, taking into account what versions are installed locally on your system. +## Getting Started -`getdeps.py` currently requires python 3.6+ to be on your path. +### Building and Installation -`getdeps.py` will invoke cmake etc. +We recommend using the provided `getdeps.py` script to build CacheLib and its dependencies. - # Clone the repo - git clone https://github.com/facebook/CacheLib - cd CacheLib - # Build, using system dependencies if available - python3 ./build/fbcode_builder/getdeps.py --allow-system-packages build cachelib +```bash +# 1. Clone the repository +git clone https://github.com/facebook/CacheLib +cd CacheLib -### Run tests +# 2. Install system dependencies +sudo ./build/fbcode_builder/getdeps.py install-system-deps --recursive cachelib -By default `getdeps.py` will build the tests for cachelib. To run them: +# 3. Build CacheLib +python3 ./build/fbcode_builder/getdeps.py --allow-system-packages build cachelib - python3 ./build/fbcode_builder/getdeps.py --allow-system-packages test cachelib +# 4. Run tests +python3 ./build/fbcode_builder/getdeps.py --allow-system-packages test cachelib +``` +### Performance Benchmarking +CacheLib includes `CacheBench`, a powerful tool for evaluating cache performance against production workloads. See the [CacheBench documentation](https://cachelib.org/docs/Cache_Library_User_Guides/Cachebench_Overview) for more details. ## Contributing -We'd love to have your help in making CacheLib better. If you're interested, -please read our [guide to contributing](CONTRIBUTING.md) +We welcome contributions! If you're interested in helping make CacheLib better, please read our [Contributing Guide](CONTRIBUTING.md). +## Community +- **GitHub Issues**: For bug reports and feature requests. +- **Discussions**: For questions and community discussions. +- **Stack Overflow**: Use the `cachelib` tag for questions. ## License -CacheLib is *apache* licensed, as found in the [LICENSE](LICENSE) file. - - - -## Reporting and Fixing Security Issues - -Please do not open GitHub issues or pull requests - this makes the problem -immediately visible to everyone, including malicious actors. Security issues in -CacheLib can be safely reported via Facebook's Whitehat Bug Bounty program: - -https://www.facebook.com/whitehat - -Facebook's security team will triage your report and determine whether or not is -it eligible for a bounty under our program. - - -## Build status - -Clicking on a badge will show you the recent builds for that OS. If your target OS's build is failing, you may check out the latest [release](https://github.com/facebook/CacheLib/releases). If the release is too stale for you, you may wish to check recent issues and PRs for known workarounds. - - -[![linux](https://github.com/facebook/CacheLib/actions/workflows/getdeps_linux.yml/badge.svg)](https://github.com/facebook/CacheLib/actions/workflows/getdeps_linux.yml) +CacheLib is Apache-2.0 licensed, as found in the [LICENSE](LICENSE) file.