alloc_fixed.Monotonic

1/// A stream allocator with a bypass for oversized allocations, used inside an2/// arena that frees everything at once and keeps a large allocation from3/// throwing away the chunk in use. It refills fixed-capacity chunks of4/// `chunk_capacity` bytes from an upstream allocator for ordinary allocations.5/// A request longer than `chunk_capacity` goes straight to the backing6/// allocator, and the active tail chunk stays where it is.7///8/// ### Reclamation and lifetime9/// It keeps metadata for the chunk in `current` alone. It has no `reset`,10/// `deinit`, or `discard` method. The backing allocator, typically an enclosing11/// `std.heap.ArenaAllocator`, reclaims the chunk memory when the owner around12/// it is torn down.13///14/// ### Resize behavior15/// Shrinking returns `true` at once, leaving the frontier where it was. Growing16/// in place looks at `current` alone. Growth returns `false` for memory that17/// sits in an earlier chunk or came from the oversized bypass.18pub const Monotonic = struct {19    /// Upstream allocator that provides the memory for chunks and for oversized20    /// allocations.21    backing: Allocator,22    /// Fixed byte capacity of an ordinary chunk, which sets the length above23    /// which a request bypasses the chunk.24    chunk_capacity: usize,25    /// The fixed buffer chunk in use that ordinary allocations are cut from,26    /// which is `null` before the first allocation.27    current: ?FixedBuffer = null,2829    const Self = @This();3031    /// Starts a `Monotonic` instance with a fixed chunk size to open a stream32    /// allocator over an arena the caller already has. It asserts that33    /// `chunk_capacity > 0`. It allocates nothing here.34    pub fn init(backing: Allocator, chunk_capacity: usize) Self {35        std.debug.assert(chunk_capacity > 0);36        return .{37            .backing = backing,38            .chunk_capacity = chunk_capacity,39        };40    }4142    /// Returns a borrowed `std.mem.Allocator` handle pointing at `self` to pass43    /// to code that allocates. The `self` instance stays alive at one memory44    /// address while the handle is in use.45    pub fn allocator(self: *Self) Allocator {46        return .{ .ptr = self, .vtable = &vtable };47    }4849    /// Confirms whether a given handle is this instance's backing allocator so50    /// a caller knows the allocator hands memory to the arena expected to free51    /// it. It checks the type-erased state pointer and the vtable pointer,52    /// both.53    pub fn isBackedBy(self: *const Self, candidate: Allocator) bool {54        return self.backing.ptr == candidate.ptr and55            self.backing.vtable == candidate.vtable;56    }5758    fn rawAlloc(59        context: *anyopaque,60        len: usize,61        alignment: Alignment,62        return_address: usize,63    ) ?[*]u8 {64        const self: *Self = @ptrCast(@alignCast(context));65        if (self.current) |*current| {66            if (fits(current, len, alignment)) {67                return current.allocator().rawAlloc(68                    len,69                    alignment,70                    return_address,71                ) orelse unreachable;72            }73        }74        if (len > self.chunk_capacity) {75            return self.backing.rawAlloc(76                len,77                alignment,78                @returnAddress(),79            );80        }81        const chunk_alignment = Alignment.max(alignment, .@"16");82        const pointer = self.backing.rawAlloc(83            self.chunk_capacity,84            chunk_alignment,85            @returnAddress(),86        ) orelse return null;87        self.current = FixedBuffer.init(pointer[0..self.chunk_capacity]);88        return self.current.?.allocator().rawAlloc(89            len,90            alignment,91            return_address,92        ) orelse unreachable;93    }9495    fn rawResize(96        context: *anyopaque,97        memory: []u8,98        alignment: Alignment,99        new_len: usize,100        return_address: usize,101    ) bool {102        if (new_len <= memory.len) return true;103        const self: *Self = @ptrCast(@alignCast(context));104        if (self.current) |*current| {105            if (current.ownsSlice(memory)) {106                return current.allocator().rawResize(107                    memory,108                    alignment,109                    new_len,110                    return_address,111                );112            }113        }114        return false;115    }116117    fn rawRemap(118        context: *anyopaque,119        memory: []u8,120        alignment: Alignment,121        new_len: usize,122        return_address: usize,123    ) ?[*]u8 {124        if (new_len <= memory.len) return memory.ptr;125        const self: *Self = @ptrCast(@alignCast(context));126        if (self.current) |*current| {127            if (current.ownsSlice(memory)) {128                if (current.allocator().rawRemap(129                    memory,130                    alignment,131                    new_len,132                    return_address,133                )) |result| return result;134            }135        }136        const result = rawAlloc(137            self,138            new_len,139            alignment,140            return_address,141        ) orelse return null;142        @memcpy(result[0..memory.len], memory);143        return result;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        if (self.current) |*current| {154            if (current.ownsSlice(memory)) {155                current.allocator().rawFree(156                    memory,157                    alignment,158                    return_address,159                );160            }161        }162    }163164    const vtable: Allocator.VTable = .{165        .alloc = rawAlloc,166        .resize = rawResize,167        .remap = rawRemap,168        .free = rawFree,169    };170};

1/// To stream allocations inside an arena that will free everything at once,2/// `Monotonic` refills fixed-capacity chunks from a backing allocator. An3/// oversized allocation bypasses the chunk chain straight to backing storage,4/// leaving the active tail chunk in place. Built for growth inside an enclosing5/// arena lifetime, the owner has no `reset` and no `discard`, so the arena6/// behind it reclaims the memory.7pub const Monotonic = fixed.Monotonic;