{"id":15140945,"url":"https://github.com/jaxron/zigache","last_synced_at":"2025-08-20T23:10:16.441Z","repository":{"id":256761064,"uuid":"855107644","full_name":"jaxron/zigache","owner":"jaxron","description":"A customizable cache library in Zig with multiple eviction policies.","archived":false,"fork":false,"pushed_at":"2025-07-15T09:08:46.000Z","size":1186,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-15T20:49:30.702Z","etag":null,"topics":["zig","zig-lang","zig-library","zig-package","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaxron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-10T10:17:45.000Z","updated_at":"2025-07-15T19:35:37.000Z","dependencies_parsed_at":"2025-06-11T11:28:55.965Z","dependency_job_id":"c81092f7-2bae-47c0-af11-85ce633c112d","html_url":"https://github.com/jaxron/zigache","commit_stats":null,"previous_names":["jaxron/zigache"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jaxron/zigache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaxron%2Fzigache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaxron%2Fzigache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaxron%2Fzigache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaxron%2Fzigache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaxron","download_url":"https://codeload.github.com/jaxron/zigache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaxron%2Fzigache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271400259,"owners_count":24752830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["zig","zig-lang","zig-library","zig-package","ziglang"],"created_at":"2024-09-26T08:42:36.929Z","updated_at":"2025-08-20T23:10:16.435Z","avatar_url":"https://github.com/jaxron.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n    \u003cpicture\u003e\n      \u003cimg width=\"300\" alt=\"Zigache\" src=\"./assets/images/zigache_logo.png\"\u003e\n    \u003c/picture\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://github.com/jaxron/zigache/blob/main/LICENSE.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/jaxron/zigache?style=flat-square\u0026color=F27523\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/jaxron/zigache/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/jaxron/zigache/ci.yml?style=flat-square\u0026color=F27523\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://jaxron.me/zigache/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/zigache-docs-00ACD7.svg?style=flat-square\u0026color=F27523\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/jaxron/zigache/issues\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/issues/jaxron/zigache?style=flat-square\u0026color=F27523\"\u003e\n  \u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e\u003cb\u003eZigache\u003c/b\u003e is an efficient caching library built in \u003ca href=\"https://ziglang.org/\"\u003eZig\u003c/a\u003e, offering customizable cache eviction policies for various application needs.\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n\u003e [!IMPORTANT]\n\u003e Zigache is **not in active development** but will be maintained. The library follows Zig version `0.14.0`.\n\n# 📚 Table of Contents\n\n- [🚀 Features](#-features)\n- [⚡️ Quickstart](#%EF%B8%8F-quickstart)\n- [👀 Examples](#-examples)\n- [⚙️ Configuration](#%EF%B8%8F-configuration)\n- [📊 Benchmarks](#-benchmarks)\n- [📄 License](#-license)\n- [❓ FAQ](#-faq)\n\n# 🚀 Features\n\nZigache offers a rich set of features to designed to meet various caching needs:\n\n- **Multiple Eviction Algorithms:**\n  - W-TinyLFU | [TinyLFU: A Highly Efficient Cache Admission Policy](https://arxiv.org/abs/1512.00727)\n  - S3-FIFO | [FIFO queues are all you need for cache eviction](https://dl.acm.org/doi/10.1145/3600006.3613147)\n  - SIEVE | [SIEVE is Simpler than LRU: an Efficient Turn-Key Eviction Algorithm for Web Caches](https://www.usenix.org/conference/nsdi24/presentation/zhang-yazhuo)\n  - LRU | Least Recently Used\n  - FIFO | First-In-First-Out\n- **Extensive Configuration Options:**\n  - Configurable cache size with pre-allocation for performance tuning\n  - Ability to fine-tune cache policies (e.g., TinyLFU, S3FIFO)\n  - Time-To-Live (TTL) support to expire cache entries\n  - Thread safety and sharding settings for concurrent environments\n  - Adjustable max load factor for the cache\n- **Heavy Testing and Benchmarking** for [stability and performance](#-benchmarks) under various workloads\n\n# ⚡️ Quickstart\n\nTo use Zigache in your project, follow these steps:\n\n1. Run this command in your project's root directory:\n\n    ```sh\n    zig fetch --save git+https://github.com/jaxron/zigache.git\n    ```\n\n2. In your `build.zig`, add:\n\n    ```diff\n    pub fn build(b: *std.Build) void {\n        // Options\n        const target = b.standardTargetOptions(.{});\n        const optimize = b.standardOptimizeOption(.{});\n\n        // Build\n    +   const zigache = b.dependency(\"zigache\", .{\n    +       .target = target,\n    +       .optimize = optimize,\n    +   }).module(\"zigache\");\n    \n        const exe = b.addExecutable(.{\n            .name = \"your-project\",\n            .root_source_file = b.path(\"src/main.zig\"),\n            .target = target,\n            .optimize = optimize,\n        });\n    +   exe.root_module.addImport(\"zigache\", zigache);\n \n        b.installArtifact(exe);\n    \n        const run_cmd = b.addRunArtifact(exe);\n        run_cmd.step.dependOn(b.getInstallStep());\n    \n        const run_step = b.step(\"run\", \"Run the program\");\n        run_step.dependOn(\u0026run_cmd.step);\n    }\n    ```\n\n3. Now you can import and use Zigache in your code like this:\n\n    ```zig\n    const std = @import(\"std\");\n    const Cache = @import(\"zigache\").Cache;\n    \n    pub fn main() !void {\n        var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;\n        defer _ = gpa.deinit();\n        const allocator = gpa.allocator();\n    \n        // Create a cache with string keys and values\n        var cache: Cache([]const u8, []const u8, .{}) = try .init(allocator, .{\n            .cache_size = 1,\n            .policy = .SIEVE,\n        });\n        defer cache.deinit();\n    \n        // your code...\n    }\n    ```\n\n\u003csmall\u003e[🔝 Back to top](#-table-of-contents)\u003c/small\u003e\n\n# 👀 Examples\n\nExplore the usage scenarios in our examples directory:\n\n- [01 | Key Types](examples/01_key_types.zig)\n- [02 | TTL Entries](examples/02_ttl_entries.zig)\n\nTo run an example:\n\n```sh\nzig build [example-id]\nzig build 01\n```\n\n\u003csmall\u003e[🔝 Back to top](#-table-of-contents)\u003c/small\u003e\n\n# ⚙️ Configuration\n\nZigache offers flexible configuration options to adjust the cache to your needs:\n\n```zig\nvar cache: Cache([]const u8, []const u8, .{\n    .thread_safety = true,     // Enable thread safety for multi-threaded environments\n    .ttl_enabled = true,       // Enable Time-To-Live (TTL) functionality\n    .max_load_percentage = 60, // Set maximum load factor for the cache (60% occupancy)\n}) = try .init(allocator, .{\n    .cache_size = 10000,       // Maximum number of items the cache can store\n    .pool_size = 1000,         // Pre-allocated nodes to optimize performance\n    .shard_count = 16,         // Number of shards for concurrent access handling\n    .policy = .SIEVE,          // Eviction policy in use\n});\n```\n\n\u003e For more detailed information, refer to the [full documentation](https://jaxron.me/zigache/).\n\n\u003csmall\u003e[🔝 Back to top](#-table-of-contents)\u003c/small\u003e\n\n# 📊 Benchmarks\n\nThis 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.\n\n\u003e [!NOTE]\n\u003e 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`.\n\n\u003cdetails\u003e\n\u003csummary\u003eSingle Threaded (zipf 0.9, 10m keys)\u003c/summary\u003e\n\n## Benchmark Parameters\n\n```sh\nzig build bench -Doptimize=ReleaseFast\n```\n\nor\n\n```sh\nzig build bench -Doptimize=ReleaseFast -Dreplay=true -Dshards=1 -Dthreads=1 -Dauto='20:50000' -Dzipf='0.9' -Dkeys=10000000 -Dduration=10000\n```\n\n## Results\n\n### Hit Rate (%)\n\n\u003cpicture\u003e\n  \u003cimg alt=\"Zigache\" src=\"./assets/images/benchmarks/1/hit_rate.png\"\u003e\n\u003c/picture\u003e\n\n### Average Operation Time (ns/op)\n\n\u003cpicture\u003e\n  \u003cimg alt=\"Zigache\" src=\"./assets/images/benchmarks/1/ns_op.png\"\u003e\n\u003c/picture\u003e\n\n### Operations per Second (ops/s)\n\n\u003cpicture\u003e\n  \u003cimg alt=\"Zigache\" src=\"./assets/images/benchmarks/1/ops_s.png\"\u003e\n\u003c/picture\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eSingle Threaded (zipf 0.7, 10m keys)\u003c/summary\u003e\n\n## Benchmark Parameters\n\n```sh\nzig build bench -Doptimize=ReleaseFast -Dzipf='0.7'\n```\n\nor\n\n```sh\nzig build bench -Doptimize=ReleaseFast -Dreplay=true -Dshards=1 -Dthreads=1 -Dauto='20:50000' -Dzipf='0.7' -Dkeys=10000000 -Dduration=10000\n```\n\n## Results\n\n### Hit Rate (%)\n\n\u003cpicture\u003e\n  \u003cimg alt=\"Zigache\" src=\"./assets/images/benchmarks/2/hit_rate.png\"\u003e\n\u003c/picture\u003e\n\n### Average Operation Time (ns/op)\n\n\u003cpicture\u003e\n  \u003cimg alt=\"Zigache\" src=\"./assets/images/benchmarks/2/ns_op.png\"\u003e\n\u003c/picture\u003e\n\n### Operations per Second (ops/s)\n\n\u003cpicture\u003e\n  \u003cimg alt=\"Zigache\" src=\"./assets/images/benchmarks/2/ops_s.png\"\u003e\n\u003c/picture\u003e\n\n\u003c/details\u003e\n\n\u003csmall\u003e[🔝 Back to top](#-table-of-contents)\u003c/small\u003e\n\n# ❓ FAQ\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eIs Zigache production-ready?\u003c/b\u003e\u003c/summary\u003e\n  \u003cp\u003eYes, 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.\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eWhich eviction policy should I choose?\u003c/b\u003e\u003c/summary\u003e\n  \u003cp\u003eIt depends on your use case:\n    \u003cul\u003e\n      \u003cli\u003e\u003cb\u003eSIEVE\u003c/b\u003e: Best for high throughput and high hit rate. (recommended)\u003c/li\u003e\n      \u003cli\u003e\u003cb\u003eTinyLFU\u003c/b\u003e: Best for customizability and high hit rate.\u003c/li\u003e\n      \u003cli\u003e\u003cb\u003eS3FIFO\u003c/b\u003e: Decent throughput with a decent hit rate.\u003c/li\u003e\n      \u003cli\u003e\u003cb\u003eLRU\u003c/b\u003e: Reliable for standard needs but falls behind compared to other options.\u003c/li\u003e\n      \u003cli\u003e\u003cb\u003eFIFO\u003c/b\u003e: High throughput, but lowest hit rates.\u003c/li\u003e\n    \u003c/ul\u003e\n  \u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eCan I use Zigache in a multi-threaded environment?\u003c/b\u003e\u003c/summary\u003e\n  \u003cp\u003eYes, Zigache supports thread-safe operations and sharding. Sharding reduces contention and there are plans to improve performance further in the future.\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eWhat type of keys does Zigache support?\u003c/b\u003e\u003c/summary\u003e\n  \u003cp\u003eZigache supports most key types like strings, integers, structs, arrays, pointers, enums, and optionals. However, floats are not supported due to precision issues.\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eHow can I contribute to Zigache?\u003c/b\u003e\u003c/summary\u003e\n  \u003cp\u003eWe welcome contributions! Please follow the \u003ca href=\"https://ziglang.org/documentation/master/#Style-Guide\"\u003eZig Style Guide\u003c/a\u003e and ensure that your changes include appropriate tests.\u003c/p\u003e\n\u003c/details\u003e\n\n\u003csmall\u003e[🔝 Back to top](#-table-of-contents)\u003c/small\u003e\n\n# 📄 License\n\nThis project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaxron%2Fzigache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaxron%2Fzigache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaxron%2Fzigache/lists"}