alloc_fixed.Chunks

1/// A chunked allocator that builds a result across several allocations and2/// then either commits backing chunks to an outer owner through `retain()` or3/// invokes upstream frees for rollback through `discard()`. It requests4/// chunks from an upstream backing allocator as needed, tracking at most 645/// chunk descriptors simultaneously in an array fixed at compile time.6/// Initializing an instance performs no initial backing allocation, acquiring7/// chunks only as requests demand them.8///9/// ### Growth schedule and capacity bounds10/// Fresh chunks follow a growth schedule that starts at `initial_capacity`,11/// doubles after each successful fresh chunk, and stops growing at12/// `maximum_capacity`. Each fresh chunk has `@max(scheduled_capacity, len)`13/// bytes, so requests larger than `maximum_capacity` are allowed but need14/// both a free descriptor and a successful backing allocation. Because15/// doubling calculations use the scheduled capacity rather than the actual16/// requested length, oversized requests do not advance the growth progression17/// faster. The `maximum_capacity` parameter caps the growth schedule itself18/// rather than limiting individual request sizes or total storage.19///20/// Calling `retain()` clears this descriptor table without freeing backing21/// memory, so committed chunks no longer occupy slots in the table and more22/// than 64 total chunks can be allocated across successive retain cycles. The23/// upstream lifetime owner must reclaim that committed memory. When an24/// allocation fails, the failure stems either from the backing allocator25/// returning `null` or from exhausting the 64 descriptor slots. Both26/// conditions return an allocation failure to the caller.27///28/// ### Transaction discipline29/// - Calling `retain()` commits every chunk it holds to the backing lifetime30///   owner, such as an enclosing `std.heap.ArenaAllocator`.31/// - Calling `retain()` clears the descriptor tracking without freeing the32///   backing memory.33/// - A chunk that was retained can no longer be freed through34///   `Chunks.discard()`.35/// - Calling `discard()` frees every tracked chunk in reverse order back to the36///   upstream allocator and puts the growth schedule back at37///   `initial_capacity`.38///39/// ### Resize behavior40/// In `rawResize`, shrinking returns `true` at once without consulting the41/// active chunk buffer, leaving the bump frontier where it was. Growing in42/// place looks at the active tail chunk alone, `self.current()`. A slice43/// allocated in an earlier chunk cannot grow in place.44pub const Chunks = struct {45    /// Internal chunk storage holding the buffer descriptors and the growth46    /// state that the methods work through. The owner maintains it, so a caller47    /// accesses storage through `retain` and `discard` and takes no copy of it48    /// and makes no direct changes.49    inner: ChunkStorage,5051    const Self = @This();52    /// Number of chunk descriptors tracked at one time, fixed at 64 to cap how53    /// many chunks one instance holds at a time.54    pub const maximum_chunk_count = ChunkStorage.maximum_chunk_count;5556    /// Starts a `Chunks` instance to open an allocation transaction over an57    /// allocator the caller already has. It asserts that `initial_capacity > 0`58    /// and that `maximum_capacity >= initial_capacity`. It allocates nothing59    /// here: chunks are requested from the backing allocator as they are60    /// needed.61    pub fn init(62        backing: Allocator,63        initial_capacity: usize,64        maximum_capacity: usize,65    ) Self {66        return .{ .inner = .init(67            backing,68            initial_capacity,69            maximum_capacity,70        ) };71    }7273    /// Returns a borrowed `std.mem.Allocator` handle pointing at `self` to pass74    /// to code that allocates. The `self` instance stays alive at one memory75    /// address while the handle is in use.76    pub fn allocator(self: *Self) Allocator {77        return .{ .ptr = self, .vtable = &vtable };78    }7980    /// Reports whether a given handle came from a `Chunks` instance, allowing a81    /// caller to allocate straight into an open transaction when handed one. It82    /// compares the candidate's vtable pointer against the `Chunks` vtable.83    pub fn isAllocator(candidate: Allocator) bool {84        return candidate.vtable == &vtable;85    }8687    /// Commits every tracked chunk to the upstream backing owner and clears88    /// tracking metadata when work succeeds. It sets the chunk descriptor count89    /// to zero without freeing any backing memory. It leaves the current growth90    /// schedule, `next_capacity`, as it is. Once retained, the backing memory91    /// can no longer be freed through `Chunks.discard()`, and reclaiming it92    /// belongs to the upstream backing owner.93    pub fn retain(self: *Self) void {94        self.inner.retain();95    }9697    /// Rolls back an uncommitted transaction after failure by freeing all98    /// tracked chunks to the backing allocator in reverse order. This99    /// invalidates any allocations residing in those chunks and resets100    /// `next_capacity` to `initial_capacity`. Chunks committed by an earlier101    /// call to `retain()` are untouched and remain allocated. Actual physical102    /// reuse of the freed memory depends on the free policy of the backing103    /// allocator.104    pub fn discard(self: *Self) void {105        self.inner.discard();106    }107108    fn rawAlloc(109        context: *anyopaque,110        len: usize,111        alignment: Alignment,112        return_address: usize,113    ) ?[*]u8 {114        const self: *Self = @ptrCast(@alignCast(context));115        return self.inner.allocate(.retained, len, alignment, return_address);116    }117118    fn rawResize(119        context: *anyopaque,120        memory: []u8,121        alignment: Alignment,122        new_len: usize,123        return_address: usize,124    ) bool {125        const self: *Self = @ptrCast(@alignCast(context));126        return self.inner.resize(memory, alignment, new_len, return_address);127    }128129    fn rawRemap(130        context: *anyopaque,131        memory: []u8,132        alignment: Alignment,133        new_len: usize,134        return_address: usize,135    ) ?[*]u8 {136        const self: *Self = @ptrCast(@alignCast(context));137        return self.inner.remap(138            .retained,139            memory,140            alignment,141            new_len,142            return_address,143        );144    }145146    fn rawFree(147        context: *anyopaque,148        memory: []u8,149        alignment: Alignment,150        return_address: usize,151    ) void {152        const self: *Self = @ptrCast(@alignCast(context));153        self.inner.free(.retained, memory, alignment, return_address);154    }155156    const vtable: Allocator.VTable = .{157        .alloc = rawAlloc,158        .resize = rawResize,159        .remap = rawRemap,160        .free = rawFree,161    };162};

1/// `Chunks` builds a result across several allocations, committing backing2/// chunks to an outer owner through `retain()` or invoking upstream frees for3/// rollback through `discard()`.4///5/// Fresh chunks requested from the backing allocator follow a growth schedule6/// that starts at `initial_capacity`, doubles after each successful fresh7/// chunk, and stops growing at `maximum_capacity`, with each fresh chunk8/// sized to `@max(scheduled_capacity, len)`. Requests larger than the9/// scheduled size are permitted without altering the doubling calculation,10/// but can fail from exhausted descriptor slots or backing allocation11/// failure.12///13/// The owner tracks at most 64 chunk descriptors simultaneously. Calling14/// `retain()` clears the descriptor table without freeing backing memory,15/// leaving committed storage for the upstream lifetime owner to reclaim.16pub const Chunks = fixed.Chunks;