tiny.sql.CheckpointPlan

1pub const CheckpointPlan = struct {2    pub const storage_alignment: usize = @alignOf(CheckpointPage);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 const DeriveError = error{CapacityOverflow};1415        pub fn derive(limits: Limits) DeriveError!@This() {16            return .{17                .pages = limits.pages,18                .storage_bytes = std.math.mul(usize, limits.pages, @sizeOf(CheckpointPage)) catch return error.CapacityOverflow,19            };20        }21    };2223    pub const InitError = CheckpointPlan.Capacity.DeriveError || error{StorageTooShort};24    pub const Exhaustion = error{25        CheckpointPlanCapacityExceeded,26        CheckpointPlanInUse,27    };28    pub const work_limits: alloc_phase.capacity.WorkLimits = .{29        .transition_steps_max = 1,30        .cleanup_steps_per_call_max = 0,31        .cleanup_calls_at_capacity_max = 0,32    };3334    pub const claim: alloc_phase.capacity.Declaration = .{35        .source = .{36            .id = "sql.checkpoint_plan",37            .kind = .phase_static,38            .limit_source = .caller,39            .storage = .{40                .covered = &.{41                    .{42                        .id = "reusable_maximum_latest_committed_wal_page_descript_860da2340194",43                        .lifetime = .steady,44                        .detail = "exclusive mutable loan for the reusable maximum latest committed WAL page descriptors for one prepared or synchronous checkpoint",45                    },46                },47                .excluded = &.{48                    "pager base images, WAL page bytes, frame and page indexes, and reader snapshots",49                    "file handles, base-file writes, WAL rewrites, and operating-system cache state",50                    "prepared checkpoint metadata, caller state, and trace instrumentation",51                },52            },53            .capacity = .{54                .inputs = &.{55                    alloc_phase.capacity.bindInput(Limits, "pages", "pages"),56                },57                .type_selectors = &.{58                    alloc_phase.capacity.bindType(CheckpointPage, "checkpointpage"),59                },60                .nodes = &.{61                    .{ .input = 0 },62                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },63                },64                .assertions = &.{.{65                    .scope = .closure_total,66                    .measure = .retained,67                    .relation = .exact,68                    .expression = 1,69                }},70            },71            .overload = .{72                .kind = .reject_before_mutation,73                .detail = "checked descriptor arithmetic and short caller storage reject before activation; begin rejects max plus one and concurrent use before clearing the reusable prefix",74            },75            .risks = .{76                .transitive = .{77                    .status = .witnessed,78                    .detail = "WAL page selection and descriptor page views remain allocation-free across repeated prepared and durable checkpoints after plan initialization",79                },80                .foreign = .{81                    .status = .excluded,82                    .detail = "base-file writes consume borrowed immutable WAL page bytes and WAL rewrite effects occur outside the plan-owned descriptor claim",83                },84            },85            .work = .{ .equation = "transition_steps <= transition_steps_max" },86            .obligations = &.{87                .{ .key = "sql_checkpoint_plan_capacity", .role = .capacity_model },88                .{ .key = "sql_checkpoint_plan_storage_rejection", .role = .initialization_failure },89                .{ .key = "sql_checkpoint_plan_sealed_overload", .role = .overload },90                .{ .key = "sql_checkpoint_plan_work_bound", .role = .work_bound },91                .{ .key = "sql_checkpoint_plan_sealed_transitive_risk", .role = .transitive_risk },92                .{ .key = "sql_checkpoint_plan_semantics_transitive_risk", .role = .transitive_risk },93                .{ .key = "sql_checkpoint_plan_semantics_foreign_risk", .role = .foreign_risk },94            },95        },96        .bindings = .{97            .owner = @This(),98            .seal = .{99                .family = alloc_phase.capacity.selector(@This().activate),100                .premise = .{101                    .class = .checked_semantic_fact,102                    .authority = .checker,103                },104            },105            .teardown = .{106                .family = alloc_phase.capacity.selector(@This().deinit),107                .premise = .{108                    .class = .checked_semantic_fact,109                    .authority = .checker,110                },111            },112        },113    };114115    phase: alloc_phase.capacity.Phase,116    capacity: CheckpointPlan.Capacity,117    storage: CheckpointPlan.Storage,118    filled: usize = 0,119    admitted: usize = 0,120    in_use: bool = false,121122    pub fn init(storage: CheckpointPlan.Storage, limits: Limits) InitError!CheckpointPlan {123        const capacity = try CheckpointPlan.Capacity.derive(limits);124        if (storage.len < capacity.storage_bytes) return error.StorageTooShort;125        return .{126            .phase = .initialization,127            .capacity = capacity,128            .storage = storage[0..capacity.storage_bytes],129        };130    }131132    pub fn begin(self: *CheckpointPlan, required_pages: usize) error{133        CheckpointPlanCapacityExceeded,134        CheckpointPlanInUse,135    }!void {136        std.debug.assert(self.phase == .steady);137        if (self.in_use) return error.CheckpointPlanInUse;138        if (required_pages > self.capacity.pages) return error.CheckpointPlanCapacityExceeded;139        self.filled = 0;140        self.admitted = required_pages;141        self.in_use = true;142    }143144    pub fn append(self: *CheckpointPlan, checkpoint_page: CheckpointPage) error{CheckpointPlanCapacityExceeded}!void {145        std.debug.assert(self.phase == .steady);146        std.debug.assert(self.in_use);147        if (self.filled >= self.admitted) return error.CheckpointPlanCapacityExceeded;148        self.pageStorage()[self.filled] = checkpoint_page;149        self.filled += 1;150    }151152    pub fn activate(self: *CheckpointPlan) void {153        std.debug.assert(self.phase == .initialization);154        std.debug.assert(self.filled == 0);155        std.debug.assert(!self.in_use);156        self.phase = .steady;157    }158159    pub fn pages(self: *const CheckpointPlan) []const CheckpointPage {160        std.debug.assert(self.phase == .steady);161        std.debug.assert(self.in_use);162        std.debug.assert(self.filled == self.admitted);163        return self.pageStorageConst()[0..self.filled];164    }165166    pub fn release(self: *CheckpointPlan) void {167        std.debug.assert(self.phase == .steady);168        std.debug.assert(self.in_use);169        self.filled = 0;170        self.admitted = 0;171        self.in_use = false;172    }173174    pub fn deinit(self: *CheckpointPlan) CheckpointPlan.Storage {175        std.debug.assert(self.phase != .teardown);176        std.debug.assert(!self.in_use);177        std.debug.assert(self.storage.len == self.capacity.storage_bytes);178        self.phase = .teardown;179        const storage = self.storage;180        self.* = undefined;181        return storage;182    }183184    fn pageStorage(self: *CheckpointPlan) []CheckpointPage {185        return std.mem.bytesAsSlice(CheckpointPage, self.storage);186    }187188    fn pageStorageConst(self: *const CheckpointPlan) []const CheckpointPage {189        return std.mem.bytesAsSlice(CheckpointPage, self.storage);190    }191};

1pub const CheckpointPlan = @import("pager.zig").CheckpointPlan;