Skip to content

docs: Improve README.md and CONTRIBUTING.md #429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vj7-byte wants to merge 1 commit into
base: main
Choose a base branch
from
+124 −108
Open

docs: Improve README.md and CONTRIBUTING.md #429

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 45 additions & 37 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: <https://code.facebook.com/cla>

## 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.
150 changes: 79 additions & 71 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,112 +1,120 @@
# CacheLib: A Pluggable Caching Engine for High-Performance Services

<p align="center">
<img width="500" height="140" alt="CacheLib" src="website/static/img/CacheLib-Logo-Large-transp.png">
</p>

# 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 <cachelib/allocator/CacheAllocator.h>
#include <iostream>

## 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> cache = std::make_unique<Cache>(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<char*>(handle->getMemory()), "Hello, CacheLib!");
cache->insert(handle);
}

// 4. Read from the cache
auto readHandle = cache->find("my_key");
if (readHandle) {
std::cout << reinterpret_cast<char*>(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.