tiny.sql.FileDatabaseWorkspace

1/// The reusable storage an open database runs on, built once by a caller so2/// that the pager, the caches, and the paths for every database opened through3/// it come from storage laid out in advance. The workspace covers the pager,4/// path storage, read cache, digest memo, and transaction staging area. One set5/// of limits sizes all of them, naming the write-ahead log header, the log byte6/// ceiling, the path limits, read cache pages, and digest memo entries. The7/// workspace takes storage from the caller with `init` or from an allocator8/// with `allocate`, gives it back with the matching `deinit` or `deallocate`,9/// and lends each region to one holder at a time. A second request receives10/// `WorkspaceBusy`.11/// Because the path storage inside records the workspace's address, callers12/// keep the workspace at one address across every database opened from it, and13/// teardown refuses by assertion until every region has been returned.14pub const DatabaseWorkspace = struct {15    pub const Limits = struct {16        header: wal.Header,17        max_wal_bytes: usize,18        path_storage: PathStorage.Limits,19        read_cache_pages: usize = default_read_cache_capacity,20        /// Direct-mapped slots, keyed by identity page, each holding one21        /// stored tree digest. Zero disables reuse.22        digest_memo_entries: usize = default_digest_memo_entries,23    };2425    pub const Storage = struct {26        pager: pager.Pager.Workspace,27        paths: PathStorage.Storage,28        read_cache: ReadCache.Storage,29        digest_memo: DigestMemo.Storage,30        transaction_staging: TransactionStaging.Storage,31    };3233    pub const Capacity = struct {34        wal_frames: usize,35        pager: pager.Pager.Workspace.Capacity,36        paths: PathStorage.Capacity,37        read_cache: ReadCache.Capacity,38        digest_memo: DigestMemo.Capacity,39        transaction_staging: TransactionStaging.Capacity,40        requested_bytes: usize,4142        pub const DeriveError = pager.Pager.Workspace.Capacity.DeriveError ||43            error{ InvalidWalLimit, CapacityOverflow };4445        pub fn derive(limits: Limits) DeriveError!Capacity {46            const wal_frames = try walFrameCapacity(limits.max_wal_bytes);47            const pager_capacity = try pager.Pager.Workspace.Capacity.derive(.{48                .header = limits.header,49                .wal_frames = wal_frames,50            });51            const transaction_staging = try TransactionStaging.Capacity.derive(.{52                .frames = wal_frames,53            });54            const paths = try PathStorage.Capacity.derive(limits.path_storage);55            const read_cache = try ReadCache.Capacity.derive(.{56                .pages = limits.read_cache_pages,57            });58            const digest_memo = try DigestMemo.Capacity.derive(limits.digest_memo_entries);59            var requested_bytes = pager_capacity.journal.storage_bytes;60            requested_bytes = std.math.add(61                usize,62                requested_bytes,63                pager_capacity.checkpoint.storage_bytes,64            ) catch return error.CapacityOverflow;65            requested_bytes = std.math.add(66                usize,67                requested_bytes,68                pager_capacity.checkpoint_once.storage_bytes,69            ) catch return error.CapacityOverflow;70            requested_bytes = std.math.add(71                usize,72                requested_bytes,73                pager_capacity.wal_index.storage_bytes,74            ) catch return error.CapacityOverflow;75            requested_bytes = std.math.add(76                usize,77                requested_bytes,78                paths.storageBytes(),79            ) catch return error.CapacityOverflow;80            requested_bytes = std.math.add(81                usize,82                requested_bytes,83                read_cache.storage_bytes,84            ) catch return error.CapacityOverflow;85            requested_bytes = std.math.add(86                usize,87                requested_bytes,88                digest_memo.storage_bytes,89            ) catch return error.CapacityOverflow;90            requested_bytes = std.math.add(91                usize,92                requested_bytes,93                transaction_staging.storage_bytes,94            ) catch return error.CapacityOverflow;95            return .{96                .wal_frames = wal_frames,97                .pager = pager_capacity,98                .paths = paths,99                .read_cache = read_cache,100                .digest_memo = digest_memo,101                .transaction_staging = transaction_staging,102                .requested_bytes = requested_bytes,103            };104        }105    };106107    pub const InitError = Capacity.DeriveError || PathStorage.IdentityError ||108        error{StorageTooShort};109    pub const AllocateError = Allocator.Error || Capacity.DeriveError ||110        PathStorage.IdentityError;111    pub const AcquireError = Error || error{ WorkspaceBusy, WorkspaceCapacityExceeded };112113    const State = enum {114        free,115        busy,116    };117118    phase: alloc_phase.capacity.Phase,119    limits: Limits,120    capacity: Capacity,121    storage: Storage,122    path_storage: PathStorage,123    state: State = .free,124    loan: pager.Pager.Workspace.Capacity = undefined,125    read_cache_live: bool = false,126    read_cache_loan: ReadCache.Capacity = undefined,127    digest_memo_live: bool = false,128    transaction_staging_live: bool = false,129    transaction_staging_loan: TransactionStaging.Capacity = undefined,130131    pub fn init(storage: Storage, limits: Limits) InitError!DatabaseWorkspace {132        const capacity = try Capacity.derive(limits);133        if (!fits(storage, capacity)) return error.StorageTooShort;134        const path_storage = try PathStorage.init(135            storage.paths[0..capacity.paths.storageBytes()],136            limits.path_storage,137        );138        return .{139            .phase = .initialization,140            .limits = limits,141            .capacity = capacity,142            .storage = storage,143            .path_storage = path_storage,144        };145    }146147    pub fn allocate(allocator: Allocator, limits: Limits) AllocateError!DatabaseWorkspace {148        const capacity = try Capacity.derive(limits);149        var pager_storage = try pager.Pager.Workspace.allocate(allocator, .{150            .header = limits.header,151            .wal_frames = capacity.wal_frames,152        });153        errdefer pager_storage.deallocate(allocator);154        const paths = if (capacity.paths.storageBytes() == 0)155            @as(PathStorage.Storage, &.{})156        else157            try allocator.alloc(u8, capacity.paths.storageBytes());158        errdefer if (paths.len != 0) allocator.free(paths);159        const read_cache = if (capacity.read_cache.storage_bytes == 0)160            @as(ReadCache.Storage, &.{})161        else162            try allocator.alignedAlloc(163                u8,164                .fromByteUnits(ReadCache.storage_alignment),165                capacity.read_cache.storage_bytes,166            );167        errdefer if (read_cache.len != 0) allocator.free(read_cache);168        const digest_memo = if (capacity.digest_memo.entries == 0)169            @as(DigestMemo.Storage, &.{})170        else171            try allocator.alloc(DigestMemo.Entry, capacity.digest_memo.entries);172        errdefer if (digest_memo.len != 0) allocator.free(digest_memo);173        const transaction_staging = if (capacity.transaction_staging.storage_bytes == 0)174            @as(TransactionStaging.Storage, &.{})175        else176            try allocator.alignedAlloc(177                u8,178                .fromByteUnits(TransactionStaging.storage_alignment),179                capacity.transaction_staging.storage_bytes,180            );181        errdefer if (transaction_staging.len != 0) allocator.free(transaction_staging);182        var workspace = init(.{183            .pager = pager_storage,184            .paths = paths,185            .read_cache = read_cache,186            .digest_memo = digest_memo,187            .transaction_staging = transaction_staging,188        }, limits) catch |err| switch (err) {189            error.StorageTooShort => unreachable,190            else => |other| return other,191        };192        workspace.activate();193        return workspace;194    }195196    pub fn activate(self: *DatabaseWorkspace) void {197        std.debug.assert(self.phase == .initialization);198        self.assertValid();199        self.phase = .steady;200    }201202    pub fn acquire(203        self: *DatabaseWorkspace,204        allocator: Allocator,205        options: pager.InitOptions,206    ) AcquireError!pager.Pager {207        self.assertSteady();208        if (self.state == .busy) return error.WorkspaceBusy;209        const loan = try pager.Pager.Workspace.Capacity.derive(options);210        if (options.wal_frames > self.capacity.wal_frames or211            !fitsPager(self.storage.pager, loan))212        {213            return error.WorkspaceCapacityExceeded;214        }215        var storage = pager.Pager.Workspace.init(216            self.storage.pager.journal[0..loan.journal.storage_bytes],217            self.storage.pager.checkpoint[0..loan.checkpoint.storage_bytes],218            self.storage.pager.checkpoint_once[0..loan.checkpoint_once.storage_bytes],219            self.storage.pager.wal_index[0..loan.wal_index.storage_bytes],220        );221        const owned = pager.Pager.init(allocator, &storage, options) catch |err| switch (err) {222            error.StorageTooShort => unreachable,223            else => return err,224        };225        self.state = .busy;226        self.loan = loan;227        return owned;228    }229230    pub fn release(self: *DatabaseWorkspace, owned: *pager.Pager) void {231        self.assertSteady();232        std.debug.assert(self.state == .busy);233        const returned = owned.deinit();234        assertReturned(self.storage.pager.journal, returned.journal, self.loan.journal.storage_bytes);235        assertReturned(self.storage.pager.checkpoint, returned.checkpoint, self.loan.checkpoint.storage_bytes);236        assertReturned(237            self.storage.pager.checkpoint_once,238            returned.checkpoint_once,239            self.loan.checkpoint_once.storage_bytes,240        );241        assertReturned(self.storage.pager.wal_index, returned.wal_index, self.loan.wal_index.storage_bytes);242        self.state = .free;243        self.loan = undefined;244    }245246    pub fn acquirePathStorage(247        self: *DatabaseWorkspace,248        limits: PathStorage.Limits,249    ) AcquireError!PathStorage.Loan {250        self.assertSteady();251        return self.path_storage.acquire(limits) catch |err| switch (err) {252            error.PathStorageBusy => error.WorkspaceBusy,253            error.PathCapacityExceeded => error.WorkspaceCapacityExceeded,254            else => |other| other,255        };256    }257258    pub fn releasePathStorage(259        self: *DatabaseWorkspace,260        owned: *PathStorage.Loan,261    ) PathStorage.Loan.LoanError!void {262        self.assertSteady();263        try self.path_storage.release(owned);264    }265266    pub fn acquireReadCache(267        self: *DatabaseWorkspace,268        limits: ReadCache.Limits,269    ) AcquireError!ReadCache {270        self.assertSteady();271        if (self.read_cache_live) return error.WorkspaceBusy;272        const loan = try ReadCache.Capacity.derive(limits);273        if (loan.storage_bytes > self.storage.read_cache.len) {274            return error.WorkspaceCapacityExceeded;275        }276        const owned = ReadCache.init(277            self.storage.read_cache[0..loan.storage_bytes],278            limits,279        ) catch |err| switch (err) {280            error.StorageTooShort => unreachable,281            else => return err,282        };283        self.read_cache_live = true;284        self.read_cache_loan = loan;285        return owned;286    }287288    pub fn releaseReadCache(289        self: *DatabaseWorkspace,290        owned: *ReadCache,291    ) void {292        self.assertSteady();293        std.debug.assert(self.read_cache_live);294        const returned = owned.deinit();295        assertReturned(296            self.storage.read_cache,297            returned,298            self.read_cache_loan.storage_bytes,299        );300        self.read_cache_live = false;301        self.read_cache_loan = undefined;302    }303304    pub fn acquireDigestMemo(self: *DatabaseWorkspace) AcquireError!DigestMemo {305        self.assertSteady();306        if (self.digest_memo_live) return error.WorkspaceBusy;307        self.digest_memo_live = true;308        return DigestMemo.init(self.storage.digest_memo, self.capacity.digest_memo.entries);309    }310311    pub fn releaseDigestMemo(self: *DatabaseWorkspace, owned: *DigestMemo) void {312        self.assertSteady();313        std.debug.assert(self.digest_memo_live);314        std.debug.assert(owned.slots.ptr == self.storage.digest_memo.ptr);315        std.debug.assert(owned.slots.len == self.capacity.digest_memo.entries);316        owned.* = undefined;317        self.digest_memo_live = false;318    }319320    pub fn acquireTransactionStaging(321        self: *DatabaseWorkspace,322        limits: TransactionStaging.Limits,323    ) AcquireError!TransactionStaging {324        self.assertSteady();325        if (self.transaction_staging_live) return error.WorkspaceBusy;326        const loan = try TransactionStaging.Capacity.derive(limits);327        if (loan.storage_bytes > self.storage.transaction_staging.len) {328            return error.WorkspaceCapacityExceeded;329        }330        const owned = TransactionStaging.init(331            self.storage.transaction_staging[0..loan.storage_bytes],332            limits,333        ) catch |err| switch (err) {334            error.StorageTooShort => unreachable,335            else => return err,336        };337        self.transaction_staging_live = true;338        self.transaction_staging_loan = loan;339        return owned;340    }341342    pub fn releaseTransactionStaging(343        self: *DatabaseWorkspace,344        owned: *TransactionStaging,345    ) void {346        self.assertSteady();347        std.debug.assert(self.transaction_staging_live);348        const returned = owned.deinit();349        assertReturned(350            self.storage.transaction_staging,351            returned,352            self.transaction_staging_loan.storage_bytes,353        );354        self.transaction_staging_live = false;355        self.transaction_staging_loan = undefined;356    }357358    pub fn deinit(self: *DatabaseWorkspace) Storage {359        std.debug.assert(self.phase != .teardown);360        self.assertValid();361        std.debug.assert(self.state == .free);362        std.debug.assert(!self.path_storage.loan_live);363        std.debug.assert(!self.read_cache_live);364        std.debug.assert(!self.digest_memo_live);365        std.debug.assert(!self.transaction_staging_live);366        const returned_paths = self.path_storage.deinit();367        assertReturned(368            self.storage.paths,369            returned_paths,370            self.capacity.paths.storageBytes(),371        );372        self.phase = .teardown;373        const storage = self.storage;374        self.* = undefined;375        return storage;376    }377378    pub fn deallocate(self: *DatabaseWorkspace, allocator: Allocator) void {379        var storage = self.deinit();380        if (storage.transaction_staging.len != 0) {381            allocator.free(storage.transaction_staging);382        }383        if (storage.read_cache.len != 0) allocator.free(storage.read_cache);384        if (storage.digest_memo.len != 0) allocator.free(storage.digest_memo);385        if (storage.paths.len != 0) allocator.free(storage.paths);386        storage.pager.deallocate(allocator);387    }388389    pub fn retainedBytes(self: *const DatabaseWorkspace) usize {390        self.assertValid();391        return self.capacity.requested_bytes;392    }393394    fn assertSteady(self: *const DatabaseWorkspace) void {395        std.debug.assert(self.phase == .steady);396        self.assertValid();397    }398399    fn assertValid(self: *const DatabaseWorkspace) void {400        std.debug.assert(fits(self.storage, self.capacity));401    }402403    fn fits(404        storage: Storage,405        capacity: Capacity,406    ) bool {407        return fitsPager(storage.pager, capacity.pager) and408            storage.paths.len >= capacity.paths.storageBytes() and409            storage.read_cache.len >= capacity.read_cache.storage_bytes and410            storage.digest_memo.len >= capacity.digest_memo.entries and411            storage.transaction_staging.len >= capacity.transaction_staging.storage_bytes;412    }413414    fn fitsPager(415        storage: pager.Pager.Workspace,416        capacity: pager.Pager.Workspace.Capacity,417    ) bool {418        return storage.journal.len >= capacity.journal.storage_bytes and419            storage.checkpoint.len >= capacity.checkpoint.storage_bytes and420            storage.checkpoint_once.len >= capacity.checkpoint_once.storage_bytes and421            storage.wal_index.len >= capacity.wal_index.storage_bytes;422    }423424    fn assertReturned(full: []u8, returned: []u8, loan_bytes: usize) void {425        std.debug.assert(returned.ptr == full.ptr);426        std.debug.assert(returned.len == loan_bytes);427        std.debug.assert(returned.len <= full.len);428    }429};

1pub const FileDatabaseWorkspace = file.DatabaseWorkspace;