tiny.ui.Store

1/// `Store` retains one accepted tree. `init` makes its only allocation, sized by2/// `Capacity.derive`, which holds two envelope blocks, one identity map per block, and the3/// splice scratch. The retained tree occupies one block. An accepted publish with a new revision4/// is written into the other block, which then becomes the retained one.5pub const Store = struct {6    pub const Limits = LimitsType;7    pub const Capacity = CapacityType;89    /// `Store.claim` is the static capacity claim `ui.publish_store`. It declares that the store's10    /// retained bytes are exactly two blocks, two identity maps, and the scratch arrays, all11    /// derived from `Limits`, and it names six witness tests.12    pub const claim: alloc_phase.capacity.Declaration = .{13        .source = .{14            .id = "ui.publish_store",15            .kind = .phase_static,16            .limit_source = .caller,17            .storage = .{18                .covered = &.{19                    .{20                        .id = "double_buffered_retained_envelope_blocks",21                        .lifetime = .steady,22                        .detail = "the store's two envelope blocks, each Capacity.buffer_bytes " ++23                            "long and aligned to storage_alignment, with one block holding the " ++24                            "retained tree and the splice writing the next tree into the other",25                    },26                    .{27                        .id = "open_addressed_node_identity_maps",28                        .lifetime = .steady,29                        .detail = "one identity map slot array of Limits.map_slots words for " ++30                            "each envelope block",31                    },32                    .{33                        .id = "splice_scratch_arrays",34                        .lifetime = .steady,35                        .detail = "the dirty node list and the placement map of Limits.nodes " ++36                            "words each, and the atom and text remap arrays of Limits.atoms " ++37                            "and Limits.texts words",38                    },39                },40                .excluded = &.{41                    "the publish buffer, which the caller owns and passes to Store.publish, " ++42                        "where the survey reads it in place and the store keeps only the " ++43                        "bytes the splice copies into its own block",44                    "storage for computed style, layout, and facts derived from the retained " ++45                        "tree, which belongs to the packages that compute them, with Store " ++46                        "having no field for any of it",47                },48            },49            .capacity = .{50                .inputs = &.{51                    alloc_phase.capacity.bindInput(LimitsType, "nodes", "nodes"),52                    alloc_phase.capacity.bindInput(LimitsType, "declarations", "declarations"),53                    alloc_phase.capacity.bindInput(LimitsType, "classes", "classes"),54                    alloc_phase.capacity.bindInput(LimitsType, "texts", "texts"),55                    alloc_phase.capacity.bindInput(LimitsType, "runs", "runs"),56                    alloc_phase.capacity.bindInput(LimitsType, "relations", "relations"),57                    alloc_phase.capacity.bindInput(LimitsType, "atoms", "atoms"),58                    alloc_phase.capacity.bindInput(LimitsType, "string_bytes", "string_bytes"),59                    alloc_phase.capacity.bindInput(LimitsType, "solved_roots", "solved_roots"),60                    alloc_phase.capacity.bindInput(LimitsType, "solved_rects", "solved_rects"),61                    alloc_phase.capacity.bindInput(LimitsType, "map_slots", "map_slots"),62                },63                .type_selectors = &.{64                    alloc_phase.capacity.bindType(abi.Node, "node"),65                    alloc_phase.capacity.bindType(abi.Declaration, "declaration"),66                    alloc_phase.capacity.bindType(u32, "u32"),67                    alloc_phase.capacity.bindType(abi.TextRecord, "text_record"),68                    alloc_phase.capacity.bindType(abi.TextRun, "text_run"),69                    alloc_phase.capacity.bindType(abi.Relation, "relation"),70                    alloc_phase.capacity.bindType(abi.Atom, "atom"),71                    alloc_phase.capacity.bindType(u8, "u8"),72                    alloc_phase.capacity.bindType(abi.SolvedRoot, "solved_root"),73                    alloc_phase.capacity.bindType(abi.Rect, "rect"),74                },75                .nodes = &.{76                    .{ .input = 0 },77                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },78                    .{ .input = 1 },79                    .{ .scale = .{ .node = 2, .coefficient = .{ .size_of_concrete_type = 1 } } },80                    .{ .input = 2 },81                    .{ .scale = .{ .node = 4, .coefficient = .{ .size_of_concrete_type = 2 } } },82                    .{ .input = 3 },83                    .{ .scale = .{ .node = 6, .coefficient = .{ .size_of_concrete_type = 3 } } },84                    .{ .input = 4 },85                    .{ .scale = .{ .node = 8, .coefficient = .{ .size_of_concrete_type = 4 } } },86                    .{ .input = 5 },87                    .{ .scale = .{ .node = 10, .coefficient = .{ .size_of_concrete_type = 5 } } },88                    .{ .input = 6 },89                    .{ .scale = .{ .node = 12, .coefficient = .{ .size_of_concrete_type = 6 } } },90                    .{ .input = 7 },91                    .{ .scale = .{ .node = 14, .coefficient = .{ .size_of_concrete_type = 7 } } },92                    .{ .input = 8 },93                    .{ .scale = .{ .node = 16, .coefficient = .{ .size_of_concrete_type = 8 } } },94                    .{ .input = 9 },95                    .{ .scale = .{ .node = 18, .coefficient = .{ .size_of_concrete_type = 9 } } },96                    .{ .input = 10 },97                    .{ .scale = .{ .node = 20, .coefficient = .{ .size_of_concrete_type = 2 } } },98                    .{ .constant = 152 },99                    .{ .alignment = .{ .node = 22, .alignment = .{ .concrete_type = 0 } } },100                    .{ .add = .{ .left = 23, .right = 1 } },101                    .{ .alignment = .{ .node = 24, .alignment = .{ .concrete_type = 1 } } },102                    .{ .add = .{ .left = 25, .right = 3 } },103                    .{ .alignment = .{ .node = 26, .alignment = .{ .concrete_type = 2 } } },104                    .{ .add = .{ .left = 27, .right = 5 } },105                    .{ .alignment = .{ .node = 28, .alignment = .{ .concrete_type = 3 } } },106                    .{ .add = .{ .left = 29, .right = 7 } },107                    .{ .alignment = .{ .node = 30, .alignment = .{ .concrete_type = 4 } } },108                    .{ .add = .{ .left = 31, .right = 9 } },109                    .{ .alignment = .{ .node = 32, .alignment = .{ .concrete_type = 5 } } },110                    .{ .add = .{ .left = 33, .right = 11 } },111                    .{ .alignment = .{ .node = 34, .alignment = .{ .concrete_type = 6 } } },112                    .{ .add = .{ .left = 35, .right = 13 } },113                    .{ .alignment = .{ .node = 36, .alignment = .{ .concrete_type = 7 } } },114                    .{ .add = .{ .left = 37, .right = 15 } },115                    .{ .alignment = .{ .node = 38, .alignment = .{ .concrete_type = 8 } } },116                    .{ .add = .{ .left = 39, .right = 17 } },117                    .{ .alignment = .{ .node = 40, .alignment = .{ .concrete_type = 9 } } },118                    .{ .add = .{ .left = 41, .right = 19 } },119                    .{ .alignment = .{ .node = 42, .alignment = .{ .literal = 8 } } },120                    .{ .add = .{ .left = 43, .right = 43 } },121                    .{ .add = .{ .left = 21, .right = 21 } },122                    .{ .add = .{ .left = 44, .right = 45 } },123                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 2 } } },124                    .{ .add = .{ .left = 46, .right = 47 } },125                    .{ .add = .{ .left = 48, .right = 47 } },126                    .{ .scale = .{ .node = 12, .coefficient = .{ .size_of_concrete_type = 2 } } },127                    .{ .add = .{ .left = 49, .right = 50 } },128                    .{ .scale = .{ .node = 6, .coefficient = .{ .size_of_concrete_type = 2 } } },129                    .{ .add = .{ .left = 51, .right = 52 } },130                },131                .assertions = &.{.{132                    .scope = .closure_total,133                    .measure = .retained,134                    .relation = .exact,135                    .expression = 53,136                }},137            },138            .overload = .{139                .kind = .reject_before_seal,140                .detail = "Store.publish runs the admission survey over the caller's buffer " ++141                    "before the splice, and the survey rejects every quota, encoding, and " ++142                    "retained reference fault, so a rejected publish writes no retained byte",143            },144            .risks = .{145                .transitive = .{146                    .status = .open,147                    .detail = "the survey and the splice take no allocator, and six witness " ++148                        "tests cover the store, but no machine-checked certificate of their " ++149                        "call graphs proves them allocation free",150                },151                .foreign = .{152                    .status = .excluded,153                    .detail = "admission and splicing transform one caller buffer inside the " ++154                        "process and make no operating-system call",155                },156            },157            .obligations = &.{158                .{ .key = "ui_publish_capacity", .role = .capacity_model },159                .{ .key = "ui_publish_acquisition", .role = .acquisition },160                .{ .key = "ui_publish_survey", .role = .overload },161                .{ .key = "ui_publish_oom", .role = .initialization_failure },162                .{ .key = "ui_publish_retained", .role = .integration },163                .{ .key = "ui_publish_teardown", .role = .teardown },164            },165        },166        .bindings = .{167            .owner = @This(),168            .seal = .{169                .family = alloc_phase.capacity.selector(@This().activate),170                .premise = .{171                    .class = .checked_semantic_fact,172                    .authority = .checker,173                },174            },175            .teardown = .{176                .family = alloc_phase.capacity.selector(@This().deinit),177                .premise = .{178                    .class = .checked_semantic_fact,179                    .authority = .checker,180                },181            },182        },183    };184185    phase: alloc_phase.capacity.Phase,186    limits: LimitsType,187    capacity: CapacityType,188    bytes: []align(storage_alignment) u8,189    blocks: [2][]align(storage_alignment) u8,190    maps: [2]Map,191    scratch: splice_mod.Scratch,192    live: u1 = 0,193    live_bytes: u32 = 0,194    present: bool = false,195    dirty_count: u32 = 0,196    assets: ?*const asset.Registry = null,197    asset_epoch: u64 = 0,198199    /// `init` derives the capacity from `limits`, makes the one allocation, and lays out the200    /// blocks, maps, and scratch inside it. It returns `error.CapacityOverflow` or the201    /// allocator's error.202    pub fn init(allocator: Allocator, limits: LimitsType) !Store {203        const capacity = try CapacityType.derive(limits);204        const bytes = try allocator.alignedAlloc(205            u8,206            .fromByteUnits(storage_alignment),207            capacity.total_bytes,208        );209        var store = Store{210            .phase = .initialization,211            .limits = limits,212            .capacity = capacity,213            .bytes = bytes,214            .blocks = undefined,215            .maps = undefined,216            .scratch = undefined,217        };218        store.place();219        return store;220    }221222    /// `activate` empties both identity maps and moves the store into its steady phase. `admits`,223    /// `publish`, and `forget` assert that phase.224    pub fn activate(self: *Store) void {225        std.debug.assert(self.phase == .initialization);226        self.assertStorage();227        self.maps[0].reset();228        self.maps[1].reset();229        self.phase = .steady;230    }231232    pub fn setAssets(self: *Store, assets: *const asset.Registry) void {233        std.debug.assert(self.phase == .initialization);234        std.debug.assert(assets.phase == .steady);235        self.assets = assets;236        self.asset_epoch = assets.epoch;237    }238239    /// `admits` returns true when every field of `limits` is at most the limit this store was240    /// sized with.241    pub fn admits(self: *const Store, limits: LimitsType) bool {242        std.debug.assert(self.phase == .steady);243        return limits.fits(self.limits);244    }245246    /// `publish` accepts one envelope buffer or returns the first rejection. It reads the header247    /// first. `Store.publish` returns after the header when the revision equals the retained248    /// revision and the registry epoch equals the epoch at the last accepted publish. The249    /// registry epoch changes whenever a font or image registers or releases, so when the epoch250    /// differs, admission checks asset handles again even if the tree revision is the same.251    /// Otherwise `admit` checks the whole buffer and the252    /// splice writes it into the other block. A rejected publish leaves `retained`, `dirty`, and253    /// `identity` as they were.254    pub fn publish(self: *Store, buffer: []align(storage_alignment) const u8) Error!Accepted {255        std.debug.assert(self.phase == .steady);256        const head = try view_mod.readHeader(buffer);257        const current_asset_epoch = if (self.assets) |assets| assets.epoch else 0;258        if (self.present and head.revision == self.retained().header.revision and current_asset_epoch == self.asset_epoch) {259            self.dirty_count = 0;260            return .{ .dirty = 0, .unchanged = true };261        }262        const next: u1 = self.live ^ 1;263        const report = try survey_mod.survey(buffer, self.limits, self.state(), &self.maps[next]);264        const outcome = splice_mod.splice(265            self.blocks[next],266            &self.maps[next],267            self.capacity,268            report,269            self.state(),270            self.scratch,271        );272        self.live = next;273        self.live_bytes = outcome.bytes;274        self.present = true;275        self.dirty_count = outcome.dirty;276        self.asset_epoch = current_asset_epoch;277        return .{ .dirty = outcome.dirty, .unchanged = outcome.dirty == 0 };278    }279280    /// `forget` drops the retained tree and empties both identity maps, so the next publish is281    /// surveyed with no retained tree. A node carrying the `retained` flag is rejected with282    /// `error.StaleRetainedSubtree`, and an accepted publish marks every one of its nodes dirty.283    pub fn forget(self: *Store) void {284        std.debug.assert(self.phase == .steady);285        self.maps[0].reset();286        self.maps[1].reset();287        self.present = false;288        self.live_bytes = 0;289        self.dirty_count = 0;290        self.asset_epoch = if (self.assets) |assets| assets.epoch else 0;291    }292293    /// `retained` returns a `View` of the retained tree, or an empty `View` when no tree is294    /// retained. The view points into the store's block. After an accepted publish with a new295    /// revision, a view taken earlier no longer shows the retained tree.296    pub fn retained(self: *const Store) View {297        if (!self.present) return .{};298        var view = view_mod.bind(self.blocks[self.live][0..self.live_bytes]) catch unreachable;299        view.identity = &self.maps[self.live];300        view.prior = self.scratch.dirty[0..view.nodes.len];301        return view;302    }303304    /// `dirty` returns, in ascending order, the indices in `retained().nodes` of the nodes the305    /// last accepted publish marked dirty. It is empty after a publish at the retained revision306    /// and after `forget`.307    pub fn dirty(self: *const Store) []const u32 {308        return self.scratch.place[0..self.dirty_count];309    }310311    /// `identity` returns the identity map of the retained tree. Pass `retained().nodes` to its312    /// `lookup`.313    pub fn identity(self: *const Store) *const Map {314        return &self.maps[self.live];315    }316317    /// `deinit` frees the allocation and moves the store into its teardown phase. After it,318    /// `retained` returns an empty `View`.319    pub fn deinit(self: *Store, allocator: Allocator) void {320        std.debug.assert(self.phase != .teardown);321        self.assertStorage();322        self.phase = .teardown;323        allocator.free(self.bytes);324        self.bytes = &.{};325        self.blocks = .{ &.{}, &.{} };326        self.maps = .{ .{}, .{} };327        self.scratch = .{ .place = &.{}, .atom_remap = &.{}, .text_remap = &.{}, .dirty = &.{} };328        self.present = false;329        self.assets = null;330        self.asset_epoch = 0;331    }332333    fn state(self: *const Store) survey_mod.Retained {334        if (!self.present) return .{ .assets = self.assets };335        const view = self.retained();336        return .{337            .view = view,338            .map = self.maps[self.live],339            .revision = view.header.revision,340            .present = true,341            .assets = self.assets,342        };343    }344345    fn place(self: *Store) void {346        const block = self.capacity.buffer_bytes;347        var cursor: usize = 0;348        for (&self.blocks) |*slot| {349            slot.* = @alignCast(self.bytes[cursor..][0..block]);350            cursor += block;351        }352        for (&self.maps) |*slot| {353            slot.* = .{ .slots = words(self.bytes, &cursor, self.limits.map_slots) };354        }355        self.scratch = .{356            .dirty = words(self.bytes, &cursor, self.limits.nodes),357            .place = words(self.bytes, &cursor, self.limits.nodes),358            .atom_remap = words(self.bytes, &cursor, self.limits.atoms),359            .text_remap = words(self.bytes, &cursor, self.limits.texts),360        };361        std.debug.assert(cursor == self.capacity.total_bytes);362    }363364    fn assertStorage(self: *const Store) void {365        const expected = CapacityType.derive(self.limits) catch unreachable;366        std.debug.assert(std.meta.eql(expected, self.capacity));367        std.debug.assert(self.bytes.len == self.capacity.total_bytes);368        std.debug.assert(self.blocks[0].len == self.capacity.buffer_bytes);369        std.debug.assert(self.blocks[1].len == self.capacity.buffer_bytes);370        std.debug.assert(self.maps[0].slots.len == self.limits.map_slots);371        std.debug.assert(self.scratch.dirty.len == self.limits.nodes);372    }373};

1pub const Store = tree.Store;