tiny.ui.AssetRegistry

1pub const Registry = struct {2    phase: alloc_phase.capacity.Phase,3    limits: Limits,4    capacity: Capacity,5    storage: []align(8) u8,6    fonts: []FontDescriptor,7    font_bytes: []Bytes,8    font_generation: []u32,9    font_used: u32,10    images: []ImageDescriptor,11    image_bytes: []Bytes,12    image_generation: []u32,13    image_used: u32,14    strings: []u8,15    owned_bytes: []u8,16    font_occupied: []u64,17    image_occupied: []u64,18    epoch: u64,1920    pub const Limits: type = capacity_mod.Limits;21    pub const Capacity: type = capacity_mod.Capacity;22    pub const Exhaustion: type = model.Error;23    pub const InitError: type = Allocator.Error || capacity_mod.Error;24    pub const claim: alloc_phase.capacity.Declaration = .{25        .source = .{26            .id = "ui.asset_table",27            .kind = .phase_static,28            .limit_source = .caller,29            .storage = .{30                .covered = &.{.{31                    .id = "asset_table_and_owned_payload_pool",32                    .lifetime = .steady,33                    .detail = "font and image descriptors, byte views, generation and occupancy arrays, family strings, and the copied payload pool in one allocation",34                }},35                .excluded = &.{36                    "borrowed font and image bytes kept alive by the caller",37                    "embedded fallback face bytes held in startup static storage",38                },39            },40            .capacity = .{41                .inputs = &.{42                    alloc_phase.capacity.bindInput(Limits, "fonts", "fonts"),43                    alloc_phase.capacity.bindInput(Limits, "images", "images"),44                    alloc_phase.capacity.bindInput(Limits, "owned_bytes", "owned_bytes"),45                },46                .type_selectors = &.{47                    alloc_phase.capacity.bindType(FontDescriptor, "font_descriptor"),48                    alloc_phase.capacity.bindType(ImageDescriptor, "image_descriptor"),49                    alloc_phase.capacity.bindType(Bytes, "bytes"),50                    alloc_phase.capacity.bindType(u32, "generation"),51                    alloc_phase.capacity.bindType(u64, "occupancy_word"),52                },53                .nodes = &.{54                    .{ .input = 0 },55                    .{ .input = 1 },56                    .{ .input = 2 },57                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },58                    .{ .alignment = .{ .node = 3, .alignment = .{ .concrete_type = 2 } } },59                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 2 } } },60                    .{ .add = .{ .left = 4, .right = 5 } },61                    .{ .alignment = .{ .node = 6, .alignment = .{ .concrete_type = 3 } } },62                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 3 } } },63                    .{ .add = .{ .left = 7, .right = 8 } },64                    .{ .alignment = .{ .node = 9, .alignment = .{ .concrete_type = 4 } } },65                    .{ .constant = 64 },66                    .{ .ceiling_division = .{ .left = 0, .right = 11 } },67                    .{ .scale = .{ .node = 12, .coefficient = .{ .size_of_concrete_type = 4 } } },68                    .{ .add = .{ .left = 10, .right = 13 } },69                    .{ .alignment = .{ .node = 14, .alignment = .{ .concrete_type = 1 } } },70                    .{ .scale = .{ .node = 1, .coefficient = .{ .size_of_concrete_type = 1 } } },71                    .{ .add = .{ .left = 15, .right = 16 } },72                    .{ .alignment = .{ .node = 17, .alignment = .{ .concrete_type = 2 } } },73                    .{ .scale = .{ .node = 1, .coefficient = .{ .size_of_concrete_type = 2 } } },74                    .{ .add = .{ .left = 18, .right = 19 } },75                    .{ .alignment = .{ .node = 20, .alignment = .{ .concrete_type = 3 } } },76                    .{ .scale = .{ .node = 1, .coefficient = .{ .size_of_concrete_type = 3 } } },77                    .{ .add = .{ .left = 21, .right = 22 } },78                    .{ .alignment = .{ .node = 23, .alignment = .{ .concrete_type = 4 } } },79                    .{ .ceiling_division = .{ .left = 1, .right = 11 } },80                    .{ .scale = .{ .node = 25, .coefficient = .{ .size_of_concrete_type = 4 } } },81                    .{ .add = .{ .left = 24, .right = 26 } },82                    .{ .scale = .{ .node = 0, .coefficient = .{ .literal = capacity_mod.family_bytes_per_font } } },83                    .{ .add = .{ .left = 27, .right = 28 } },84                    .{ .add = .{ .left = 29, .right = 2 } },85                },86                .assertions = &.{.{87                    .scope = .closure_total,88                    .measure = .retained,89                    .relation = .exact,90                    .expression = 30,91                }},92            },93            .overload = .{94                .kind = .reject_before_mutation,95                .detail = "slot, family length, and owned payload quota checks run before changing table fields",96            },97            .risks = .{98                .transitive = .{99                    .status = .open,100                    .detail = "owned bytes use one allocation at initialization; the bounded registration scan takes no allocator",101                },102                .foreign = .{103                    .status = .excluded,104                    .detail = "registration and lookup operate on caller and table bytes without an operating-system call",105                },106            },107            .obligations = &.{108                .{ .key = "ui_asset_capacity", .role = .capacity_model },109                .{ .key = "ui_asset_acquisition", .role = .acquisition },110                .{ .key = "ui_asset_generation", .role = .integration },111                .{ .key = "ui_asset_oom", .role = .overload },112                .{ .key = "ui_asset_teardown", .role = .teardown },113            },114        },115        .bindings = .{116            .owner = @This(),117            .seal = .{118                .family = alloc_phase.capacity.selector(@This().activate),119                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },120            },121            .teardown = .{122                .family = alloc_phase.capacity.selector(@This().deinit),123                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },124            },125        },126    };127128    pub fn init(allocator: Allocator, limits: Limits) InitError!Registry {129        const capacity = try Capacity.derive(limits);130        const storage = try allocator.alignedAlloc(u8, .fromByteUnits(8), capacity.total_bytes);131        var self = Registry{132            .phase = .initialization,133            .limits = limits,134            .capacity = capacity,135            .storage = storage,136            .fonts = &.{},137            .font_bytes = &.{},138            .font_generation = &.{},139            .font_used = 0,140            .images = &.{},141            .image_bytes = &.{},142            .image_generation = &.{},143            .image_used = 0,144            .strings = &.{},145            .owned_bytes = &.{},146            .font_occupied = &.{},147            .image_occupied = &.{},148            .epoch = 0,149        };150        self.place();151        @memset(self.storage, 0);152        for (self.font_bytes) |*entry| entry.* = .{ .borrowed = &.{} };153        for (self.image_bytes) |*entry| entry.* = .{ .borrowed = &.{} };154        @memset(self.font_generation, 1);155        @memset(self.image_generation, 1);156        return self;157    }158159    pub fn activate(self: *Registry) void {160        std.debug.assert(self.phase == .initialization);161        std.debug.assert(self.storage.len == self.capacity.total_bytes);162        self.phase = .steady;163    }164165    pub fn deinit(self: *Registry, allocator: Allocator) void {166        std.debug.assert(self.phase != .teardown);167        allocator.free(self.storage);168        self.phase = .teardown;169        self.storage = &.{};170        self.fonts = &.{};171        self.font_bytes = &.{};172        self.font_generation = &.{};173        self.images = &.{};174        self.image_bytes = &.{};175        self.image_generation = &.{};176        self.strings = &.{};177        self.owned_bytes = &.{};178        self.font_occupied = &.{};179        self.image_occupied = &.{};180        self.font_used = 0;181        self.image_used = 0;182        self.epoch = 0;183    }184185    pub fn registerFont(self: *Registry, family: []const u8, input: FontDescriptor, bytes: Bytes) model.Error!AssetHandle {186        std.debug.assert(self.phase == .steady);187        if (family.len > capacity_mod.family_bytes_per_font) return error.FamilyTooLong;188        const index = firstFree(self.font_occupied, self.limits.fonts) orelse return error.FontCapacityExceeded;189        const source = bytes.slice();190        const offset = switch (bytes) {191            .borrowed => null,192            .owned => self.findOwned(source.len) orelse return error.OwnedBytesExceeded,193        };194        const family_offset = @as(usize, index) * capacity_mod.family_bytes_per_font;195        var descriptor = input;196        descriptor.family_offset = @intCast(family_offset);197        descriptor.family_len = @intCast(family.len);198        @memcpy(self.strings[family_offset..][0..family.len], family);199        self.fonts[index] = descriptor;200        self.font_bytes[index] = self.storeBytes(bytes, offset);201        setOccupied(self.font_occupied, index, true);202        self.font_used += 1;203        self.epoch +%= 1;204        return .{ .index = index, .generation = self.font_generation[index] };205    }206207    pub fn registerImage(self: *Registry, descriptor: ImageDescriptor, bytes: Bytes) model.Error!AssetHandle {208        std.debug.assert(self.phase == .steady);209        const index = firstFree(self.image_occupied, self.limits.images) orelse return error.ImageCapacityExceeded;210        const source = bytes.slice();211        const offset = switch (bytes) {212            .borrowed => null,213            .owned => self.findOwned(source.len) orelse return error.OwnedBytesExceeded,214        };215        self.images[index] = descriptor;216        self.image_bytes[index] = self.storeBytes(bytes, offset);217        setOccupied(self.image_occupied, index, true);218        self.image_used += 1;219        self.epoch +%= 1;220        return .{ .index = index, .generation = self.image_generation[index] };221    }222223    pub fn release(self: *Registry, kind: model.Kind, handle: AssetHandle) model.Error!void {224        std.debug.assert(self.phase == .steady);225        switch (kind) {226            .font => {227                if (!self.hasFont(handle)) return error.StaleAsset;228                if (handle.generation == std.math.maxInt(u32)) return error.GenerationExhausted;229                clearOwned(self.font_bytes[handle.index]);230                const start = @as(usize, handle.index) * capacity_mod.family_bytes_per_font;231                @memset(self.strings[start..][0..capacity_mod.family_bytes_per_font], 0);232                self.fonts[handle.index] = .{};233                self.font_bytes[handle.index] = .{ .borrowed = &.{} };234                self.font_generation[handle.index] += 1;235                setOccupied(self.font_occupied, handle.index, false);236                self.font_used -= 1;237                self.epoch +%= 1;238            },239            .image => {240                if (!self.hasImage(handle)) return error.StaleAsset;241                if (handle.generation == std.math.maxInt(u32)) return error.GenerationExhausted;242                clearOwned(self.image_bytes[handle.index]);243                self.images[handle.index] = .{};244                self.image_bytes[handle.index] = .{ .borrowed = &.{} };245                self.image_generation[handle.index] += 1;246                setOccupied(self.image_occupied, handle.index, false);247                self.image_used -= 1;248                self.epoch +%= 1;249            },250        }251    }252253    pub fn hasFont(self: *const Registry, handle: AssetHandle) bool {254        return handle.index < self.limits.fonts and occupied(self.font_occupied, handle.index) and self.font_generation[handle.index] == handle.generation;255    }256257    pub fn hasImage(self: *const Registry, handle: AssetHandle) bool {258        return handle.index < self.limits.images and occupied(self.image_occupied, handle.index) and self.image_generation[handle.index] == handle.generation;259    }260261    pub fn font(self: *const Registry, handle: AssetHandle) model.Error!model.Font {262        if (!self.hasFont(handle)) return error.StaleAsset;263        const descriptor = self.fonts[handle.index];264        return .{265            .descriptor = descriptor,266            .family = self.strings[descriptor.family_offset..][0..descriptor.family_len],267            .bytes = self.font_bytes[handle.index].slice(),268        };269    }270271    pub fn image(self: *const Registry, handle: AssetHandle) model.Error!model.Image {272        if (!self.hasImage(handle)) return error.StaleAsset;273        return .{ .descriptor = self.images[handle.index], .bytes = self.image_bytes[handle.index].slice() };274    }275276    fn storeBytes(self: *Registry, bytes: Bytes, offset: ?usize) Bytes {277        return switch (bytes) {278            .borrowed => bytes,279            .owned => |source| blk: {280                const start = offset.?;281                @memcpy(self.owned_bytes[start..][0..source.len], source);282                break :blk .{ .owned = self.owned_bytes[start..][0..source.len] };283            },284        };285    }286287    fn findOwned(self: *const Registry, len: usize) ?usize {288        if (len > self.owned_bytes.len) return null;289        var candidate: usize = 0;290        while (candidate <= self.owned_bytes.len - len) {291            var conflict_end: usize = candidate;292            for (self.font_bytes, 0..) |entry, index| {293                if (!occupied(self.font_occupied, @intCast(index))) continue;294                overlapEnd(self.owned_bytes, entry, candidate, len, &conflict_end);295            }296            for (self.image_bytes, 0..) |entry, index| {297                if (!occupied(self.image_occupied, @intCast(index))) continue;298                overlapEnd(self.owned_bytes, entry, candidate, len, &conflict_end);299            }300            if (conflict_end == candidate) return candidate;301            candidate = conflict_end;302        }303        return null;304    }305306    fn place(self: *Registry) void {307        var cursor: usize = 0;308        self.fonts = take(self.storage, &cursor, FontDescriptor, self.limits.fonts);309        self.font_bytes = take(self.storage, &cursor, Bytes, self.limits.fonts);310        self.font_generation = take(self.storage, &cursor, u32, self.limits.fonts);311        self.font_occupied = take(self.storage, &cursor, u64, std.math.divCeil(usize, self.limits.fonts, 64) catch unreachable);312        self.images = take(self.storage, &cursor, ImageDescriptor, self.limits.images);313        self.image_bytes = take(self.storage, &cursor, Bytes, self.limits.images);314        self.image_generation = take(self.storage, &cursor, u32, self.limits.images);315        self.image_occupied = take(self.storage, &cursor, u64, std.math.divCeil(usize, self.limits.images, 64) catch unreachable);316        self.strings = take(self.storage, &cursor, u8, self.capacity.string_bytes);317        self.owned_bytes = take(self.storage, &cursor, u8, self.limits.owned_bytes);318        std.debug.assert(cursor == self.capacity.total_bytes);319    }320};

1pub const AssetRegistry = asset.Registry;