tigerbeetle 0.0.40 → 0.17.8

data/ext/tb_client/tigerbeetle/src/lsm/set_associative_cache.zig

@@ -1,865 +0,0 @@
-const std = @import("std");
-const builtin = @import("builtin");
-
-const assert = std.debug.assert;
-const math = std.math;
-const mem = std.mem;
-const meta = std.meta;
-
-const stdx = @import("stdx");
-
-const div_ceil = stdx.div_ceil;
-const maybe = stdx.maybe;
-const fastrange = stdx.fastrange;
-
-pub const Layout = struct {
-    ways: u64 = 16,
-    tag_bits: u64 = 8,
-    clock_bits: u64 = 2,
-    cache_line_size: u64 = 64,
-    /// Set this to a non-null value to override the alignment of the stored values.
-    value_alignment: ?u29 = null,
-};
-
-const Metrics = struct {
-    hits: u64 = 0,
-    misses: u64 = 0,
-};
-
-/// Each Key is associated with a set of n consecutive ways (or slots) that may contain the Value.
-pub fn SetAssociativeCacheType(
-    comptime Key: type,
-    comptime Value: type,
-    comptime key_from_value: fn (*const Value) callconv(.@"inline") Key,
-    comptime hash: fn (Key) callconv(.@"inline") u64,
-    comptime layout: Layout,
-) type {
-    assert(math.isPowerOfTwo(@sizeOf(Key)));
-    assert(math.isPowerOfTwo(@sizeOf(Value)));
-
-    switch (layout.ways) {
-        // An 8-way set-associative cache has the clock hand as a u3, which would introduce padding.
-        2, 4, 16 => {},
-        else => @compileError("ways must be 2, 4 or 16 for optimal CLOCK hand size."),
-    }
-    switch (layout.tag_bits) {
-        8, 16 => {},
-        else => @compileError("tag_bits must be 8 or 16."),
-    }
-    switch (layout.clock_bits) {
-        1, 2, 4 => {},
-        else => @compileError("clock_bits must be 1, 2 or 4."),
-    }
-
-    if (layout.value_alignment) |alignment| {
-        assert(alignment >= @alignOf(Value));
-        assert(@sizeOf(Value) % alignment == 0);
-    }
-    const value_alignment = layout.value_alignment orelse @alignOf(Value);
-
-    assert(math.isPowerOfTwo(layout.ways));
-    assert(math.isPowerOfTwo(layout.tag_bits));
-    assert(math.isPowerOfTwo(layout.clock_bits));
-    assert(math.isPowerOfTwo(layout.cache_line_size));
-
-    assert(@sizeOf(Key) <= @sizeOf(Value));
-    assert(@sizeOf(Key) < layout.cache_line_size);
-    assert(layout.cache_line_size % @sizeOf(Key) == 0);
-
-    if (layout.cache_line_size > @sizeOf(Value)) {
-        assert(layout.cache_line_size % @sizeOf(Value) == 0);
-    } else {
-        assert(@sizeOf(Value) % layout.cache_line_size == 0);
-    }
-
-    const clock_hand_bits = math.log2_int(u64, layout.ways);
-    assert(math.isPowerOfTwo(clock_hand_bits));
-    assert((1 << clock_hand_bits) == layout.ways);
-
-    const tags_per_line = @divExact(layout.cache_line_size * 8, layout.ways * layout.tag_bits);
-    assert(tags_per_line > 0);
-
-    const clocks_per_line = @divExact(layout.cache_line_size * 8, layout.ways * layout.clock_bits);
-    assert(clocks_per_line > 0);
-
-    const clock_hands_per_line = @divExact(layout.cache_line_size * 8, clock_hand_bits);
-    assert(clock_hands_per_line > 0);
-
-    return struct {
-        const SetAssociativeCache = @This();
-
-        const Tag = meta.Int(.unsigned, layout.tag_bits);
-        const Count = meta.Int(.unsigned, layout.clock_bits);
-        const Clock = meta.Int(.unsigned, clock_hand_bits);
-
-        /// We don't require `value_count_max` in `init` to be a power of 2, but we do require
-        /// it to be a multiple of `value_count_max_multiple`. The calculation below
-        /// follows from a multiple which will satisfy all asserts.
-        pub const value_count_max_multiple: u64 = @max(
-            // `values`:
-            @divExact(
-                @max(@sizeOf(Value), layout.cache_line_size),
-                @min(@sizeOf(Value), layout.cache_line_size),
-            ) * layout.ways,
-            @divExact(layout.cache_line_size * 8, layout.clock_bits), // `counts`
-        );
-
-        name: []const u8,
-        sets: u64,
-
-        metrics: *Metrics,
-
-        /// A short, partial hash of a Key, corresponding to a Value.
-        /// Because the tag is small, collisions are possible:
-        /// `tag(v₁) = tag(v₂)` does not imply `v₁ = v₂`.
-        /// However, most of the time, where the tag differs, a full key comparison can be avoided.
-        /// Since tags are 16-32x smaller than keys, they can also be kept hot in cache.
-        tags: []Tag,
-
-        /// When the corresponding Count is zero, the Value is absent.
-        values: []align(value_alignment) Value,
-
-        /// Each value has a Count, which tracks the number of recent reads.
-        ///
-        /// * A Count is incremented when the value is accessed by `get`.
-        /// * A Count is decremented when a cache write to the value's Set misses.
-        /// * The value is evicted when its Count reaches zero.
-        ///
-        counts: PackedUnsignedIntegerArrayType(Count),
-
-        /// Each set has a Clock: a counter that cycles between each of the set's ways (i.e. slots).
-        ///
-        /// On cache write, entries are checked for occupancy (or eviction) beginning from the
-        /// clock's position, wrapping around.
-        ///
-        /// The algorithm implemented is "CLOCK Nth-Chance" — each way has more than one bit,
-        /// to give ways more than one chance before eviction.
-        ///
-        /// * A similar algorithm called "RRIParoo" is described in
-        ///   "Kangaroo: Caching Billions of Tiny Objects on Flash".
-        /// * For more general information on CLOCK algorithms, see:
-        ///   https://en.wikipedia.org/wiki/Page_replacement_algorithm.
-        clocks: PackedUnsignedIntegerArrayType(Clock),
-
-        pub const Options = struct { name: []const u8 };
-
-        pub fn init(
-            allocator: mem.Allocator,
-            value_count_max: u64,
-            options: Options,
-        ) !SetAssociativeCache {
-            const sets = @divExact(value_count_max, layout.ways);
-
-            assert(value_count_max > 0);
-            assert(value_count_max >= layout.ways);
-            assert(value_count_max % layout.ways == 0);
-
-            const values_size_max = value_count_max * @sizeOf(Value);
-            assert(values_size_max >= layout.cache_line_size);
-            assert(values_size_max % layout.cache_line_size == 0);
-
-            const counts_size = @divExact(value_count_max * layout.clock_bits, 8);
-            assert(counts_size >= layout.cache_line_size);
-            assert(counts_size % layout.cache_line_size == 0);
-
-            // Each clock hand is guaranteed (by comptime asserts) to not span multiple cache lines.
-            // But in order to shrink the lower-bound cache size, we do not require that `clocks`
-            // itself is a multiple of the cache line size.
-            const clocks_size = @divExact(sets * clock_hand_bits, 8);
-            maybe(clocks_size >= layout.cache_line_size);
-            maybe(clocks_size % layout.cache_line_size == 0);
-
-            assert(value_count_max % value_count_max_multiple == 0);
-
-            const tags = try allocator.alloc(Tag, value_count_max);
-            errdefer allocator.free(tags);
-
-            const values = try allocator.alignedAlloc(
-                Value,
-                value_alignment,
-                value_count_max,
-            );
-            errdefer allocator.free(values);
-
-            const counts = try allocator.alloc(u64, @divExact(counts_size, @sizeOf(u64)));
-            errdefer allocator.free(counts);
-
-            const clocks = try allocator.alloc(u64, div_ceil(clocks_size, @sizeOf(u64)));
-            errdefer allocator.free(clocks);
-
-            // Explicitly allocated so that get / get_index can be `*const SetAssociativeCache`.
-            const metrics = try allocator.create(Metrics);
-            errdefer allocator.destroy(metrics);
-
-            var self = SetAssociativeCache{
-                .name = options.name,
-                .sets = sets,
-                .tags = tags,
-                .values = values,
-                .counts = .{ .words = counts },
-                .clocks = .{ .words = clocks },
-                .metrics = metrics,
-            };
-
-            self.reset();
-
-            return self;
-        }
-
-        pub fn deinit(self: *SetAssociativeCache, allocator: mem.Allocator) void {
-            assert(self.sets > 0);
-            self.sets = 0;
-
-            allocator.free(self.tags);
-            allocator.free(self.values);
-            allocator.free(self.counts.words);
-            allocator.free(self.clocks.words);
-            allocator.destroy(self.metrics);
-        }
-
-        pub fn reset(self: *SetAssociativeCache) void {
-            @memset(self.tags, 0);
-            @memset(self.counts.words, 0);
-            @memset(self.clocks.words, 0);
-            self.metrics.* = .{};
-        }
-
-        pub fn get_index(self: *const SetAssociativeCache, key: Key) ?usize {
-            const set = self.associate(key);
-            if (self.search(set, key)) |way| {
-                self.metrics.hits += 1;
-                const count = self.counts.get(set.offset + way);
-                self.counts.set(set.offset + way, count +| 1);
-                return set.offset + way;
-            } else {
-                self.metrics.misses += 1;
-                return null;
-            }
-        }
-
-        pub fn get(self: *const SetAssociativeCache, key: Key) ?*align(value_alignment) Value {
-            const index = self.get_index(key) orelse return null;
-            return @alignCast(&self.values[index]);
-        }
-
-        /// Remove a key from the set associative cache if present.
-        /// Returns the removed value, if any.
-        pub fn remove(self: *SetAssociativeCache, key: Key) ?Value {
-            const set = self.associate(key);
-            const way = self.search(set, key) orelse return null;
-
-            const removed: Value = set.values[way];
-            self.counts.set(set.offset + way, 0);
-            set.values[way] = undefined;
-
-            return removed;
-        }
-
-        /// Hint that the key is less likely to be accessed in the future, without actually removing
-        /// it from the cache.
-        pub fn demote(self: *SetAssociativeCache, key: Key) void {
-            const set = self.associate(key);
-            const way = self.search(set, key) orelse return;
-
-            self.counts.set(set.offset + way, 1);
-        }
-
-        /// If the key is present in the set, returns the way. Otherwise returns null.
-        inline fn search(self: *const SetAssociativeCache, set: Set, key: Key) ?u16 {
-            const ways: u16 = search_tags(set.tags, set.tag);
-            if (ways == 0) return null;
-
-            // Iterate over all ways to help the OOO execution.
-            for (0..layout.ways) |way| {
-                if ((ways >> @as(u4, @intCast(way)) & 1) == 1 and
-                    self.counts.get(set.offset + way) > 0)
-                {
-                    if (key_from_value(&set.values[way]) == key) {
-                        return @intCast(way);
-                    }
-                }
-            }
-            return null;
-        }
-
-        /// Where each set bit represents the index of a way that has the same tag.
-        const Ways = meta.Int(.unsigned, layout.ways);
-
-        inline fn search_tags(tags: *const [layout.ways]Tag, tag: Tag) Ways {
-            const x: @Vector(layout.ways, Tag) = tags.*;
-            const y: @Vector(layout.ways, Tag) = @splat(tag);
-
-            const result: @Vector(layout.ways, bool) = x == y;
-            return @bitCast(result);
-        }
-
-        /// Upsert a value, evicting an older entry if needed. The evicted value, if an update or
-        /// insert was performed and the index at which the value was inserted is returned.
-        pub fn upsert(self: *SetAssociativeCache, value: *const Value) struct {
-            index: usize,
-            updated: UpdateOrInsert,
-            evicted: ?Value,
-        } {
-            const key = key_from_value(value);
-            const set = self.associate(key);
-            if (self.search(set, key)) |way| {
-                // Overwrite the old entry for this key.
-                self.counts.set(set.offset + way, 1);
-                const evicted = set.values[way];
-                set.values[way] = value.*;
-                return .{
-                    .index = set.offset + way,
-                    .updated = .update,
-                    .evicted = evicted,
-                };
-            }
-
-            const clock_index = @divExact(set.offset, layout.ways);
-
-            var way = self.clocks.get(clock_index);
-            comptime assert(math.maxInt(@TypeOf(way)) == layout.ways - 1);
-            comptime assert(@as(@TypeOf(way), math.maxInt(@TypeOf(way))) +% 1 == 0);
-
-            // The maximum number of iterations happens when every slot in the set has the maximum
-            // count. In this case, the loop will iterate until all counts have been decremented
-            // to 1. Then in the next iteration it will decrement a count to 0 and break.
-            const clock_iterations_max = layout.ways * (math.maxInt(Count) - 1);
-
-            var evicted: ?Value = null;
-            var safety_count: usize = 0;
-            while (safety_count <= clock_iterations_max) : ({
-                safety_count += 1;
-                way +%= 1;
-            }) {
-                var count = self.counts.get(set.offset + way);
-                if (count == 0) break; // Way is already free.
-
-                count -= 1;
-                self.counts.set(set.offset + way, count);
-                if (count == 0) {
-                    // Way has become free.
-                    evicted = set.values[way];
-                    break;
-                }
-            } else {
-                unreachable;
-            }
-            assert(self.counts.get(set.offset + way) == 0);
-
-            set.tags[way] = set.tag;
-            set.values[way] = value.*;
-            self.counts.set(set.offset + way, 1);
-            self.clocks.set(clock_index, way +% 1);
-
-            return .{
-                .index = set.offset + way,
-                .updated = .insert,
-                .evicted = evicted,
-            };
-        }
-
-        const Set = struct {
-            tag: Tag,
-            offset: u64,
-            tags: *[layout.ways]Tag,
-            values: *[layout.ways]Value,
-
-            fn inspect(set: Set, sac: SetAssociativeCache) void {
-                const clock_index = @divExact(set.offset, layout.ways);
-                std.debug.print(
-                    \\{{
-                    \\  tag={}
-                    \\  offset={}
-                    \\  clock_hand={}
-                , .{
-                    set.tag,
-                    set.offset,
-                    sac.clocks.get(clock_index),
-                });
-
-                std.debug.print("\n  tags={}", .{set.tags[0]});
-                for (set.tags[1..]) |tag| std.debug.print(", {}", .{tag});
-
-                std.debug.print("\n  values={}", .{set.values[0]});
-                for (set.values[1..]) |value| std.debug.print(", {}", .{value});
-
-                std.debug.print("\n  counts={}", .{sac.counts.get(set.offset)});
-                var i: usize = 1;
-                while (i < layout.ways) : (i += 1) {
-                    std.debug.print(", {}", .{sac.counts.get(set.offset + i)});
-                }
-
-                std.debug.print("\n}}\n", .{});
-            }
-        };
-
-        inline fn associate(self: *const SetAssociativeCache, key: Key) Set {
-            const entropy = hash(key);
-
-            const tag: Tag = @truncate(entropy);
-            const index = fastrange(entropy, self.sets);
-            const offset = index * layout.ways;
-
-            return .{
-                .tag = tag,
-                .offset = offset,
-                .tags = self.tags[offset..][0..layout.ways],
-                .values = self.values[offset..][0..layout.ways],
-            };
-        }
-
-        pub fn inspect() void {
-            std.debug.print("\nKey={} Value={} ways={} tag_bits={} clock_bits={} " ++
-                "clock_hand_bits={} tags_per_line={} clocks_per_line={} " ++
-                "clock_hands_per_line={}\n", .{
-                @bitSizeOf(Key),
-                @sizeOf(Value),
-                layout.ways,
-                layout.tag_bits,
-                layout.clock_bits,
-                clock_hand_bits,
-                tags_per_line,
-                clocks_per_line,
-                clock_hands_per_line,
-            });
-        }
-    };
-}
-
-pub const UpdateOrInsert = enum { update, insert };
-
-fn set_associative_cache_test(
-    comptime Key: type,
-    comptime Value: type,
-    comptime context: type,
-    comptime layout: Layout,
-) type {
-    const testing = std.testing;
-    const expect = testing.expect;
-    const expectEqual = testing.expectEqual;
-
-    const log = false;
-
-    const SAC = SetAssociativeCacheType(
-        Key,
-        Value,
-        context.key_from_value,
-        context.hash,
-        layout,
-    );
-
-    return struct {
-        fn run() !void {
-            if (log) SAC.inspect();
-
-            // TODO Add a nice calculator method to help solve the minimum value_count_max required:
-            var sac = try SAC.init(testing.allocator, 16 * 16 * 8, .{ .name = "test" });
-            defer sac.deinit(testing.allocator);
-
-            for (sac.tags) |tag| try testing.expectEqual(@as(SAC.Tag, 0), tag);
-            for (sac.counts.words) |word| try testing.expectEqual(@as(u64, 0), word);
-            for (sac.clocks.words) |word| try testing.expectEqual(@as(u64, 0), word);
-
-            // Fill up the first set entirely.
-            {
-                var i: usize = 0;
-                while (i < layout.ways) : (i += 1) {
-                    try expectEqual(i, sac.clocks.get(0));
-
-                    const key = i * sac.sets;
-                    _ = sac.upsert(&key);
-                    try expect(sac.counts.get(i) == 1);
-                    try expectEqual(key, sac.get(key).?.*);
-                    try expect(sac.counts.get(i) == 2);
-                }
-                try expect(sac.clocks.get(0) == 0);
-            }
-
-            if (log) sac.associate(0).inspect(sac);
-
-            // Insert another element into the first set, causing key 0 to be evicted.
-            {
-                const key = layout.ways * sac.sets;
-                _ = sac.upsert(&key);
-                try expect(sac.counts.get(0) == 1);
-                try expectEqual(key, sac.get(key).?.*);
-                try expect(sac.counts.get(0) == 2);
-
-                try expectEqual(@as(?*Value, null), sac.get(0));
-
-                {
-                    var i: usize = 1;
-                    while (i < layout.ways) : (i += 1) {
-                        try expect(sac.counts.get(i) == 1);
-                    }
-                }
-            }
-
-            if (log) sac.associate(0).inspect(sac);
-
-            // Ensure removal works.
-            {
-                const key = 5 * sac.sets;
-                assert(sac.get(key).?.* == key);
-                try expect(sac.counts.get(5) == 2);
-
-                _ = sac.remove(key);
-                try expectEqual(@as(?*Value, null), sac.get(key));
-                try expect(sac.counts.get(5) == 0);
-            }
-
-            sac.reset();
-
-            for (sac.tags) |tag| try testing.expectEqual(@as(SAC.Tag, 0), tag);
-            for (sac.counts.words) |word| try testing.expectEqual(@as(u64, 0), word);
-            for (sac.clocks.words) |word| try testing.expectEqual(@as(u64, 0), word);
-
-            // Fill up the first set entirely, maxing out the count for each slot.
-            {
-                var i: usize = 0;
-                while (i < layout.ways) : (i += 1) {
-                    try expectEqual(i, sac.clocks.get(0));
-
-                    const key = i * sac.sets;
-                    _ = sac.upsert(&key);
-                    try expect(sac.counts.get(i) == 1);
-                    var j: usize = 2;
-                    while (j <= math.maxInt(SAC.Count)) : (j += 1) {
-                        try expectEqual(key, sac.get(key).?.*);
-                        try expect(sac.counts.get(i) == j);
-                    }
-                    try expectEqual(key, sac.get(key).?.*);
-                    try expect(sac.counts.get(i) == math.maxInt(SAC.Count));
-                }
-                try expect(sac.clocks.get(0) == 0);
-            }
-
-            if (log) sac.associate(0).inspect(sac);
-
-            // Insert another element into the first set, causing key 0 to be evicted.
-            {
-                const key = layout.ways * sac.sets;
-                _ = sac.upsert(&key);
-                try expect(sac.counts.get(0) == 1);
-                try expectEqual(key, sac.get(key).?.*);
-                try expect(sac.counts.get(0) == 2);
-
-                try expectEqual(@as(?*Value, null), sac.get(0));
-
-                {
-                    var i: usize = 1;
-                    while (i < layout.ways) : (i += 1) {
-                        try expect(sac.counts.get(i) == 1);
-                    }
-                }
-            }
-
-            if (log) sac.associate(0).inspect(sac);
-        }
-    };
-}
-
-test "SetAssociativeCache: eviction" {
-    const Key = u64;
-    const Value = u64;
-
-    const context = struct {
-        inline fn key_from_value(value: *const Value) Key {
-            return value.*;
-        }
-        inline fn hash(key: Key) u64 {
-            return key;
-        }
-    };
-
-    try set_associative_cache_test(Key, Value, context, .{}).run();
-}
-
-test "SetAssociativeCache: hash collision" {
-    const Key = u64;
-    const Value = u64;
-
-    const context = struct {
-        inline fn key_from_value(value: *const Value) Key {
-            return value.*;
-        }
-        /// This hash function is intentionally broken to simulate hash collision.
-        inline fn hash(key: Key) u64 {
-            _ = key;
-            return 0;
-        }
-        inline fn equal(a: Key, b: Key) bool {
-            return a == b;
-        }
-    };
-
-    try set_associative_cache_test(Key, Value, context, .{}).run();
-}
-
-/// A little simpler than PackedIntArray in the std lib, restricted to little endian 64-bit words,
-/// and using words exactly without padding.
-fn PackedUnsignedIntegerArrayType(comptime UInt: type) type {
-    const Word = u64;
-
-    assert(builtin.target.cpu.arch.endian() == .little);
-    assert(@typeInfo(UInt).int.signedness == .unsigned);
-    assert(@typeInfo(UInt).int.bits < @bitSizeOf(u8));
-    assert(math.isPowerOfTwo(@typeInfo(UInt).int.bits));
-
-    const word_bits = @bitSizeOf(Word);
-    const uint_bits = @bitSizeOf(UInt);
-    const uints_per_word = @divExact(word_bits, uint_bits);
-
-    // An index bounded by the number of unsigned integers that fit exactly into a word.
-    const WordIndex = meta.Int(.unsigned, math.log2_int(u64, uints_per_word));
-    assert(math.maxInt(WordIndex) == uints_per_word - 1);
-
-    // An index bounded by the number of bits (not unsigned integers) that fit exactly into a word.
-    const BitsIndex = math.Log2Int(Word);
-    assert(math.maxInt(BitsIndex) == @bitSizeOf(Word) - 1);
-    assert(math.maxInt(BitsIndex) == word_bits - 1);
-    assert(math.maxInt(BitsIndex) == uint_bits * (math.maxInt(WordIndex) + 1) - 1);
-
-    return struct {
-        const PackedUnsignedIntegerArray = @This();
-
-        words: []Word,
-
-        /// Returns the unsigned integer at `index`.
-        pub inline fn get(self: PackedUnsignedIntegerArray, index: u64) UInt {
-            // This truncate is safe since we want to mask the right-shifted word by exactly a UInt:
-            return @as(UInt, @truncate(self.word(index).* >> bits_index(index)));
-        }
-
-        /// Sets the unsigned integer at `index` to `value`.
-        pub inline fn set(self: PackedUnsignedIntegerArray, index: u64, value: UInt) void {
-            const w = self.word(index);
-            w.* &= ~mask(index);
-            w.* |= @as(Word, value) << bits_index(index);
-        }
-
-        inline fn mask(index: u64) Word {
-            return @as(Word, math.maxInt(UInt)) << bits_index(index);
-        }
-
-        inline fn word(self: PackedUnsignedIntegerArray, index: u64) *Word {
-            return &self.words[@divFloor(index, uints_per_word)];
-        }
-
-        inline fn bits_index(index: u64) BitsIndex {
-            // If uint_bits=2, then it's normal for the maximum return value value to be 62, even
-            // where BitsIndex allows up to 63 (inclusive) for a 64-bit word. This is because 62 is
-            // the bit index of the highest 2-bit UInt (e.g. bit index + bit length == 64).
-            comptime assert(uint_bits * (math.maxInt(WordIndex) + 1) == math.maxInt(BitsIndex) + 1);
-
-            return @as(BitsIndex, uint_bits) * @as(WordIndex, @truncate(index));
-        }
-    };
-}
-
-test "PackedUnsignedIntegerArray: unit" {
-    const expectEqual = std.testing.expectEqual;
-
-    var words = [8]u64{ 0, 0b10110010, 0, 0, 0, 0, 0, 0 };
-
-    var p: PackedUnsignedIntegerArrayType(u2) = .{
-        .words = &words,
-    };
-
-    try expectEqual(@as(u2, 0b10), p.get(32 + 0));
-    try expectEqual(@as(u2, 0b00), p.get(32 + 1));
-    try expectEqual(@as(u2, 0b11), p.get(32 + 2));
-    try expectEqual(@as(u2, 0b10), p.get(32 + 3));
-
-    p.set(0, 0b01);
-    try expectEqual(@as(u64, 0b00000001), words[0]);
-    try expectEqual(@as(u2, 0b01), p.get(0));
-    p.set(1, 0b10);
-    try expectEqual(@as(u64, 0b00001001), words[0]);
-    try expectEqual(@as(u2, 0b10), p.get(1));
-    p.set(2, 0b11);
-    try expectEqual(@as(u64, 0b00111001), words[0]);
-    try expectEqual(@as(u2, 0b11), p.get(2));
-    p.set(3, 0b11);
-    try expectEqual(@as(u64, 0b11111001), words[0]);
-    try expectEqual(@as(u2, 0b11), p.get(3));
-    p.set(3, 0b01);
-    try expectEqual(@as(u64, 0b01111001), words[0]);
-    try expectEqual(@as(u2, 0b01), p.get(3));
-    p.set(3, 0b00);
-    try expectEqual(@as(u64, 0b00111001), words[0]);
-    try expectEqual(@as(u2, 0b00), p.get(3));
-
-    p.set(4, 0b11);
-    try expectEqual(
-        @as(u64, 0b0000000000000000000000000000000000000000000000000000001100111001),
-        words[0],
-    );
-    p.set(31, 0b11);
-    try expectEqual(
-        @as(u64, 0b1100000000000000000000000000000000000000000000000000001100111001),
-        words[0],
-    );
-}
-
-fn ContextType(comptime UInt: type) type {
-    const testing = std.testing;
-
-    return struct {
-        const Context = @This();
-
-        const Array = PackedUnsignedIntegerArrayType(UInt);
-        prng: *stdx.PRNG,
-
-        array: Array,
-        reference: []UInt,
-
-        fn init(prng: *stdx.PRNG, len: usize) !Context {
-            const words = try testing.allocator.alloc(u64, @divExact(len * @bitSizeOf(UInt), 64));
-            errdefer testing.allocator.free(words);
-
-            const reference = try testing.allocator.alloc(UInt, len);
-            errdefer testing.allocator.free(reference);
-
-            @memset(words, 0);
-            @memset(reference, 0);
-
-            return .{
-                .prng = prng,
-                .array = Array{ .words = words },
-                .reference = reference,
-            };
-        }
-
-        fn deinit(context: *Context) void {
-            testing.allocator.free(context.array.words);
-            testing.allocator.free(context.reference);
-        }
-
-        fn run(context: *Context) !void {
-            var iterations: usize = 0;
-            while (iterations < 10_000) : (iterations += 1) {
-                const index = context.prng.index(context.reference);
-                const value = context.prng.int(UInt);
-
-                context.array.set(index, value);
-                context.reference[index] = value;
-
-                try context.verify();
-            }
-        }
-
-        fn verify(context: *Context) !void {
-            for (context.reference, 0..) |value, index| {
-                try testing.expectEqual(value, context.array.get(index));
-            }
-        }
-    };
-}
-
-test "PackedUnsignedIntegerArray: fuzz" {
-    const seed = 42;
-    var prng = stdx.PRNG.from_seed(seed);
-
-    inline for (.{ u1, u2, u4 }) |UInt| {
-        const Context = ContextType(UInt);
-
-        var context = try Context.init(&prng, 1024);
-        defer context.deinit();
-
-        try context.run();
-    }
-}
-
-fn search_tags_test(comptime Key: type, comptime Value: type, comptime layout: Layout) type {
-    const testing = std.testing;
-
-    const log = false;
-
-    const context = struct {
-        inline fn key_from_value(value: *const Value) Key {
-            return value.*;
-        }
-        inline fn hash(key: Key) u64 {
-            return key;
-        }
-        inline fn equal(a: Key, b: Key) bool {
-            return a == b;
-        }
-    };
-
-    const SAC = SetAssociativeCacheType(
-        Key,
-        Value,
-        context.key_from_value,
-        context.hash,
-        layout,
-    );
-
-    const reference = struct {
-        inline fn search_tags(tags: *[layout.ways]SAC.Tag, tag: SAC.Tag) SAC.Ways {
-            var bits: SAC.Ways = 0;
-            var count: usize = 0;
-            for (tags, 0..) |t, i| {
-                if (t == tag) {
-                    const bit: math.Log2Int(SAC.Ways) = @intCast(i);
-                    bits |= (@as(SAC.Ways, 1) << bit);
-                    count += 1;
-                }
-            }
-            assert(@popCount(bits) == count);
-            return bits;
-        }
-    };
-
-    return struct {
-        fn run(prng: *stdx.PRNG) !void {
-            if (log) SAC.inspect();
-
-            var iterations: usize = 0;
-            while (iterations < 10_000) : (iterations += 1) {
-                var tags: [layout.ways]SAC.Tag = undefined;
-                prng.fill(mem.asBytes(&tags));
-
-                const tag = prng.int(SAC.Tag);
-
-                var indexes: [layout.ways]usize = undefined;
-                for (&indexes, 0..) |*x, i| x.* = i;
-                prng.shuffle(usize, &indexes);
-
-                const matches_count_min = prng.int_inclusive(u32, layout.ways);
-                for (indexes[0..matches_count_min]) |index| {
-                    tags[index] = tag;
-                }
-
-                const expected = reference.search_tags(&tags, tag);
-                const actual = SAC.search_tags(&tags, tag);
-                if (log) std.debug.print("expected: {b:0>16}, actual: {b:0>16}\n", .{
-                    expected,
-                    actual,
-                });
-                try testing.expectEqual(expected, actual);
-            }
-        }
-    };
-}
-
-test "SetAssociativeCache: search_tags()" {
-    const seed = 42;
-
-    const Key = u64;
-    const Value = u64;
-
-    var prng = stdx.PRNG.from_seed(seed);
-
-    inline for ([_]u64{ 2, 4, 16 }) |ways| {
-        inline for ([_]u64{ 8, 16 }) |tag_bits| {
-            const case = search_tags_test(Key, Value, .{
-                .ways = ways,
-                .tag_bits = tag_bits,
-            });
-
-            try case.run(&prng);
-        }
-    }
-}