├── .gitattributes ├── .github └── workflows │ ├── cd.yaml │ └── ci.yaml ├── .gitignore ├── LICENSE ├── README.md ├── build.zig ├── build.zig.zon └── src ├── bench.zig ├── root.zig └── sieve.zig /.gitattributes: -------------------------------------------------------------------------------- 1 | # Zig recommends LF line endings 2 | *.zig text eol=lf 3 | *.zon text eol=lf 4 | -------------------------------------------------------------------------------- /.github/workflows/cd.yaml: -------------------------------------------------------------------------------- 1 | name: CD 2 | 3 | on: 4 | workflow_run: 5 | workflows: [CI] 6 | types: [completed] 7 | 8 | workflow_dispatch: 9 | 10 | jobs: 11 | emit: 12 | if: ${{ github.event.workflow_run.conclusion == 'success' }} 13 | 14 | runs-on: ubuntu-latest 15 | 16 | steps: 17 | - name: Check out repository 18 | uses: actions/checkout@v4 19 | 20 | - name: Set up Zig 21 | uses: mlugg/setup-zig@v1 22 | with: 23 | version: master 24 | 25 | - name: Run doc step 26 | run: zig build doc 27 | 28 | - name: Upload artifact for GitHub Pages 29 | uses: actions/upload-pages-artifact@v3 30 | with: 31 | path: zig-out/docs/ 32 | 33 | deploy: 34 | needs: emit 35 | 36 | runs-on: ubuntu-latest 37 | 38 | permissions: 39 | pages: write 40 | id-token: write 41 | 42 | environment: 43 | name: github-pages 44 | url: ${{ steps.deployment.outputs.page_url }} 45 | 46 | steps: 47 | - name: Deploy artifact to GitHub Pages 48 | id: deployment 49 | uses: actions/deploy-pages@v4 50 | -------------------------------------------------------------------------------- /.github/workflows/ci.yaml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: [main] 6 | 7 | pull_request: 8 | branches: [main] 9 | 10 | workflow_dispatch: 11 | 12 | jobs: 13 | test: 14 | runs-on: ubuntu-latest 15 | 16 | steps: 17 | - name: Check out repository 18 | uses: actions/checkout@v4 19 | 20 | - name: Set up Zig 21 | uses: mlugg/setup-zig@v1 22 | with: 23 | version: master 24 | 25 | - name: Run test step 26 | run: zig build test --summary all 27 | 28 | fmt: 29 | runs-on: ubuntu-latest 30 | 31 | steps: 32 | - name: Check out repository 33 | uses: actions/checkout@v4 34 | 35 | - name: Set up Zig 36 | uses: mlugg/setup-zig@v1 37 | with: 38 | version: master 39 | 40 | - name: Run fmt step 41 | run: zig build fmt 42 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Zig artifacts 2 | .zig-cache/ 3 | zig-out/ 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Jora Troosh 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # zig-sieve 2 | 3 | ## Zig implementation of [SIEVE cache eviction algorithm](https://cachemon.github.io/SIEVE-website/). 4 | 5 | ### Usage 6 | 7 | - Add `sieve` dependency to `build.zig.zon`. 8 | 9 | ```sh 10 | zig fetch --save git+https://github.com/tensorush/zig-sieve 11 | ``` 12 | 13 | - Use `sieve` dependency in `build.zig`. 14 | 15 | ```zig 16 | const sieve_dep = b.dependency("sieve", .{ 17 | .target = target, 18 | .optimize = optimize, 19 | }); 20 | const sieve_mod = sieve_dep.module("sieve"); 21 | .root_module.addImport("sieve", sieve_mod); 22 | ``` 23 | 24 | ### Benchmarks (MacBook M1 Pro) 25 | 26 | - Sequence: the time to cache and retrieve integer values. 27 | 28 | ```sh 29 | $ zig build bench -- -s 30 | Sequence: 23.042us 31 | ``` 32 | 33 | - Composite: the time to cache and retrieve composite values. 34 | 35 | ```sh 36 | $ zig build bench -- -c 37 | Composite: 33.417us 38 | ``` 39 | 40 | - Composite (normal): the time to cache and retrieve normally-distributed composite values. 41 | 42 | ```sh 43 | $ zig build bench -- -n 44 | Composite Normal: 99.708us 45 | ``` 46 | -------------------------------------------------------------------------------- /build.zig: -------------------------------------------------------------------------------- 1 | const std = @import("std"); 2 | 3 | pub fn build(b: *std.Build) void { 4 | const install_step = b.getInstallStep(); 5 | const target = b.standardTargetOptions(.{}); 6 | const optimize = b.standardOptimizeOption(.{}); 7 | const root_source_file = b.path("src/root.zig"); 8 | const version = std.SemanticVersion{ .major = 0, .minor = 1, .patch = 1 }; 9 | 10 | // Module 11 | const mod = b.addModule("sieve", .{ 12 | .target = target, 13 | .optimize = optimize, 14 | .root_source_file = root_source_file, 15 | }); 16 | 17 | // Library 18 | const lib_step = b.step("lib", "Install library"); 19 | 20 | const lib = b.addLibrary(.{ 21 | .name = "sieve", 22 | .version = version, 23 | .root_module = mod, 24 | }); 25 | 26 | const lib_install = b.addInstallArtifact(lib, .{}); 27 | lib_step.dependOn(&lib_install.step); 28 | install_step.dependOn(lib_step); 29 | 30 | // Documentation 31 | const docs_step = b.step("doc", "Emit documentation"); 32 | const docs_install = b.addInstallDirectory(.{ 33 | .install_dir = .prefix, 34 | .install_subdir = "docs", 35 | .source_dir = lib.getEmittedDocs(), 36 | }); 37 | docs_step.dependOn(&docs_install.step); 38 | install_step.dependOn(docs_step); 39 | 40 | // Benchmarks 41 | const benchs_step = b.step("bench", "Run benchmarks"); 42 | 43 | const benchs = b.addExecutable(.{ 44 | .name = "bench", 45 | .version = version, 46 | .root_module = b.createModule(.{ 47 | .target = target, 48 | .optimize = .ReleaseFast, 49 | .root_source_file = b.path("src/bench.zig"), 50 | }), 51 | }); 52 | 53 | const benchs_run = b.addRunArtifact(benchs); 54 | if (b.args) |args| { 55 | benchs_run.addArgs(args); 56 | } 57 | benchs_step.dependOn(&benchs_run.step); 58 | 59 | // Test suite 60 | const tests_step = b.step("test", "Run test suite"); 61 | 62 | const tests = b.addTest(.{ 63 | .version = version, 64 | .root_module = b.createModule(.{ 65 | .target = target, 66 | .root_source_file = root_source_file, 67 | }), 68 | }); 69 | 70 | const tests_run = b.addRunArtifact(tests); 71 | tests_step.dependOn(&tests_run.step); 72 | install_step.dependOn(tests_step); 73 | 74 | // Formatting check 75 | const fmt_step = b.step("fmt", "Check formatting"); 76 | 77 | const fmt = b.addFmt(.{ 78 | .paths = &.{ 79 | "src/", 80 | "build.zig", 81 | "build.zig.zon", 82 | }, 83 | .check = true, 84 | }); 85 | fmt_step.dependOn(&fmt.step); 86 | install_step.dependOn(fmt_step); 87 | } 88 | -------------------------------------------------------------------------------- /build.zig.zon: -------------------------------------------------------------------------------- 1 | .{ 2 | .name = .sieve, 3 | .fingerprint = 0x34df97e7ea21fbe6, 4 | .version = "0.1.1", 5 | .minimum_zig_version = "0.14.0", 6 | .paths = .{ 7 | "src/", 8 | "build.zig", 9 | "build.zig.zon", 10 | "LICENSE", 11 | "README.md", 12 | }, 13 | } 14 | -------------------------------------------------------------------------------- /src/bench.zig: -------------------------------------------------------------------------------- 1 | const std = @import("std"); 2 | const sieve = @import("sieve.zig"); 3 | 4 | const MEAN: f64 = 50.0; 5 | const ARRAY_SIZE: u64 = 12; 6 | const NUM_ITERS: u64 = 1000; 7 | const CACHE_CAPACITY: u64 = 68; 8 | const STD_DEV: f64 = MEAN / 3.0; 9 | 10 | pub fn main() !void { 11 | var gpa_state = std.heap.DebugAllocator(.{}){}; 12 | const gpa = gpa_state.allocator(); 13 | defer if (gpa_state.deinit() == .leak) { 14 | @panic("Memory leak has occurred!"); 15 | }; 16 | 17 | const std_out = std.io.getStdOut(); 18 | var buf_writer = std.io.bufferedWriter(std_out.writer()); 19 | const writer = buf_writer.writer(); 20 | 21 | var prng = std.Random.DefaultPrng.init(blk: { 22 | var seed: u64 = undefined; 23 | try std.posix.getrandom(std.mem.asBytes(&seed)); 24 | break :blk seed; 25 | }); 26 | const random = prng.random(); 27 | 28 | var buf: [512]u8 = undefined; 29 | var fixed_buf = std.heap.FixedBufferAllocator.init(buf[0..]); 30 | const args = try std.process.argsAlloc(fixed_buf.allocator()); 31 | 32 | switch (args[1][1]) { 33 | 's' => try benchmarkSequence(gpa, writer), 34 | 'c' => try benchmarkComposite(gpa, random, writer), 35 | 'n' => try benchmarkCompositeNormal(gpa, random, writer), 36 | else => @panic("Unknown benchmark!"), 37 | } 38 | 39 | try buf_writer.flush(); 40 | } 41 | 42 | fn benchmarkSequence(gpa: std.mem.Allocator, writer: anytype) !void { 43 | const Cache = sieve.Cache(u64, u64); 44 | var cache = try Cache.init(gpa, CACHE_CAPACITY); 45 | defer cache.deinit(gpa); 46 | 47 | var timer = try std.time.Timer.start(); 48 | const start = timer.lap(); 49 | 50 | var node: *Cache.Node = undefined; 51 | var num: u64 = undefined; 52 | var i: u64 = 1; 53 | while (i < NUM_ITERS) : (i += 1) { 54 | num = i % 100; 55 | node = try gpa.create(Cache.Node); 56 | node.* = .{ .key = num, .value = num }; 57 | _ = try cache.put(node); 58 | } 59 | 60 | while (i < NUM_ITERS) : (i += 1) { 61 | num = i % 100; 62 | _ = cache.get(num); 63 | } 64 | 65 | try writer.print("Sequence: {}\n", .{std.fmt.fmtDuration(timer.read() - start)}); 66 | } 67 | 68 | fn benchmarkComposite(gpa: std.mem.Allocator, random: std.Random, writer: anytype) !void { 69 | const Cache = sieve.Cache(u64, struct { [ARRAY_SIZE]u8, u64 }); 70 | var cache = try Cache.init(gpa, CACHE_CAPACITY); 71 | defer cache.deinit(gpa); 72 | 73 | var timer = try std.time.Timer.start(); 74 | const start = timer.lap(); 75 | 76 | var node: *Cache.Node = undefined; 77 | var num: u64 = undefined; 78 | var i: u64 = 1; 79 | while (i < NUM_ITERS) : (i += 1) { 80 | num = random.uintLessThan(u64, 100); 81 | node = try gpa.create(Cache.Node); 82 | node.* = .{ .key = num, .value = .{ [1]u8{0} ** ARRAY_SIZE, num } }; 83 | _ = try cache.put(node); 84 | } 85 | 86 | while (i < NUM_ITERS) : (i += 1) { 87 | num = random.uintLessThan(u64, 100); 88 | _ = cache.get(num); 89 | } 90 | 91 | try writer.print("Composite: {}\n", .{std.fmt.fmtDuration(timer.read() - start)}); 92 | } 93 | 94 | fn benchmarkCompositeNormal(gpa: std.mem.Allocator, random: std.Random, writer: anytype) !void { 95 | const Cache = sieve.Cache(u64, struct { [ARRAY_SIZE]u8, u64 }); 96 | var cache = try Cache.init(gpa, @intFromFloat(STD_DEV)); 97 | defer cache.deinit(gpa); 98 | 99 | var timer = try std.time.Timer.start(); 100 | const start = timer.lap(); 101 | 102 | var node: *Cache.Node = undefined; 103 | var num: u64 = undefined; 104 | var i: u64 = 1; 105 | while (i < NUM_ITERS) : (i += 1) { 106 | num = @intFromFloat(random.floatNorm(f64) * STD_DEV + MEAN); 107 | num %= 100; 108 | node = try gpa.create(Cache.Node); 109 | node.* = .{ .key = num, .value = .{ [1]u8{0} ** ARRAY_SIZE, num } }; 110 | _ = try cache.put(node); 111 | } 112 | 113 | while (i < NUM_ITERS) : (i += 1) { 114 | num = @intFromFloat(random.floatNorm(f64) * STD_DEV + MEAN); 115 | num %= 100; 116 | _ = cache.get(num); 117 | } 118 | 119 | try writer.print("Composite Normal: {}\n", .{std.fmt.fmtDuration(timer.read() - start)}); 120 | } 121 | -------------------------------------------------------------------------------- /src/root.zig: -------------------------------------------------------------------------------- 1 | //! Root source file that exposes the library's API to users and Autodoc. 2 | 3 | const std = @import("std"); 4 | 5 | pub const Cache = @import("sieve.zig").Cache; 6 | 7 | test { 8 | std.testing.refAllDecls(@This()); 9 | } 10 | -------------------------------------------------------------------------------- /src/sieve.zig: -------------------------------------------------------------------------------- 1 | const std = @import("std"); 2 | 3 | /// Intrusive cache based on the SIEVE eviction algorithm. 4 | pub fn Cache(comptime K: type, comptime V: type) type { 5 | return struct { 6 | const Self = @This(); 7 | const HashMapUnmanaged = if (K == []const u8) std.StringHashMapUnmanaged(*Node) else std.AutoHashMapUnmanaged(K, *Node); 8 | 9 | /// Intrusive cache's node. 10 | pub const Node = struct { 11 | is_visited: bool = false, 12 | prev: ?*Node = null, 13 | next: ?*Node = null, 14 | value: V, 15 | key: K, 16 | }; 17 | 18 | map: HashMapUnmanaged = HashMapUnmanaged{}, 19 | hand: ?*Node = null, 20 | head: ?*Node = null, 21 | tail: ?*Node = null, 22 | 23 | /// Initialize cache with given capacity. 24 | pub fn init(allocator: std.mem.Allocator, capacity: u32) !Self { 25 | var self = Self{}; 26 | try self.map.ensureTotalCapacity(allocator, capacity); 27 | return self; 28 | } 29 | 30 | /// Deinitialize cache. 31 | pub fn deinit(self: *Self, allocator: std.mem.Allocator) void { 32 | self.map.deinit(allocator); 33 | self.* = undefined; 34 | } 35 | 36 | /// Check if cache is empty. 37 | pub fn isEmpty(self: Self) bool { 38 | return self.map.size == 0; 39 | } 40 | 41 | /// Check if cache contains given key. 42 | pub fn contains(self: Self, key: K) bool { 43 | return self.map.contains(key); 44 | } 45 | 46 | /// Retrieve value associated with given key, otherwise return `null`. 47 | pub fn get(self: Self, key: K) ?V { 48 | var node = self.map.get(key) orelse return null; 49 | node.is_visited = true; 50 | return node.value; 51 | } 52 | 53 | /// Put node pointer and return `true` if associated key is not already present. 54 | /// Otherwise, put node pointer, evicting old entry, and return `false`. 55 | pub fn put(self: *Self, node: *Node) !bool { 56 | if (self.map.getPtr(node.key)) |old_node| { 57 | node.is_visited = true; 58 | old_node.* = node; 59 | return false; 60 | } else { 61 | if (self.map.size >= self.map.capacity()) { 62 | self.evict(); 63 | } 64 | 65 | node.next = self.head; 66 | if (self.head) |head| { 67 | head.prev = node; 68 | } 69 | 70 | self.head = node; 71 | if (self.tail == null) { 72 | self.tail = self.head; 73 | } 74 | 75 | self.map.putAssumeCapacityNoClobber(node.key, node); 76 | return true; 77 | } 78 | } 79 | 80 | /// Remove key and return associated value, otherwise return `null`. 81 | pub fn fetchRemove(self: *Self, key: K) ?V { 82 | const node = self.map.get(key) orelse return null; 83 | if (self.hand == node) { 84 | self.hand = node.prev; 85 | } 86 | _ = self.map.remove(key); 87 | self.removeNode(node); 88 | return node.value; 89 | } 90 | 91 | fn removeNode(self: *Self, node: *Node) void { 92 | if (node.prev) |prev| { 93 | prev.next = node.next; 94 | } else { 95 | self.head = node.next; 96 | } 97 | 98 | if (node.next) |next| { 99 | next.prev = node.prev; 100 | } else { 101 | self.tail = node.prev; 102 | } 103 | } 104 | 105 | fn evict(self: *Self) void { 106 | var node_opt = self.hand orelse self.tail; 107 | while (node_opt) |node| : (node_opt = node.prev orelse self.tail) { 108 | if (!node.is_visited) { 109 | break; 110 | } 111 | node.is_visited = false; 112 | } 113 | if (node_opt) |node| { 114 | self.hand = node.prev; 115 | _ = self.map.remove(node.key); 116 | self.removeNode(node); 117 | } 118 | } 119 | }; 120 | } 121 | 122 | test Cache { 123 | { 124 | const StringCache = Cache([]const u8, []const u8); 125 | 126 | var cache = try StringCache.init(std.testing.allocator, 3); 127 | defer cache.deinit(std.testing.allocator); 128 | 129 | var zigzag_node = StringCache.Node{ .key = "zig", .value = "zag" }; 130 | var foobar_node = StringCache.Node{ .key = "foo", .value = "bar" }; 131 | var flipflop_node = StringCache.Node{ .key = "flip", .value = "flop" }; 132 | var ticktock_node = StringCache.Node{ .key = "tick", .value = "tock" }; 133 | 134 | try std.testing.expect(try cache.put(&zigzag_node)); 135 | try std.testing.expect(try cache.put(&foobar_node)); 136 | 137 | try std.testing.expectEqualStrings("bar", cache.fetchRemove("foo").?); 138 | 139 | try std.testing.expect(try cache.put(&flipflop_node)); 140 | try std.testing.expect(try cache.put(&ticktock_node)); 141 | 142 | try std.testing.expectEqualStrings("zag", cache.get("zig").?); 143 | try std.testing.expectEqual(cache.get("foo"), null); 144 | try std.testing.expectEqualStrings("flop", cache.get("flip").?); 145 | try std.testing.expectEqualStrings("tock", cache.get("tick").?); 146 | } 147 | { 148 | const StringCache = Cache([]const u8, []const u8); 149 | 150 | var cache = try StringCache.init(std.testing.allocator, 3); 151 | defer cache.deinit(std.testing.allocator); 152 | 153 | var zigzag_node = StringCache.Node{ .key = "zig", .value = "zag" }; 154 | var zigupd_node = StringCache.Node{ .key = "zig", .value = "upd" }; 155 | var foobar_node = StringCache.Node{ .key = "foo", .value = "bar" }; 156 | var flipflop_node = StringCache.Node{ .key = "flip", .value = "flop" }; 157 | 158 | try std.testing.expect(try cache.put(&zigzag_node)); 159 | try std.testing.expect(try cache.put(&foobar_node)); 160 | try std.testing.expect(!try cache.put(&zigupd_node)); 161 | try std.testing.expect(try cache.put(&flipflop_node)); 162 | 163 | try std.testing.expectEqualStrings("upd", cache.get("zig").?); 164 | } 165 | } 166 | --------------------------------------------------------------------------------