alloc_fixed.Fallback

1/// A two-tier allocator that serves small work from bytes the caller already2/// has and lets larger work reach the allocator behind it without the caller3/// choosing between them. It serves a request from `fixed` while the room and4/// the alignment fit, and hands the request to `backing` otherwise.5///6/// ### Bounds and provenance routing7/// - The `backing` allocator is any allocator the caller chooses, and8///   `Fallback` adds no memory bound of its own, so a bounded backing allocator9///   bounds the pair.10/// - The `free` operation asks `fixed.ownsSlice(memory)`, and calls11///   `fixed.allocator().rawFree()` for memory the fixed buffer owns and12///   `backing.rawFree()` for the rest.13/// - The `resize` operation tries to grow or shrink in place in the tier that14///   owns the memory.15/// - The `remap` operation on memory that started in `fixed` and cannot be16///   resized in place allocates elsewhere, which may spill to `backing`, copies17///   the bytes over, and frees the old memory from `fixed`, while memory that18///   started in `backing` has its remap handed straight to `backing`.19pub const Fallback = struct {20    /// Primary fixed-buffer storage owner that serves allocation requests21    /// first.22    fixed: FixedBuffer,23    /// Secondary backing allocator that takes requests once the primary fixed24    /// storage cannot fit them.25    backing: Allocator,2627    const Self = @This();2829    /// Starts a `Fallback` instance over a fixed storage buffer the caller30    /// supplies and a backing allocator.31    pub fn init(storage_bytes: []u8, backing: Allocator) Self {32        return .{33            .fixed = FixedBuffer.init(storage_bytes),34            .backing = backing,35        };36    }3738    /// Returns a borrowed `std.mem.Allocator` handle pointing at `self` to pass39    /// to code that allocates. The `self` instance stays alive at one memory40    /// address while the handle is in use.41    pub fn allocator(self: *Self) Allocator {42        return .{ .ptr = self, .vtable = &vtable };43    }4445    fn rawAlloc(46        context: *anyopaque,47        len: usize,48        alignment: Alignment,49        return_address: usize,50    ) ?[*]u8 {51        const self: *Self = @ptrCast(@alignCast(context));52        if (fits(&self.fixed, len, alignment)) {53            return self.fixed.allocator().rawAlloc(54                len,55                alignment,56                return_address,57            ) orelse unreachable;58        }59        return self.backing.rawAlloc(60            len,61            alignment,62            return_address,63        );64    }6566    fn rawResize(67        context: *anyopaque,68        memory: []u8,69        alignment: Alignment,70        new_len: usize,71        return_address: usize,72    ) bool {73        const self: *Self = @ptrCast(@alignCast(context));74        if (self.fixed.ownsSlice(memory)) {75            return self.fixed.allocator().rawResize(76                memory,77                alignment,78                new_len,79                return_address,80            );81        }82        return self.backing.rawResize(83            memory,84            alignment,85            new_len,86            return_address,87        );88    }8990    fn rawRemap(91        context: *anyopaque,92        memory: []u8,93        alignment: Alignment,94        new_len: usize,95        return_address: usize,96    ) ?[*]u8 {97        const self: *Self = @ptrCast(@alignCast(context));98        if (!self.fixed.ownsSlice(memory)) {99            return self.backing.rawRemap(100                memory,101                alignment,102                new_len,103                return_address,104            );105        }106        if (self.fixed.allocator().rawRemap(107            memory,108            alignment,109            new_len,110            return_address,111        )) |result| return result;112        const result = rawAlloc(113            self,114            new_len,115            alignment,116            return_address,117        ) orelse return null;118        @memcpy(result[0..@min(memory.len, new_len)], memory[0..@min(memory.len, new_len)]);119        self.fixed.allocator().rawFree(120            memory,121            alignment,122            return_address,123        );124        return result;125    }126127    fn rawFree(128        context: *anyopaque,129        memory: []u8,130        alignment: Alignment,131        return_address: usize,132    ) void {133        const self: *Self = @ptrCast(@alignCast(context));134        if (self.fixed.ownsSlice(memory)) {135            self.fixed.allocator().rawFree(136                memory,137                alignment,138                return_address,139            );140            return;141        }142        self.backing.rawFree(143            memory,144            alignment,145            return_address,146        );147    }148149    const vtable: Allocator.VTable = .{150        .alloc = rawAlloc,151        .resize = rawResize,152        .remap = rawRemap,153        .free = rawFree,154    };155};

1/// When small work can run on the stack while larger requests spill to the2/// heap, `Fallback` tries a fixed storage buffer first and falls back to a3/// backing allocator. It adds no memory bound of its own, so the bound is4/// whatever the backing allocator imposes. Provenance routing sends every later5/// `free`, `resize`, or `remap` to the tier that owns the slice.6pub const Fallback = fixed.Fallback;