https://github.com/jaxron/zigache
A customizable cache library in Zig with multiple eviction policies.
https://github.com/jaxron/zigache
zig zig-lang zig-library zig-package ziglang
Last synced: 10 months ago
JSON representation
A customizable cache library in Zig with multiple eviction policies.
- Host: GitHub
- URL: https://github.com/jaxron/zigache
- Owner: jaxron
- License: mit
- Created: 2024-09-10T10:17:45.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-15T09:08:46.000Z (11 months ago)
- Last Synced: 2025-07-15T20:49:30.702Z (11 months ago)
- Topics: zig, zig-lang, zig-library, zig-package, ziglang
- Language: Zig
- Homepage:
- Size: 1.13 MB
- Stars: 11
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Zigache is an efficient caching library built in Zig, offering customizable cache eviction policies for various application needs.
---
> [!IMPORTANT]
> Zigache is **not in active development** but will be maintained. The library follows Zig version `0.14.0`.
# 📚 Table of Contents
- [🚀 Features](#-features)
- [⚡️ Quickstart](#%EF%B8%8F-quickstart)
- [👀 Examples](#-examples)
- [⚙️ Configuration](#%EF%B8%8F-configuration)
- [📊 Benchmarks](#-benchmarks)
- [📄 License](#-license)
- [❓ FAQ](#-faq)
# 🚀 Features
Zigache offers a rich set of features to designed to meet various caching needs:
- **Multiple Eviction Algorithms:**
- W-TinyLFU | [TinyLFU: A Highly Efficient Cache Admission Policy](https://arxiv.org/abs/1512.00727)
- S3-FIFO | [FIFO queues are all you need for cache eviction](https://dl.acm.org/doi/10.1145/3600006.3613147)
- SIEVE | [SIEVE is Simpler than LRU: an Efficient Turn-Key Eviction Algorithm for Web Caches](https://www.usenix.org/conference/nsdi24/presentation/zhang-yazhuo)
- LRU | Least Recently Used
- FIFO | First-In-First-Out
- **Extensive Configuration Options:**
- Configurable cache size with pre-allocation for performance tuning
- Ability to fine-tune cache policies (e.g., TinyLFU, S3FIFO)
- Time-To-Live (TTL) support to expire cache entries
- Thread safety and sharding settings for concurrent environments
- Adjustable max load factor for the cache
- **Heavy Testing and Benchmarking** for [stability and performance](#-benchmarks) under various workloads
# ⚡️ Quickstart
To use Zigache in your project, follow these steps:
1. Run this command in your project's root directory:
```sh
zig fetch --save git+https://github.com/jaxron/zigache.git
```
2. In your `build.zig`, add:
```diff
pub fn build(b: *std.Build) void {
// Options
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
// Build
+ const zigache = b.dependency("zigache", .{
+ .target = target,
+ .optimize = optimize,
+ }).module("zigache");
const exe = b.addExecutable(.{
.name = "your-project",
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});
+ exe.root_module.addImport("zigache", zigache);
b.installArtifact(exe);
const run_cmd = b.addRunArtifact(exe);
run_cmd.step.dependOn(b.getInstallStep());
const run_step = b.step("run", "Run the program");
run_step.dependOn(&run_cmd.step);
}
```
3. Now you can import and use Zigache in your code like this:
```zig
const std = @import("std");
const Cache = @import("zigache").Cache;
pub fn main() !void {
var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
defer _ = gpa.deinit();
const allocator = gpa.allocator();
// Create a cache with string keys and values
var cache: Cache([]const u8, []const u8, .{}) = try .init(allocator, .{
.cache_size = 1,
.policy = .SIEVE,
});
defer cache.deinit();
// your code...
}
```
[🔝 Back to top](#-table-of-contents)
# 👀 Examples
Explore the usage scenarios in our examples directory:
- [01 | Key Types](examples/01_key_types.zig)
- [02 | TTL Entries](examples/02_ttl_entries.zig)
To run an example:
```sh
zig build [example-id]
zig build 01
```
[🔝 Back to top](#-table-of-contents)
# ⚙️ Configuration
Zigache offers flexible configuration options to adjust the cache to your needs:
```zig
var cache: Cache([]const u8, []const u8, .{
.thread_safety = true, // Enable thread safety for multi-threaded environments
.ttl_enabled = true, // Enable Time-To-Live (TTL) functionality
.max_load_percentage = 60, // Set maximum load factor for the cache (60% occupancy)
}) = try .init(allocator, .{
.cache_size = 10000, // Maximum number of items the cache can store
.pool_size = 1000, // Pre-allocated nodes to optimize performance
.shard_count = 16, // Number of shards for concurrent access handling
.policy = .SIEVE, // Eviction policy in use
});
```
> For more detailed information, refer to the [full documentation](https://jaxron.me/zigache/).
[🔝 Back to top](#-table-of-contents)
# 📊 Benchmarks
This benchmark uses a [Zipfian distribution](https://en.wikipedia.org/wiki/Zipf%27s_law), run on an Intel® Core™ i7-8700 CPU, using commit `7a12b1f` of this library.
> [!NOTE]
> These results are not conclusive, as performance depends on workload and environment. These benchmarks are comparing eviction policies within this library, and not comparisons with other languages or libraries. You can customize the benchmarks using various flags. For details, run `zig build -h`.
Single Threaded (zipf 0.9, 10m keys)
## Benchmark Parameters
```sh
zig build bench -Doptimize=ReleaseFast
```
or
```sh
zig build bench -Doptimize=ReleaseFast -Dreplay=true -Dshards=1 -Dthreads=1 -Dauto='20:50000' -Dzipf='0.9' -Dkeys=10000000 -Dduration=10000
```
## Results
### Hit Rate (%)
### Average Operation Time (ns/op)
### Operations per Second (ops/s)
Single Threaded (zipf 0.7, 10m keys)
## Benchmark Parameters
```sh
zig build bench -Doptimize=ReleaseFast -Dzipf='0.7'
```
or
```sh
zig build bench -Doptimize=ReleaseFast -Dreplay=true -Dshards=1 -Dthreads=1 -Dauto='20:50000' -Dzipf='0.7' -Dkeys=10000000 -Dduration=10000
```
## Results
### Hit Rate (%)
### Average Operation Time (ns/op)
### Operations per Second (ops/s)
[🔝 Back to top](#-table-of-contents)
# ❓ FAQ
Is Zigache production-ready?
Yes, Zigache is production-ready. It has been thoroughly tested and benchmarked for performance and stability. If you encounter any problems while using it in production, please report them so they can be addressed.
Which eviction policy should I choose?
It depends on your use case:
-
SIEVE: Best for high throughput and high hit rate. (recommended) -
TinyLFU: Best for customizability and high hit rate. -
S3FIFO: Decent throughput with a decent hit rate. -
LRU: Reliable for standard needs but falls behind compared to other options. -
FIFO: High throughput, but lowest hit rates.
Can I use Zigache in a multi-threaded environment?
Yes, Zigache supports thread-safe operations and sharding. Sharding reduces contention and there are plans to improve performance further in the future.
What type of keys does Zigache support?
Zigache supports most key types like strings, integers, structs, arrays, pointers, enums, and optionals. However, floats are not supported due to precision issues.
How can I contribute to Zigache?
We welcome contributions! Please follow the Zig Style Guide and ensure that your changes include appropriate tests.
[🔝 Back to top](#-table-of-contents)
# 📄 License
This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.