tiny.sql.FileTransactionStaging

1pub const TransactionStaging = struct {2    pub const storage_alignment: usize = @alignOf(TransactionIndexEntry);3    pub const Storage = []align(storage_alignment) u8;45    pub const Limits = struct {6        frames: usize,7    };89    pub const Capacity = struct {10        frames: usize,11        index_slots: usize,12        storage_bytes: usize,1314        pub fn derive(limits: Limits) error{CapacityOverflow}!Capacity {15            if (limits.frames > std.math.maxInt(u32)) return error.CapacityOverflow;16            const index_slots = std.math.mul(usize, limits.frames, 2) catch return error.CapacityOverflow;17            const storage_bytes = std.math.mul(usize, index_slots, @sizeOf(TransactionIndexEntry)) catch return error.CapacityOverflow;18            return .{19                .frames = limits.frames,20                .index_slots = index_slots,21                .storage_bytes = storage_bytes,22            };23        }24    };2526    pub const Exhaustion = error{TransactionTooLarge};27    pub const InitError = error{ CapacityOverflow, StorageTooShort };28    pub const work_limits: alloc_phase.capacity.WorkLimits = .{29        .transition_steps_max = std.math.maxInt(usize),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.file_transaction_staging",37            .kind = .phase_static,38            .limit_source = .caller,39            .storage = .{40                .covered = &.{41                    .{42                        .id = "exact_dense_page_lookup_index_for_the_borrowed_wal_bd67af59f1b2",43                        .lifetime = .steady,44                        .detail = "exact dense-page lookup index for the borrowed WAL tail frame bound",45                    },46                },47                .excluded = &.{48                    "staged and committed page bytes owned by the phase static WAL writer",49                    "database pager frame and page indexes base images read cache and tree roots",50                    "file handles persistence effects transaction metadata and trace instrumentation",51                },52            },53            .capacity = .{54                .inputs = &.{55                    alloc_phase.capacity.bindInput(Limits, "frames", "frames"),56                },57                .type_selectors = &.{58                    alloc_phase.capacity.bindType(TransactionIndexEntry, "transaction_index_entry"),59                },60                .nodes = &.{61                    .{ .input = 0 },62                    .{ .scale = .{ .node = 0, .coefficient = .{ .literal = 2 } } },63                    .{ .scale = .{ .node = 1, .coefficient = .{ .size_of_concrete_type = 0 } } },64                },65                .assertions = &.{.{66                    .scope = .closure_total,67                    .measure = .retained,68                    .relation = .exact,69                    .expression = 2,70                }},71            },72            .overload = .{73                .kind = .reject_before_mutation,74                .detail = "a full remaining WAL frame prefix rejects a new page before the reusable lookup index or borrowed WAL tail mutate",75            },76            .risks = .{77                .transitive = .{78                    .status = .witnessed,79                    .detail = "the transaction stages sorts and transfers page images within WAL owned storage without a second page allocation",80                },81                .foreign = .{82                    .status = .excluded,83                    .detail = "WAL file persistence consumes the committed borrowed bytes after the in memory ownership transfer",84                },85            },86            .work = .{87                .equation = "begin visits at most twice the admitted frame bound only when the generation wraps; other steady operations take constant steps",88            },89            .dependencies = &.{"sql.wal_writer"},90            .obligations = &.{91                .{ .key = "sql_file_transaction_staging_capacity", .role = .capacity_model },92                .{ .key = "sql_file_transaction_staging_sealed", .role = .overload },93                .{ .key = "sql_file_transaction_staging_work_bound", .role = .work_bound },94                .{ .key = "sql_file_transaction_staging_transfer_transitive_risk", .role = .transitive_risk },95                .{ .key = "sql_file_transaction_staging_transfer_foreign_risk", .role = .foreign_risk },96            },97        },98        .bindings = .{99            .owner = @This(),100            .seal = .{101                .family = alloc_phase.capacity.selector(@This().activate),102                .premise = .{103                    .class = .checked_semantic_fact,104                    .authority = .checker,105                },106            },107            .teardown = .{108                .family = alloc_phase.capacity.selector(@This().deinit),109                .premise = .{110                    .class = .checked_semantic_fact,111                    .authority = .checker,112                },113            },114        },115    };116117    phase: alloc_phase.capacity.Phase,118    capacity: Capacity,119    storage: Storage,120    index: []TransactionIndexEntry,121    generation: u32 = 0,122    limit_frames: usize = 0,123    pages: usize = 0,124    active: bool = false,125126    pub fn init(storage: Storage, limits: Limits) InitError!TransactionStaging {127        const capacity = try Capacity.derive(limits);128        if (storage.len < capacity.storage_bytes) return error.StorageTooShort;129        const borrowed = storage[0..capacity.storage_bytes];130        const index = std.mem.bytesAsSlice(TransactionIndexEntry, borrowed);131        @memset(index, .{});132        return .{133            .phase = .initialization,134            .capacity = capacity,135            .storage = borrowed,136            .index = index,137        };138    }139140    pub fn activate(self: *TransactionStaging) void {141        std.debug.assert(self.phase == .initialization);142        std.debug.assert(self.index.len == self.capacity.index_slots);143        self.phase = .steady;144    }145146    pub fn deinit(self: *TransactionStaging) Storage {147        std.debug.assert(self.phase != .teardown);148        std.debug.assert(!self.active);149        std.debug.assert(self.storage.len == self.capacity.storage_bytes);150        std.debug.assert(self.index.len == self.capacity.index_slots);151        std.debug.assert(self.index.ptr == std.mem.bytesAsSlice(152            TransactionIndexEntry,153            self.storage,154        ).ptr);155        self.phase = .teardown;156        const storage = self.storage;157        self.* = undefined;158        return storage;159    }160161    pub fn begin(self: *TransactionStaging, frames: usize) void {162        std.debug.assert(self.phase == .steady);163        std.debug.assert(!self.active);164        std.debug.assert(frames <= self.capacity.frames);165        self.generation +%= 1;166        if (self.generation == 0) {167            @memset(self.index, .{});168            self.generation = 1;169        }170        self.limit_frames = frames;171        self.pages = 0;172        self.active = true;173    }174175    pub fn end(self: *TransactionStaging) void {176        std.debug.assert(self.phase == .steady);177        std.debug.assert(self.active);178        self.limit_frames = 0;179        self.pages = 0;180        self.active = false;181    }182183    pub fn pageIndex(self: *const TransactionStaging, index: usize) ?usize {184        std.debug.assert(self.phase == .steady);185        std.debug.assert(self.active);186        std.debug.assert(index < self.capacity.index_slots);187        const entry = self.index[index];188        return if (entry.generation == self.generation) entry.page_index else null;189    }190191    pub fn nextPage(self: *const TransactionStaging) Exhaustion!usize {192        std.debug.assert(self.phase == .steady);193        std.debug.assert(self.active);194        if (self.pages >= self.limit_frames) return error.TransactionTooLarge;195        return self.pages;196    }197198    pub fn occupy(self: *TransactionStaging, index: usize, page_index: usize) void {199        std.debug.assert(self.phase == .steady);200        std.debug.assert(self.active);201        std.debug.assert(index < self.capacity.index_slots);202        std.debug.assert(self.index[index].generation != self.generation);203        std.debug.assert(page_index == self.pages);204        std.debug.assert(page_index < self.limit_frames);205        self.index[index] = .{206            .generation = self.generation,207            .page_index = @intCast(page_index),208        };209        self.pages += 1;210    }211};

1pub const FileTransactionStaging = file.TransactionStaging;