tiny.content.memory

1/// One binding: a reference and the offset at which its bytes start in the2/// content region. Entries make up the metadata array the caller sizes. The3/// entry size has to equal the metadata entry size a capacity was derived with,4/// and a compile-time check refuses the build otherwise.5pub const Entry = struct {6    reference: content.Reference,7    offset: u64,8};

1pub const InitError = error{2    CapacityHostWidthExceeded,3    ContentStorageTooShort,4    EntryStorageTooShort,5    StagingStorageTooShort,6    StorageOverlap,7};

1/// Provides a content store over three buffers the caller laid out, the2/// metadata array, the content region, and the staging region, kept as borrowed3/// slices so the caller keeps the memory. The owner tracks how many bindings it4/// holds and how many content bytes it has used, and serializes every provider5/// call behind a process-local spin lock.6pub const Owner = struct {7    pub const work_limits: alloc_phase.capacity.WorkLimits = .{8        .transition_steps_max = 1,9        .cleanup_steps_per_call_max = 0,10        .cleanup_calls_at_capacity_max = 0,11    };1213    pub const claim: alloc_phase.capacity.Declaration = .{14        .source = .{15            .id = "content.memory",16            .kind = .startup_static,17            .limit_source = .caller,18            .storage = .{19                .covered = &.{20                    .{21                        .id = "identity_entries",22                        .lifetime = .steady,23                        .detail = "one exact reference and byte offset per admitted object",24                    },25                    .{26                        .id = "committed_content",27                        .lifetime = .steady,28                        .detail = "caller-selected immutable content byte region",29                    },30                    .{31                        .id = "publication_staging",32                        .lifetime = .steady,33                        .detail = "one maximum-size private publication staging region",34                    },35                },36                .excluded = &.{37                    "caller input and read-output slices",38                    "provider-independent Reader and Sink values",39                },40            },41            .capacity = .{42                .inputs = &.{43                    alloc_phase.capacity.bindInput(content.Limits, "objects", "objects"),44                    alloc_phase.capacity.bindInput(content.Limits, "object_bytes", "object_bytes"),45                    alloc_phase.capacity.bindInput(content.Limits, "total_bytes", "total_bytes"),46                },47                .type_selectors = &.{48                    alloc_phase.capacity.bindType(Entry, "entry"),49                },50                .nodes = &.{51                    .{ .input = 0 },52                    .{ .input = 1 },53                    .{ .input = 2 },54                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },55                    .{ .add = .{ .left = 3, .right = 2 } },56                    .{ .add = .{ .left = 4, .right = 1 } },57                },58                .assertions = &.{.{59                    .scope = .closure_total,60                    .measure = .retained,61                    .relation = .exact,62                    .expression = 5,63                }},64            },65            .overload = .{66                .kind = .reject_before_mutation,67                .detail = "capacity, digest, extent, and staging checks precede committed metadata mutation",68            },69            .risks = .{70                .transitive = .{71                    .status = .excluded,72                    .detail = "all lookup, hashing, copy, and teardown work is bounded by checked Capacity fields",73                },74                .foreign = .{75                    .status = .excluded,76                    .detail = "caller-owned memory and a process-local mutex perform no filesystem or foreign-runtime work",77                },78            },79            .obligations = &.{80                .{ .key = "content_memory_capacity", .role = .capacity_model },81                .{ .key = "content_memory_overload", .role = .overload },82                .{ .key = "content_memory_convergence", .role = .custom },83                .{ .key = "content_memory_teardown", .role = .custom },84            },85        },86        .bindings = .{87            .owner = @This(),88            .seal = .{89                .family = alloc_phase.capacity.selector(@This().activate),90                .premise = .{91                    .class = .checked_semantic_fact,92                    .authority = .checker,93                },94            },95            .teardown = .{96                .family = alloc_phase.capacity.selector(@This().deinit),97                .premise = .{98                    .class = .checked_semantic_fact,99                    .authority = .checker,100                },101            },102        },103    };104105    phase: alloc_phase.capacity.Phase,106    capacity: content.Capacity,107    entries: []Entry,108    content: []u8,109    staging: []u8,110    entry_count: usize = 0,111    used: usize = 0,112    mutex: std.atomic.Mutex = .unlocked,113114    const reader_vtable: content.Reader.VTable = .{ .read = readProvider };115    const sink_vtable: content.Sink.VTable = .{ .put = putProvider };116117    /// Binds a derived capacity to the three buffers it calls for, once the118    /// caller has laid them out. The call returns `CapacityHostWidthExceeded`119    /// when one of the capacity's counts is wider than a host `usize`, returns120    /// `EntryStorageTooShort`, `ContentStorageTooShort`, or121    /// `StagingStorageTooShort` when a buffer is smaller than the capacity122    /// calls for, and returns `StorageOverlap` when any two of the three123    /// buffers share bytes, because staging and committed content have to stay124    /// apart. Successful initialization cuts each buffer to the size the125    /// capacity names, keeps that slice, and leaves the owner in the126    /// initialization phase, where capabilities are still refused.127    pub fn init(128        capacity: content.Capacity,129        entries: []Entry,130        content_storage: []u8,131        staging: []u8,132    ) InitError!Owner {133        const object_count = std.math.cast(usize, capacity.limits.objects) orelse134            return error.CapacityHostWidthExceeded;135        const total_bytes = std.math.cast(usize, capacity.limits.total_bytes) orelse136            return error.CapacityHostWidthExceeded;137        const object_bytes = std.math.cast(usize, capacity.limits.object_bytes) orelse138            return error.CapacityHostWidthExceeded;139        if (entries.len < object_count) return error.EntryStorageTooShort;140        if (content_storage.len < total_bytes) return error.ContentStorageTooShort;141        if (staging.len < object_bytes) return error.StagingStorageTooShort;142        const selected_entries = entries[0..object_count];143        const selected_content = content_storage[0..total_bytes];144        const selected_staging = staging[0..object_bytes];145        const entry_bytes = std.mem.sliceAsBytes(selected_entries);146        if (slicesOverlap(entry_bytes, selected_content) or147            slicesOverlap(entry_bytes, selected_staging) or148            slicesOverlap(selected_content, selected_staging))149        {150            return error.StorageOverlap;151        }152        return .{153            .phase = .initialization,154            .capacity = capacity,155            .entries = selected_entries,156            .content = selected_content,157            .staging = selected_staging,158        };159    }160161    /// Opens the store for use once after init by moving the owner from162    /// initialization into the steady phase. Every capability accessor asserts163    /// the steady phase, so no Reader or Sink escapes before this call.164    pub fn activate(self: *Owner) void {165        std.debug.assert(self.phase == .initialization);166        std.debug.assert(self.entry_count == 0);167        std.debug.assert(self.used == 0);168        self.phase = .steady;169    }170171    /// Returns a Reader to hand to code that may reopen bytes and do nothing172    /// else, bound to this owner and carrying the owner's capacity. The173    /// returned value borrows the owner, so the owner outlives it.174    pub fn reader(self: *Owner) content.Reader {175        std.debug.assert(self.phase == .steady);176        return .{177            .context = self,178            .capacity = self.capacity,179            .vtable = &reader_vtable,180        };181    }182183    /// Returns a Sink to hand to code that may add bytes and do nothing else,184    /// bound to this owner and carrying the owner's capacity. The returned185    /// value borrows the owner, so the owner outlives it.186    pub fn sink(self: *Owner) content.Sink {187        std.debug.assert(self.phase == .steady);188        return .{189            .context = self,190            .capacity = self.capacity,191            .vtable = &sink_vtable,192        };193    }194195    /// Returns the owner's Reader and Sink as one Store to hand to code trusted196    /// with both authorities at once. Both halves carry the same capacity, so197    /// the composition always succeeds.198    pub fn store(self: *Owner) content.Store {199        return content.Store.init(self.reader(), self.sink()) catch unreachable;200    }201202    /// Drops every binding and resets the store to empty, for a caller that has203    /// finished with the store and keeps the buffers for something else. This204    /// overwrites the live metadata entries and returns the binding count and205    /// the used byte count to zero. The call leaves all three buffers with206    /// their caller, who decides what happens to the bytes, and moves the owner207    /// into the teardown phase, after which the capability accessors refuse.208    pub fn deinit(self: *Owner) void {209        self.lock();210        defer self.mutex.unlock();211        std.debug.assert(self.phase == .steady);212        for (self.entries[0..self.entry_count]) |*entry| entry.* = undefined;213        self.entry_count = 0;214        self.used = 0;215        self.phase = .teardown;216    }217218    /// Reports how many bindings the store holds, for a test or a diagnostic.219    /// The call takes the same lock the provider calls take, so the answer is a220    /// consistent one.221    pub fn count(self: *Owner) usize {222        self.lock();223        defer self.mutex.unlock();224        std.debug.assert(self.phase == .steady);225        return self.entry_count;226    }227228    fn readProvider(229        context: *anyopaque,230        identifier: content.Identifier,231        output: []u8,232    ) error{ ContentMissing, ReadFailed }!u64 {233        const self: *Owner = @ptrCast(@alignCast(context));234        self.lock();235        defer self.mutex.unlock();236        std.debug.assert(self.phase == .steady);237        const index = self.find(identifier) orelse return error.ContentMissing;238        const entry = self.entries[index];239        const actual = entry.reference.extent.bytes;240        if (actual > output.len) return actual;241        const start = std.math.cast(usize, entry.offset) orelse242            return error.ReadFailed;243        const end = std.math.add(usize, start, actual) catch244            return error.ReadFailed;245        if (end > self.content.len or end > self.used) return error.ReadFailed;246        @memcpy(output[0..actual], self.content[start..end]);247        return actual;248    }249250    fn putProvider(251        context: *anyopaque,252        reference: content.Reference,253        bytes: []const u8,254    ) error{255        ContentMutated,256        PublicationConflict,257        PublicationFailed,258        StoreCapacityExceeded,259    }!content.Publication {260        const self: *Owner = @ptrCast(@alignCast(context));261        self.lock();262        defer self.mutex.unlock();263        std.debug.assert(self.phase == .steady);264        if (!reference.identifier.matches(bytes)) return error.ContentMutated;265        if (self.find(reference.identifier)) |index| {266            const entry = self.entries[index];267            if (entry.reference.extent.bytes != reference.extent.bytes) {268                return error.PublicationConflict;269            }270            const start = std.math.cast(usize, entry.offset) orelse271                return error.PublicationConflict;272            const end = std.math.add(usize, start, bytes.len) catch273                return error.PublicationConflict;274            if (end > self.used or end > self.content.len or275                !std.mem.eql(u8, self.content[start..end], bytes))276            {277                return error.PublicationConflict;278            }279            if (!reference.identifier.matches(bytes)) return error.ContentMutated;280            return .exists_same;281        }282        if (self.entry_count >= self.entries.len) {283            return error.StoreCapacityExceeded;284        }285        const next_used = std.math.add(usize, self.used, bytes.len) catch286            return error.StoreCapacityExceeded;287        if (next_used > self.content.len or bytes.len > self.staging.len) {288            return error.StoreCapacityExceeded;289        }290        @memcpy(self.staging[0..bytes.len], bytes);291        const staged = self.staging[0..bytes.len];292        if (!reference.identifier.matches(staged) or293            !reference.identifier.matches(bytes))294        {295            return error.ContentMutated;296        }297        @memcpy(self.content[self.used..next_used], staged);298        self.entries[self.entry_count] = .{299            .reference = reference,300            .offset = self.used,301        };302        self.entry_count += 1;303        self.used = next_used;304        return .created;305    }306307    fn find(self: *const Owner, identifier: content.Identifier) ?usize {308        var index: usize = 0;309        while (index < self.entry_count) : (index += 1) {310            if (self.entries[index].reference.identifier.eql(identifier)) {311                return index;312            }313        }314        return null;315    }316317    fn lock(self: *Owner) void {318        while (!self.mutex.tryLock()) std.atomic.spinLoopHint();319    }320};

1const store = @import("store.zig");23pub const Entry = store.Entry;4pub const InitError = store.InitError;5pub const Owner = store.Owner;

1pub const memory = @import("memory/root.zig");