tiny.sql.FileTransaction

1pub const Transaction = struct {2    database: *Database,3    start_position: pager.Pager.Position,4    start_generation: u64,5    staging: *TransactionStaging,6    closed: bool = false,78    /// Ends the transaction without committing it, usually called through a9    /// defer so that an abandoned transaction gives the database's single write10    /// slot back and another transaction can open. The call drops the staged11    /// pages, so nothing the transaction put reaches the log, and does nothing12    /// on a transaction that has already committed or ended.13    pub fn deinit(self: *Transaction) void {14        self.close();15    }1617    pub fn putPage(self: *Transaction, page_id: u32, image: *const [page.size]u8) Error!void {18        if (self.closed) return error.TransactionClosed;19        if (page_id == 0) return error.InvalidPageId;20        try self.ensureCurrent();21        const phase = trace.scope("file.transaction.put_page");22        defer phase.end();23        switch (self.findSlot(page_id)) {24            .existing => |index| try self.database.pager.stageWalPage(self.start_position, index, page_id, image),25            .empty => |index| {26                const page_index = self.staging.nextPage() catch return self.capacityError();27                try self.database.pager.stageWalPage(self.start_position, page_index, page_id, image);28                self.staging.occupy(index, page_index);29            },30            .full => return self.capacityError(),31        }32    }3334    pub fn getPage(self: *const Transaction, page_id: u32) Error!?[]const u8 {35        if (self.closed) return error.TransactionClosed;36        if (page_id == 0) return error.InvalidPageId;37        try self.ensureCurrent();38        return switch (self.findSlot(page_id)) {39            .existing => |index| self.database.pager.stagedWalPage(self.start_position, index),40            .empty => null,41            .full => null,42        };43    }4445    /// Returns the image this transaction staged for `page_id`, or null when46    /// it staged none. Edits through the image are staged as they happen,47    /// so putting the same image again copies nothing. The image stays48    /// valid until the transaction commits or ends.49    pub fn editPage(self: *Transaction, page_id: u32) Error!?*[page.size]u8 {50        if (self.closed) return error.TransactionClosed;51        if (page_id == 0) return error.InvalidPageId;52        try self.ensureCurrent();53        return switch (self.findSlot(page_id)) {54            .existing => |index| self.database.pager.stagedWalPageMut(self.start_position, index),55            .empty => null,56            .full => null,57        };58    }5960    /// Appends every staged page to the write-ahead log as one committed batch61    /// to make those pages part of the database, sorting the staged pages by62    /// page number before appending them. Callers choose whether to wait for63    /// the bytes to reach the disk through durability options: with `synced`64    /// durability the call syncs the log before returning and reports the65    /// commit as synced, and with `buffered` it returns as soon as the bytes66    /// are written and reports the commit as not yet synced. A transaction with67    /// nothing staged commits as a no-op, reporting zero frames and zero pages.68    /// The call reports `TransactionConflict` when the database moved69    /// underneath the transaction, and `TransactionClosed` when the transaction70    /// has already ended. The transaction ends whichever way the call goes, so71    /// the write slot is free even after a failure.72    pub fn commit(self: *Transaction, options: CommitOptions) Error!Commit {73        if (self.closed) return error.TransactionClosed;74        defer self.close();75        const phase = trace.scope("file.transaction.commit");76        defer phase.end();77        try self.ensureCurrent();78        if (self.staging.pages == 0) {79            return .{80                .view = try self.database.pager.currentView(),81                .frames = 0,82                .pages = 0,83                .synced = false,84            };85        }8687        self.sortPages();88        var page_count = self.database.pager.databasePageCount();89        for (0..self.staging.pages) |index| page_count = @max(page_count, self.pageId(index));90        try self.database.advanceWriteSerial();91        try self.database.appendStagedTransactionWal(self.start_position, self.staging.pages, page_count);9293        const view = try self.database.pager.currentView();94        const frames = self.staging.pages;95        const synced = switch (options.durability) {96            .buffered => false,97            .synced => synced: {98                try self.database.syncWal();99                break :synced true;100            },101        };102        trace.progress("file.transaction.commit.complete");103        return .{104            .view = view,105            .frames = frames,106            .pages = frames,107            .synced = synced,108        };109    }110111    fn close(self: *Transaction) void {112        if (self.closed) return;113        std.debug.assert(self.database.write_transaction_open);114        self.staging.end();115        self.database.write_transaction_open = false;116        self.closed = true;117    }118119    fn ensureCurrent(self: *const Transaction) Error!void {120        try self.database.ensureUsable();121        if (!std.meta.eql(self.database.pager.position(), self.start_position) or self.database.pager.baseGeneration() != self.start_generation) {122            return error.TransactionConflict;123        }124    }125126    fn findSlot(self: *const Transaction, page_id: u32) TransactionSlot {127        const slots = self.staging.capacity.index_slots;128        if (slots == 0) return .full;129        var index = std.hash.Wyhash.hash(0x7469_6e79_7371_6c31, std.mem.asBytes(&page_id)) % slots;130        for (0..slots) |_| {131            const page_index = self.staging.pageIndex(index) orelse return .{ .empty = index };132            if (self.database.pager.stagedWalPageId(self.start_position, page_index) == page_id) return .{ .existing = page_index };133            index = if (index + 1 == slots) 0 else index + 1;134        }135        return .full;136    }137138    fn capacityError(self: *const Transaction) DatabaseFileError {139        return if (self.staging.limit_frames < self.staging.capacity.frames) error.WalLimitExceeded else error.TransactionTooLarge;140    }141142    fn sortPages(self: *Transaction) void {143        if (self.staging.pages < 2) return;144        self.quickSortPages(0, self.staging.pages);145    }146147    fn quickSortPages(self: *Transaction, start: usize, end: usize) void {148        if (end - start < 16) return self.insertionSortPages(start, end);149        const pivot = self.pageId(start + (end - start) / 2);150        var left = start;151        var right = end - 1;152        while (left <= right) {153            while (self.pageId(left) < pivot) left += 1;154            while (self.pageId(right) > pivot) {155                if (right == start) break;156                right -= 1;157            }158            if (left <= right) {159                self.database.pager.swapStagedWalFrames(self.start_position, left, right);160                left += 1;161                if (right == start) break;162                right -= 1;163            }164        }165        if (right > start) self.quickSortPages(start, right + 1);166        if (left < end) self.quickSortPages(left, end);167    }168169    fn insertionSortPages(self: *Transaction, start: usize, end: usize) void {170        var index = start + 1;171        while (index < end) : (index += 1) {172            var scan = index;173            while (scan > start and self.pageId(scan) < self.pageId(scan - 1)) : (scan -= 1) {174                self.database.pager.swapStagedWalFrames(self.start_position, scan, scan - 1);175            }176        }177    }178179    fn pageId(self: *const Transaction, index: usize) u32 {180        return self.database.pager.stagedWalPageId(self.start_position, index);181    }182};

1pub const FileTransaction = file.Transaction;