tiny.sql.FileReadCache

1pub const ReadCache = struct {2    pub const storage_alignment: usize = @alignOf(ReadCacheKey);3    pub const Storage = []align(storage_alignment) u8;45    pub const Limits = struct {6        pages: usize,7    };89    pub const Capacity = struct {10        pages: usize,11        storage_bytes: usize,1213        pub fn derive(limits: Limits) error{CapacityOverflow}!Capacity {14            const key_bytes = std.math.mul(usize, limits.pages, @sizeOf(ReadCacheKey)) catch {15                return error.CapacityOverflow;16            };17            const image_bytes = std.math.mul(usize, limits.pages, @sizeOf(ReadCacheImage)) catch {18                return error.CapacityOverflow;19            };20            const storage_bytes = std.math.add(usize, key_bytes, image_bytes) catch {21                return error.CapacityOverflow;22            };23            return .{24                .pages = limits.pages,25                .storage_bytes = storage_bytes,26            };27        }28    };2930    pub const InitError = error{ CapacityOverflow, StorageTooShort };31    pub const Exhaustion = error{CacheDisabled};32    pub const work_limits: alloc_phase.capacity.WorkLimits = .{33        .transition_steps_max = std.math.maxInt(usize),34        .cleanup_steps_per_call_max = 0,35        .cleanup_calls_at_capacity_max = 0,36    };3738    pub const claim: alloc_phase.capacity.Declaration = .{39        .source = .{40            .id = "sql.file_read_cache",41            .kind = .phase_static,42            .limit_source = .caller,43            .storage = .{44                .covered = &.{45                    .{46                        .id = "configured_direct_mapped_base_page_cache_slots_for_94cfd2eab286",47                        .lifetime = .steady,48                        .detail = "configured direct-mapped base-page cache slots for lazy and durable-checkpoint reads",49                    },50                },51                .excluded = &.{52                    "operating-system page cache, database and WAL file contents, and file handles",53                    "pager-owned WAL images, indexes, prepared checkpoint descriptors, and reader-bearing in-memory base history",54                    "caller-owned copyPage destination images and trace instrumentation",55                },56            },57            .capacity = .{58                .inputs = &.{59                    alloc_phase.capacity.bindInput(Limits, "pages", "pages"),60                },61                .type_selectors = &.{62                    alloc_phase.capacity.bindType(ReadCacheKey, "readcachekey"),63                    alloc_phase.capacity.bindType(ReadCacheImage, "readcacheimage"),64                },65                .nodes = &.{66                    .{ .input = 0 },67                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },68                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 1 } } },69                    .{ .add = .{ .left = 1, .right = 2 } },70                },71                .assertions = &.{.{72                    .scope = .closure_total,73                    .measure = .retained,74                    .relation = .exact,75                    .expression = 3,76                }},77            },78            .overload = .{79                .kind = .reject_before_mutation,80                .detail = "short caller storage rejects initialization and zero cache capacity returns CacheDisabled before mutation; admitted positive capacity replaces exactly page_id modulo slots",81            },82            .risks = .{83                .transitive = .{84                    .status = .open,85                    .detail = "cache methods are allocation-free value copies, but no machine call-graph certificate excludes future transitive growth",86                },87                .foreign = .{88                    .status = .excluded,89                    .detail = "file reads durable checkpoint writes and the operating-system page cache are outside the owner-local heap-storage claim",90                },91            },92            .work = .{93                .equation = "initialization and clear visit only the contiguous key bound, occupancy counting visits the admitted key bound, and get and put take constant steps",94            },95            .obligations = &.{96                .{ .key = "sql_read_cache_capacity", .role = .capacity_model },97                .{ .key = "sql_read_cache_storage_rejection", .role = .initialization_failure },98                .{ .key = "sql_read_cache_sealed_overload", .role = .overload },99                .{ .key = "sql_read_cache_work_bound", .role = .work_bound },100                .{ .key = "sql_read_cache_sealed_transitive_risk", .role = .transitive_risk },101                .{ .key = "sql_read_cache_semantics_overload", .role = .overload },102                .{ .key = "sql_read_cache_semantics_foreign_risk", .role = .foreign_risk },103                .{ .key = "sql_read_cache_checkpoint_semantics", .role = .foreign_risk },104            },105        },106        .bindings = .{107            .owner = @This(),108            .seal = .{109                .family = alloc_phase.capacity.selector(@This().activate),110                .premise = .{111                    .class = .checked_semantic_fact,112                    .authority = .checker,113                },114            },115            .teardown = .{116                .family = alloc_phase.capacity.selector(@This().deinit),117                .premise = .{118                    .class = .checked_semantic_fact,119                    .authority = .checker,120                },121            },122        },123    };124125    phase: alloc_phase.capacity.Phase,126    capacity: Capacity,127    storage: Storage,128    keys: []ReadCacheKey,129130    pub fn init(storage: Storage, limits: Limits) InitError!ReadCache {131        const capacity = try Capacity.derive(limits);132        if (storage.len < capacity.storage_bytes) return error.StorageTooShort;133        const borrowed = storage[0..capacity.storage_bytes];134        const keys = keysFromStorage(borrowed, capacity);135        for (keys) |*key| key.* = .{ .generation = 0, .page_id = 0 };136        return .{137            .phase = .initialization,138            .capacity = capacity,139            .storage = borrowed,140            .keys = keys,141        };142    }143144    pub fn activate(self: *ReadCache) void {145        std.debug.assert(self.phase == .initialization);146        std.debug.assert(self.keys.len == self.capacity.pages);147        std.debug.assert(imagesFromStorage(self.storage, self.capacity).len == self.capacity.pages);148        self.phase = .steady;149    }150151    pub fn deinit(self: *ReadCache) Storage {152        std.debug.assert(self.phase != .teardown);153        std.debug.assert(self.storage.len == self.capacity.storage_bytes);154        std.debug.assert(self.keys.len == self.capacity.pages);155        std.debug.assert(self.keys.ptr == keysFromStorage(self.storage, self.capacity).ptr);156        self.phase = .teardown;157        const storage = self.storage;158        self.* = undefined;159        return storage;160    }161162    fn clearRetainingCapacity(self: *ReadCache) void {163        std.debug.assert(self.phase == .steady);164        for (self.keys) |*key| key.* = .{ .generation = 0, .page_id = 0 };165    }166167    fn get(self: *ReadCache, key: ReadCacheKey, image: *[page.size]u8) bool {168        std.debug.assert(self.phase == .steady);169        std.debug.assert(key.page_id != 0);170        if (self.keys.len == 0) return false;171        const slot = cacheSlot(key, self.keys.len);172        const cached = self.keys[slot];173        if (cached.generation != key.generation or cached.page_id != key.page_id) return false;174        image.* = imagesFromStorage(self.storage, self.capacity)[slot];175        return true;176    }177178    pub fn put(self: *ReadCache, key: ReadCacheKey, image: *const [page.size]u8) Exhaustion!void {179        std.debug.assert(self.phase == .steady);180        std.debug.assert(key.page_id != 0);181        if (self.keys.len == 0) return error.CacheDisabled;182        const slot = cacheSlot(key, self.keys.len);183        imagesFromStorage(self.storage, self.capacity)[slot] = image.*;184        self.keys[slot] = .{ .generation = key.generation, .page_id = key.page_id };185    }186187    /// Returns the check mark of the cached image for `key`, or null when the188    /// cache does not hold that image.189    fn checkMark(self: *ReadCache, key: ReadCacheKey) ?*bool {190        std.debug.assert(self.phase == .steady);191        if (self.keys.len == 0) return null;192        const cached = &self.keys[cacheSlot(key, self.keys.len)];193        if (cached.generation != key.generation or cached.page_id != key.page_id) return null;194        return &cached.checked;195    }196197    fn count(self: *const ReadCache) usize {198        std.debug.assert(self.phase == .steady);199        var total: usize = 0;200        for (self.keys) |key| {201            if (key.page_id != 0) total += 1;202        }203        return total;204    }205206    fn keysFromStorage(storage: Storage, capacity: Capacity) []ReadCacheKey {207        return std.mem.bytesAsSlice(ReadCacheKey, storage[0..keyBytes(capacity)]);208    }209210    fn imagesFromStorage(storage: Storage, capacity: Capacity) []ReadCacheImage {211        return std.mem.bytesAsSlice(212            ReadCacheImage,213            storage[keyBytes(capacity)..capacity.storage_bytes],214        );215    }216217    fn keyBytes(capacity: Capacity) usize {218        return std.math.mul(usize, capacity.pages, @sizeOf(ReadCacheKey)) catch unreachable;219    }220};

1pub const FileReadCache = file.ReadCache;