tiny.zen.HeadingStorage

1/// One reusable aligned region for an inspected Markdown document.2///3/// Call `init`, then `activate`. A document borrows the region until `reset`.4/// Call `deinit` with the allocator passed to `init` after the last reset.5pub const Storage = struct {6    phase: alloc_phase.capacity.Phase,7    capacity: capacity_mod.Capacity,8    bytes: []align(capacity_mod.storage_alignment) u8,9    headings: []model.Heading,10    text: []u8,11    ids: []u8,12    in_use: bool = false,13    heading_count: usize = 0,14    text_bytes: usize = 0,15    id_bytes: usize = 0,16    high_water_headings: usize = 0,17    high_water_text_bytes: usize = 0,18    high_water_id_bytes: usize = 0,19    rejected_source_count: u64 = 0,2021    pub const Limits: type = capacity_mod.Limits;22    pub const Capacity: type = capacity_mod.Capacity;23    pub const Exhaustion: type = model.Exhaustion;24    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;25    pub const AcquireError: type = model.Exhaustion;2627    pub const claim: alloc_phase.capacity.Declaration = .{28        .source = .{29            .id = "zen.heading_storage",30            .kind = .phase_static,31            .limit_source = .caller,32            .storage = .{33                .covered = &.{34                    .{35                        .id = "markdown_heading_descriptors",36                        .lifetime = .steady,37                        .detail = "Markdown heading descriptors",38                    },39                    .{40                        .id = "source_independent_heading_text",41                        .lifetime = .steady,42                        .detail = "source-independent heading text",43                    },44                    .{45                        .id = "stable_heading_identifiers",46                        .lifetime = .steady,47                        .detail = "stable heading identifiers",48                    },49                },50                .excluded = &.{51                    "caller-owned Markdown source",52                    "rendered HTML and inline-rendering owners",53                    "site catalog, theme, and filesystem output owners",54                },55            },56            .capacity = .{57                .inputs = &.{58                    alloc_phase.capacity.bindInput(Limits, "max_headings", "max_headings"),59                    alloc_phase.capacity.bindInput(Limits, "max_text_bytes", "max_text_bytes"),60                    alloc_phase.capacity.bindInput(Limits, "max_id_bytes", "max_id_bytes"),61                },62                .type_selectors = &.{63                    alloc_phase.capacity.bindType(model.Heading, "heading"),64                },65                .nodes = &.{66                    .{ .input = 0 },67                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },68                    .{ .input = 1 },69                    .{ .input = 2 },70                    .{ .add = .{ .left = 1, .right = 2 } },71                    .{ .add = .{ .left = 4, .right = 3 } },72                },73                .assertions = &.{.{74                    .scope = .closure_total,75                    .measure = .retained,76                    .relation = .exact,77                    .expression = 5,78                }},79            },80            .overload = .{81                .kind = .reject_before_mutation,82                .detail = "max plus one and in-use acquisition reject before the backing region or active result changes; only rejection telemetry advances",83            },84            .risks = .{85                .transitive = .{86                    .status = .witnessed,87                    .detail = "heading scanning, planning, copying, and identifier resolution use borrowed input and acquired slices only",88                },89                .foreign = .{90                    .status = .excluded,91                    .detail = "heading inspection crosses no operating-system or foreign callback boundary",92                },93            },94            .obligations = &.{95                .{ .key = "zen_heading_capacity", .role = .capacity_model },96                .{ .key = "zen_heading_acquisition", .role = .custom },97                .{ .key = "zen_heading_oom", .role = .custom },98                .{ .key = "zen_heading_boundaries", .role = .overload },99                .{ .key = "zen_heading_reuse", .role = .overload },100                .{ .key = "zen_heading_sealed", .role = .transitive_risk },101                .{ .key = "zen_heading_root", .role = .custom },102                .{ .key = "zen_heading_consumer", .role = .foreign_risk },103            },104        },105        .bindings = .{106            .owner = @This(),107            .seal = .{108                .family = alloc_phase.capacity.selector(@This().activate),109                .premise = .{110                    .class = .checked_semantic_fact,111                    .authority = .checker,112                },113            },114            .teardown = .{115                .family = alloc_phase.capacity.selector(@This().deinit),116                .premise = .{117                    .class = .checked_semantic_fact,118                    .authority = .checker,119                },120            },121        },122    };123124    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {125        const capacity = try Capacity.derive(limits);126        const bytes = if (capacity.storage_bytes == 0)127            @as([]align(capacity_mod.storage_alignment) u8, &.{})128        else129            try allocator.alignedAlloc(130                u8,131                .fromByteUnits(capacity_mod.storage_alignment),132                capacity.storage_bytes,133            );134        return .{135            .phase = .initialization,136            .capacity = capacity,137            .bytes = bytes,138            .headings = typedSlice(139                model.Heading,140                bytes,141                capacity.headings_offset,142                limits.max_headings,143            ),144            .text = bytes[capacity.text_offset..][0..limits.max_text_bytes],145            .ids = bytes[capacity.id_offset..][0..limits.max_id_bytes],146        };147    }148149    pub fn activate(self: *Storage) void {150        std.debug.assert(self.phase == .initialization);151        self.assertStorage();152        self.phase = .steady;153    }154155    /// Acquires exact plan regions or rejects before backing bytes change.156    pub fn acquire(self: *Storage, plan: plan_mod.Plan) AcquireError!Regions {157        std.debug.assert(self.phase == .steady);158        if (self.in_use) return self.reject(error.DocumentStorageInUse);159        plan.require(self.capacity.limits) catch |err| return self.reject(err);160        self.in_use = true;161        self.heading_count = plan.headings;162        self.text_bytes = plan.text_bytes;163        self.id_bytes = plan.id_bytes;164        self.high_water_headings = @max(self.high_water_headings, plan.headings);165        self.high_water_text_bytes = @max(self.high_water_text_bytes, plan.text_bytes);166        self.high_water_id_bytes = @max(self.high_water_id_bytes, plan.id_bytes);167        self.assertStorage();168        return .{169            .plan = plan,170            .headings = self.headings[0..plan.headings],171            .text = self.text[0..plan.text_bytes],172            .ids = self.ids[0..plan.id_bytes],173        };174    }175176    /// Ends the active borrow so the same region can inspect another document.177    pub fn reset(self: *Storage) void {178        std.debug.assert(self.phase == .steady);179        std.debug.assert(self.in_use);180        self.in_use = false;181        self.heading_count = 0;182        self.text_bytes = 0;183        self.id_bytes = 0;184        self.assertStorage();185    }186187    /// Returns current, high-water, and rejected demand without mutation.188    pub fn status(self: *const Storage) Status {189        return .{190            .phase = self.phase,191            .in_use = self.in_use,192            .storage_bytes = self.capacity.storage_bytes,193            .max_headings = self.capacity.limits.max_headings,194            .max_text_bytes = self.capacity.limits.max_text_bytes,195            .max_id_bytes = self.capacity.limits.max_id_bytes,196            .heading_count = self.heading_count,197            .text_bytes = self.text_bytes,198            .id_bytes = self.id_bytes,199            .high_water_headings = self.high_water_headings,200            .high_water_text_bytes = self.high_water_text_bytes,201            .high_water_id_bytes = self.high_water_id_bytes,202            .rejected_source_count = self.rejected_source_count,203        };204    }205206    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {207        std.debug.assert(self.phase != .teardown);208        std.debug.assert(!self.in_use);209        self.assertStorage();210        self.phase = .teardown;211        allocator.free(self.bytes);212        self.bytes = &.{};213        self.headings = &.{};214        self.text = &.{};215        self.ids = &.{};216    }217218    fn reject(self: *Storage, err: model.Exhaustion) model.Exhaustion {219        self.rejected_source_count +|= 1;220        return err;221    }222223    fn assertStorage(self: *const Storage) void {224        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);225        std.debug.assert(self.headings.len == self.capacity.limits.max_headings);226        std.debug.assert(self.text.len == self.capacity.limits.max_text_bytes);227        std.debug.assert(self.ids.len == self.capacity.limits.max_id_bytes);228        std.debug.assert(self.heading_count <= self.headings.len);229        std.debug.assert(self.text_bytes <= self.text.len);230        std.debug.assert(self.id_bytes <= self.ids.len);231        std.debug.assert(self.high_water_headings <= self.headings.len);232        std.debug.assert(self.high_water_text_bytes <= self.text.len);233        std.debug.assert(self.high_water_id_bytes <= self.ids.len);234        if (!self.in_use) {235            std.debug.assert(self.heading_count == 0);236            std.debug.assert(self.text_bytes == 0);237            std.debug.assert(self.id_bytes == 0);238        }239    }240};

1/// Reusable caller-allocated storage for one inspected Markdown document.2pub const HeadingStorage = document.Storage;