alloc_fixed.Recycling

1/// `Recycling` reuses memory chunks across repeated workloads to reduce2/// allocation calls to an upstream backing allocator. It tracks the count of3/// outstanding live allocations within each chunk. When deallocations bring4/// the live count of the active tail chunk to zero, that chunk is deactivated5/// and reset for subsequent reuse. Because reusing an inactive chunk requires6/// that its capacity and alignment satisfy the new request, subsequent7/// workloads may still require new backing allocations if existing chunks8/// lack sufficient size or alignment.9///10/// ### Chunk deactivation and reuse constraints11/// - It compacts no holes, so a chunk that sits before the tail and has emptied12///   waits for every chunk behind it to empty too.13/// - Reusing an inactive chunk needs the alignment it was allocated at to meet14///   or exceed the requested alignment, and needs room for the request.15/// - In `rawRemap`, growth that cannot happen in place returns `null`, and a16///   caller going through `std.mem.Allocator.realloc` gets the allocate, copy,17///   and free path, which is how a reallocation crosses chunks.18/// - In `rawResize`, shrinking returns `true` at once and leaves the frontier19///   where it was, and growing in place looks at the active tail chunk alone.20pub const Recycling = struct {21    /// Internal chunk storage holding the buffer descriptors and the live22    /// allocation counts that the methods work through. The owner maintains it,23    /// so a caller accesses storage through `reset` and `discard` and takes no24    /// copy of it and makes no direct changes.25    inner: ChunkStorage,2627    const Self = @This();28    /// Ceiling on how many chunks one instance holds at a time, fixed at 6429    /// chunk descriptors and counting the inactive chunks kept for reuse.30    pub const maximum_chunk_count = ChunkStorage.maximum_chunk_count;3132    /// Starts a `Recycling` instance over an allocator the caller already has.33    /// It asserts that `initial_capacity > 0` and that34    /// `maximum_capacity >= initial_capacity`. It allocates nothing here: the35    /// first request that needs backing memory takes it.36    pub fn init(37        backing: Allocator,38        initial_capacity: usize,39        maximum_capacity: usize,40    ) Self {41        return .{ .inner = .init(42            backing,43            initial_capacity,44            maximum_capacity,45        ) };46    }4748    /// Returns a borrowed `std.mem.Allocator` handle pointing at `self` to pass49    /// to code that allocates. The `self` instance stays alive at one memory50    /// address while the handle is in use.51    pub fn allocator(self: *Self) Allocator {52        return .{ .ptr = self, .vtable = &vtable };53    }5455    /// Resets every tracked chunk and deactivates them for reuse so the next56    /// round of work can start with the chunks it already has. It rewinds the57    /// bump frontier of every tracked chunk and sets its live allocation count58    /// to zero. The backing memory stays where it is, so later allocations59    /// reuse the existing chunks when the size and the alignment fit. It leaves60    /// `next_capacity` as it is and clears the descriptor exhaustion flag.61    /// Every allocation returned before becomes invalid.62    pub fn reset(self: *Self) void {63        self.inner.reset();64    }6566    /// Returns every tracked chunk back to the allocator it came from and67    /// starts the growth schedule over. It frees in reverse order, puts68    /// `next_capacity` back at `initial_capacity`, and clears the descriptor69    /// exhaustion flag.70    pub fn discard(self: *Self) void {71        self.inner.discard();72    }7374    /// Reports whether an allocation failed because all 64 chunk descriptors75    /// were taken, helping a caller separate a full descriptor table from an76    /// exhausted backing allocator because the two need different fixes. It77    /// stays set until `reset()` or `discard()`.78    pub fn metadataExhausted(self: *const Self) bool {79        return self.inner.metadata_exhausted;80    }8182    fn rawAlloc(83        context: *anyopaque,84        len: usize,85        alignment: Alignment,86        return_address: usize,87    ) ?[*]u8 {88        const self: *Self = @ptrCast(@alignCast(context));89        return self.inner.allocate(.recycling, len, alignment, return_address);90    }9192    fn rawResize(93        context: *anyopaque,94        memory: []u8,95        alignment: Alignment,96        new_len: usize,97        return_address: usize,98    ) bool {99        const self: *Self = @ptrCast(@alignCast(context));100        return self.inner.resize(memory, alignment, new_len, return_address);101    }102103    fn rawRemap(104        context: *anyopaque,105        memory: []u8,106        alignment: Alignment,107        new_len: usize,108        return_address: usize,109    ) ?[*]u8 {110        const self: *Self = @ptrCast(@alignCast(context));111        return self.inner.remap(112            .recycling,113            memory,114            alignment,115            new_len,116            return_address,117        );118    }119120    fn rawFree(121        context: *anyopaque,122        memory: []u8,123        alignment: Alignment,124        return_address: usize,125    ) void {126        const self: *Self = @ptrCast(@alignCast(context));127        self.inner.free(.recycling, memory, alignment, return_address);128    }129130    const vtable: Allocator.VTable = .{131        .alloc = rawAlloc,132        .resize = rawResize,133        .remap = rawRemap,134        .free = rawFree,135    };136};

1/// `Recycling` reuses memory chunks across repeated workloads by tracking2/// outstanding allocations across up to 64 chunk descriptors, including3/// inactive chunks kept for reuse. When deallocations bring the live count of4/// the active tail chunk to zero, that chunk is deactivated and reset for5/// subsequent reuse. Because reusing an inactive chunk requires that its6/// capacity and alignment satisfy the new request, subsequent workloads may7/// still require new backing allocations if existing chunks lack sufficient8/// size or alignment.9pub const Recycling = fixed.Recycling;