alloc_fixed.Tracked

1/// When a caller allocates from its own slice and needs to find out afterwards2/// how much memory the work took, this fixed-capacity buffer allocator records3/// usage figures alongside a sticky record of any raw allocation that ran out4/// of room. It wraps a `FixedBuffer` and records the current bump frontier5/// offset, the peak since the last reset, the high-water mark over its life,6/// and the allocation failure.7///8/// ### Owner stability9/// The instance stays alive at one memory address for as long as any handle10/// from `allocator()` is in use. One instance owns one set of numbers, and the11/// caller takes no copy of it to act as a second allocator over that same12/// state.13pub const Tracked = struct {14    /// The fixed-buffer storage owner whose frontier every other field counts,15    /// maintained by `Tracked`.16    fixed: FixedBuffer,17    /// Furthest the bump frontier has reached in the current interval, which18    /// starts when the instance starts and again at every `reset()`.19    peak_bytes: usize = 0,20    /// Furthest the bump frontier has reached at any point in the life of the21    /// struct, the figure for sizing the buffer. A `reset()` leaves it22    /// standing.23    high_water_bytes: usize = 0,24    /// Set to `true` exactly when `rawAlloc` returns `null` for want of room in25    /// the buffer, separating a buffer too small from work that fits. A failed26    /// `rawResize` or `rawRemap` leaves it alone. Calling `reset()` clears it27    /// to `false`.28    exhausted: bool = false,2930    const Self = @This();3132    /// A point-in-time snapshot of the numbers a `Tracked` allocator records,33    /// used to read every figure at once as it stood when taken.34    pub const Status = struct {35        /// Current bump frontier offset in bytes, counting the payload and the36        /// alignment padding.37        used_bytes: usize,38        /// Furthest the bump frontier reached in the interval that ends here,39        /// which began at the last reset, or at initialization when there was40        /// none.41        peak_bytes: usize,42        /// Furthest the bump frontier reached at any point, with every reset43        /// behind it counted.44        high_water_bytes: usize,45        /// Indicates whether a raw allocation failure happened since46        /// initialization or the last reset. A failed in-place resize or remap47        /// leaves it unchanged.48        exhausted: bool,49    };5051    /// Starts a `Tracked` instance over a byte slice the caller supplies. The52    /// caller keeps ownership of `bytes`. It performs no backing allocation.53    pub fn init(bytes: []u8) Self {54        return .{ .fixed = FixedBuffer.init(bytes) };55    }5657    /// Hands the whole buffer back to the next round of work by resetting the58    /// bump frontier, the peak offset, and the exhausted flag. It rewinds the59    /// frontier to zero, sets `peak_bytes` to 0, and sets `exhausted` to60    /// `false`. It leaves `high_water_bytes` standing across resets. Every61    /// active allocation becomes invalid, and the space is available again.62    pub fn reset(self: *Self) void {63        self.fixed.reset();64        self.peak_bytes = 0;65        self.exhausted = false;66    }6768    /// Returns a borrowed `std.mem.Allocator` handle pointing at `self` to pass69    /// to code that allocates. The `self` instance stays alive at one memory70    /// address while the handle is in use.71    pub fn allocator(self: *Self) Allocator {72        return .{ .ptr = self, .vtable = &vtable };73    }7475    /// Returns a snapshot of the current usage numbers by value so a caller can76    /// inspect them. The caller serializes access, because the read is unsafe77    /// while another thread mutates the allocator.78    pub fn status(self: *const Self) Status {79        return .{80            .used_bytes = used(&self.fixed),81            .peak_bytes = self.peak_bytes,82            .high_water_bytes = self.high_water_bytes,83            .exhausted = self.exhausted,84        };85    }8687    fn observeUsage(self: *Self) void {88        const used_bytes = used(&self.fixed);89        self.peak_bytes = @max(self.peak_bytes, used_bytes);90        self.high_water_bytes = @max(self.high_water_bytes, used_bytes);91    }9293    fn rawAlloc(94        context: *anyopaque,95        len: usize,96        alignment: Alignment,97        return_address: usize,98    ) ?[*]u8 {99        const self: *Self = @ptrCast(@alignCast(context));100        const result = self.fixed.allocator().rawAlloc(101            len,102            alignment,103            return_address,104        ) orelse {105            self.exhausted = true;106            return null;107        };108        self.observeUsage();109        return result;110    }111112    fn rawResize(113        context: *anyopaque,114        memory: []u8,115        alignment: Alignment,116        new_len: usize,117        return_address: usize,118    ) bool {119        const self: *Self = @ptrCast(@alignCast(context));120        const resized = self.fixed.allocator().rawResize(121            memory,122            alignment,123            new_len,124            return_address,125        );126        if (resized) self.observeUsage();127        return resized;128    }129130    fn rawRemap(131        context: *anyopaque,132        memory: []u8,133        alignment: Alignment,134        new_len: usize,135        return_address: usize,136    ) ?[*]u8 {137        const self: *Self = @ptrCast(@alignCast(context));138        const result = self.fixed.allocator().rawRemap(139            memory,140            alignment,141            new_len,142            return_address,143        );144        if (result != null) self.observeUsage();145        return result;146    }147148    fn rawFree(149        context: *anyopaque,150        memory: []u8,151        alignment: Alignment,152        return_address: usize,153    ) void {154        const self: *Self = @ptrCast(@alignCast(context));155        self.fixed.allocator().rawFree(156            memory,157            alignment,158            return_address,159        );160    }161162    const vtable: Allocator.VTable = .{163        .alloc = rawAlloc,164        .resize = rawResize,165        .remap = rawRemap,166        .free = rawFree,167    };168};

1/// `Tracked` provides fixed-capacity bump allocation over a caller-supplied2/// slice while measuring exact memory consumption. Bookkeeping records the3/// current bump frontier offset, the peak offset reached since the last reset,4/// the high-water mark over the owner's whole life, and the exhausted flag that5/// latches any raw allocation that ran out of room.6pub const Tracked = fixed.Tracked;