跳转到内容

std.heap.FixedBufferAllocator

标准库Zig 0.17.0官方原文
源码std/heap/FixedBufferAllocator.zig

第 1 行

字段

end_index: usize
buffer: []u8

std.heap.FixedBufferAllocator.alloc

函数

第 62 行

pub fn alloc(ctx: *anyopaque, n: usize, alignment: mem.Alignment, ra: usize) ?[*]u8

参数

ctx: *anyopaque
n: usize
alignment: mem.Alignment
ra: usize

std.heap.FixedBufferAllocator.allocator

函数

第 19 行

与 threadSafeAllocator 返回的接口同时使用时,不具备线程安全性。

pub fn allocator(self: *FixedBufferAllocator) Allocator

参数

std.heap.FixedBufferAllocator.Allocator

别名

第 2 行

别名目标 std.mem.Allocator

std.heap.FixedBufferAllocator.assert

别名

第 3 行

别名目标 std.debug.assert

std.heap.FixedBufferAllocator.FixedBufferAllocator

别名

第 6 行

别名目标 std.heap.FixedBufferAllocator

std.heap.FixedBufferAllocator.free

函数

第 114 行

pub fn free( ctx: *anyopaque, buf: []u8, alignment: mem.Alignment, return_address: usize, ) void

参数

ctx: *anyopaque
buf: []u8
alignment: mem.Alignment
return_address: usize

std.heap.FixedBufferAllocator.init

函数

第 11 行

pub fn init(buffer: []u8) FixedBufferAllocator

参数

buffer: []u8

std.heap.FixedBufferAllocator.isLastAllocation

函数

第 58 行

当最后一次分配具有 adjusted_index 时,此检查可能漏报。 在这种情况下,无法确定最后一次分配, 因为 alloc 中执行的 alignForward 操作 不可逆。

pub fn isLastAllocation(self: *FixedBufferAllocator, buf: []u8) bool

参数

self: *FixedBufferAllocator
buf: []u8

std.heap.FixedBufferAllocator.mem

别名

第 4 行

别名目标 std.mem

std.heap.FixedBufferAllocator.ownsPtr

函数

第 46 行

pub fn ownsPtr(self: *FixedBufferAllocator, ptr: [*]u8) bool

参数

self: *FixedBufferAllocator
ptr: [*]u8

std.heap.FixedBufferAllocator.ownsSlice

函数

第 50 行

pub fn ownsSlice(self: *FixedBufferAllocator, slice: []u8) bool

参数

self: *FixedBufferAllocator
slice: []u8

std.heap.FixedBufferAllocator.remap

函数

第 104 行

pub fn remap( context: *anyopaque, memory: []u8, alignment: mem.Alignment, new_len: usize, return_address: usize, ) ?[*]u8

参数

context: *anyopaque
memory: []u8
alignment: mem.Alignment
new_len: usize
return_address: usize

std.heap.FixedBufferAllocator.reset

函数

第 226 行

pub fn reset(self: *FixedBufferAllocator) void

参数

用法示例

test reset {
    var buf: [8]u8 align(@alignOf(u64)) = undefined;
    var fba = FixedBufferAllocator.init(buf[0..]);
    const a = fba.allocator();

    const X = 0xeeeeeeeeeeeeeeee;
    const Y = 0xffffffffffffffff;

    const x = try a.create(u64);
    x.* = X;
    try std.testing.expectError(error.OutOfMemory, a.create(u64));

    fba.reset();
    const y = try a.create(u64);
    y.* = Y;

    // 我们预计 Y 已覆盖 X。
    try std.testing.expect(x.* == y.*);
    try std.testing.expect(y.* == Y);
}

std.heap.FixedBufferAllocator.resize

函数

第 74 行

pub fn resize( ctx: *anyopaque, buf: []u8, alignment: mem.Alignment, new_size: usize, return_address: usize, ) bool

参数

ctx: *anyopaque
buf: []u8
alignment: mem.Alignment
new_size: usize
return_address: usize

std.heap.FixedBufferAllocator.sliceContainsPtr

函数

第 230 行

fn sliceContainsPtr(container: []u8, ptr: [*]u8) bool

参数

container: []u8
ptr: [*]u8

std.heap.FixedBufferAllocator.sliceContainsSlice

函数

第 235 行

fn sliceContainsSlice(container: []u8, slice: []u8) bool

参数

container: []u8
slice: []u8

std.heap.FixedBufferAllocator.std

别名

第 1 行

别名目标 std

std.heap.FixedBufferAllocator.test_fixed_buffer_allocator_memory

变量

第 240 行

[800000 * @sizeOf(u64)]u8

std.heap.FixedBufferAllocator.threadSafeAlloc

函数

第 130 行

fn threadSafeAlloc(ctx: *anyopaque, n: usize, alignment: mem.Alignment, ret_addr: usize) ?[*]u8

参数

ctx: *anyopaque
n: usize
alignment: mem.Alignment
ret_addr: usize

std.heap.FixedBufferAllocator.threadSafeAllocator

函数

第 34 行

为底层 FixedBufferAllocator 提供无锁、线程安全的 Allocator 接口。

同时使用此接口和 allocator 返回的接口并非线程安全。

pub fn threadSafeAllocator(self: *FixedBufferAllocator) Allocator

参数

std.heap.FixedBufferAllocator.threadSafeFree

函数

第 200 行

fn threadSafeFree(ctx: *anyopaque, memory: []u8, alignment: mem.Alignment, ret_addr: usize) void

参数

ctx: *anyopaque
memory: []u8
alignment: mem.Alignment
ret_addr: usize

std.heap.FixedBufferAllocator.threadSafeRemap

函数

第 196 行

fn threadSafeRemap(ctx: *anyopaque, memory: []u8, alignment: mem.Alignment, new_len: usize, ret_addr: usize) ?[*]u8

参数

ctx: *anyopaque
memory: []u8
alignment: mem.Alignment
new_len: usize
ret_addr: usize

std.heap.FixedBufferAllocator.threadSafeResize

函数

第 152 行

fn threadSafeResize(ctx: *anyopaque, memory: []u8, alignment: mem.Alignment, new_len: usize, ret_addr: usize) bool

参数

ctx: *anyopaque
memory: []u8
alignment: mem.Alignment
new_len: usize
ret_addr: usize
源码

std/heap/FixedBufferAllocator.zig

const std = @import("../std.zig");
const Allocator = std.mem.Allocator;
const assert = std.debug.assert;
const mem = std.mem;

const FixedBufferAllocator = @This();

end_index: usize,
buffer: []u8,

pub fn init(buffer: []u8) FixedBufferAllocator {
    return .{
        .buffer = buffer,
        .end_index = 0,
    };
}

/// 与 `threadSafeAllocator` 返回的接口同时使用时,不具备线程安全性。
pub fn allocator(self: *FixedBufferAllocator) Allocator {
    return .{
        .ptr = self,
        .vtable = &.{
            .alloc = alloc,
            .resize = resize,
            .remap = remap,
            .free = free,
        },
    };
}

/// 为底层 `FixedBufferAllocator` 提供无锁、线程安全的 `Allocator` 接口。
///
/// 同时使用此接口和 `allocator` 返回的接口并非线程安全。
pub fn threadSafeAllocator(self: *FixedBufferAllocator) Allocator {
    return .{
        .ptr = self,
        .vtable = &.{
            .alloc = threadSafeAlloc,
            .resize = threadSafeResize,
            .remap = threadSafeRemap,
            .free = threadSafeFree,
        },
    };
}

pub fn ownsPtr(self: *FixedBufferAllocator, ptr: [*]u8) bool {
    return sliceContainsPtr(self.buffer, ptr);
}

pub fn ownsSlice(self: *FixedBufferAllocator, slice: []u8) bool {
    return sliceContainsSlice(self.buffer, slice);
}

/// 当最后一次分配具有 adjusted_index 时,此检查可能漏报。
/// 在这种情况下,无法确定最后一次分配,
/// 因为 alloc 中执行的 alignForward 操作
/// 不可逆。
pub fn isLastAllocation(self: *FixedBufferAllocator, buf: []u8) bool {
    return buf.ptr + buf.len == self.buffer.ptr + self.end_index;
}

pub fn alloc(ctx: *anyopaque, n: usize, alignment: mem.Alignment, ra: usize) ?[*]u8 {
    const self: *FixedBufferAllocator = @ptrCast(@alignCast(ctx));
    _ = ra;
    const ptr_align = alignment.toByteUnits();
    const adjust_off = mem.alignPointerOffset(self.buffer.ptr + self.end_index, ptr_align) orelse return null;
    const adjusted_index = self.end_index + adjust_off;
    const new_end_index = adjusted_index + n;
    if (new_end_index > self.buffer.len) return null;
    self.end_index = new_end_index;
    return self.buffer.ptr + adjusted_index;
}

pub fn resize(
    ctx: *anyopaque,
    buf: []u8,
    alignment: mem.Alignment,
    new_size: usize,
    return_address: usize,
) bool {
    const self: *FixedBufferAllocator = @ptrCast(@alignCast(ctx));
    _ = alignment;
    _ = return_address;
    assert(@inComptime() or self.ownsSlice(buf));

    if (!self.isLastAllocation(buf)) {
        if (new_size > buf.len) return false;
        return true;
    }

    if (new_size <= buf.len) {
        const sub = buf.len - new_size;
        self.end_index -= sub;
        return true;
    }

    const add = new_size - buf.len;
    if (add + self.end_index > self.buffer.len) return false;

    self.end_index += add;
    return true;
}

pub fn remap(
    context: *anyopaque,
    memory: []u8,
    alignment: mem.Alignment,
    new_len: usize,
    return_address: usize,
) ?[*]u8 {
    return if (resize(context, memory, alignment, new_len, return_address)) memory.ptr else null;
}

pub fn free(
    ctx: *anyopaque,
    buf: []u8,
    alignment: mem.Alignment,
    return_address: usize,
) void {
    const self: *FixedBufferAllocator = @ptrCast(@alignCast(ctx));
    _ = alignment;
    _ = return_address;
    assert(@inComptime() or self.ownsSlice(buf));

    if (self.isLastAllocation(buf)) {
        self.end_index -= buf.len;
    }
}

fn threadSafeAlloc(ctx: *anyopaque, n: usize, alignment: mem.Alignment, ret_addr: usize) ?[*]u8 {
    const self: *FixedBufferAllocator = @ptrCast(@alignCast(ctx));
    _ = ret_addr;
    const ptr_align = alignment.toByteUnits();
    var cur_end_index = @atomicLoad(usize, &self.end_index, .monotonic);
    while (true) {
        const adjust_off = mem.alignPointerOffset(self.buffer.ptr + cur_end_index, ptr_align) orelse return null;
        const adjusted_index = cur_end_index + adjust_off;
        const new_end_index = adjusted_index + n;
        if (new_end_index > self.buffer.len) return null;
        cur_end_index = @cmpxchgWeak(
            usize,
            &self.end_index,
            cur_end_index,
            new_end_index,
            .acquire, // 获取可能已释放的任意内存
            .monotonic,
        ) orelse
            return self.buffer[adjusted_index..new_end_index].ptr;
    }
}

fn threadSafeResize(ctx: *anyopaque, memory: []u8, alignment: mem.Alignment, new_len: usize, ret_addr: usize) bool {
    const fba: *FixedBufferAllocator = @ptrCast(@alignCast(ctx));
    _ = alignment;
    _ = ret_addr;

    const cur_end_index = @atomicLoad(usize, &fba.end_index, .monotonic);
    if (fba.buffer.ptr + cur_end_index != memory.ptr + memory.len) {
        // 这不是最近一次分配,因此不能扩展,
        // 但允许调用方缩小它。
        return new_len <= memory.len;
    }

    if (new_len <= memory.len) {
        const new_end_index = cur_end_index - (memory.len - new_len);
        assert(fba.buffer.ptr + new_end_index == memory.ptr + new_len);

        _ = @cmpxchgStrong(
            usize,
            &fba.end_index,
            cur_end_index,
            new_end_index,
            .release, // 释放已归还的内存
            .monotonic,
        );
        return true; // 缩小内存分配应当始终成功。
    }

    if (fba.buffer.len - cur_end_index >= new_len - memory.len) {
        const new_end_index = cur_end_index + (new_len - memory.len);
        assert(fba.buffer.ptr + new_end_index == memory.ptr + new_len);

        return null == @cmpxchgStrong(
            usize,
            &fba.end_index,
            cur_end_index,
            new_end_index,
            .acquire, // 获取可能已释放的任意内存
            .monotonic,
        );
    }

    return false;
}

fn threadSafeRemap(ctx: *anyopaque, memory: []u8, alignment: mem.Alignment, new_len: usize, ret_addr: usize) ?[*]u8 {
    return if (threadSafeResize(ctx, memory, alignment, new_len, ret_addr)) memory.ptr else null;
}

fn threadSafeFree(ctx: *anyopaque, memory: []u8, alignment: mem.Alignment, ret_addr: usize) void {
    const fba: *FixedBufferAllocator = @ptrCast(@alignCast(ctx));
    _ = alignment;
    _ = ret_addr;

    assert(memory.len > 0);

    const cur_end_index = @atomicLoad(usize, &fba.end_index, .monotonic);
    if (fba.buffer.ptr + cur_end_index != memory.ptr + memory.len) {
        // 不是最近一次分配,无法释放它。
        return;
    }

    const new_end_index = cur_end_index - memory.len;
    assert(fba.buffer.ptr + new_end_index == memory.ptr);

    _ = @cmpxchgStrong(
        usize,
        &fba.end_index,
        cur_end_index,
        new_end_index,
        .release, // 释放已归还的内存
        .monotonic,
    );
}

pub fn reset(self: *FixedBufferAllocator) void {
    self.end_index = 0;
}

fn sliceContainsPtr(container: []u8, ptr: [*]u8) bool {
    return @intFromPtr(ptr) >= @intFromPtr(container.ptr) and
        @intFromPtr(ptr) < (@intFromPtr(container.ptr) + container.len);
}

fn sliceContainsSlice(container: []u8, slice: []u8) bool {
    return @intFromPtr(slice.ptr) >= @intFromPtr(container.ptr) and
        (@intFromPtr(slice.ptr) + slice.len) <= (@intFromPtr(container.ptr) + container.len);
}

var test_fixed_buffer_allocator_memory: [800000 * @sizeOf(u64)]u8 = undefined;

test FixedBufferAllocator {
    var fixed_buffer_allocator = mem.validationWrap(FixedBufferAllocator.init(test_fixed_buffer_allocator_memory[0..]));
    const a = fixed_buffer_allocator.allocator();

    try std.heap.testAllocator(a);
    try std.heap.testAllocatorAligned(a);
    try std.heap.testAllocatorLargeAlignment(a);
    try std.heap.testAllocatorAlignedShrink(a);
}

test reset {
    var buf: [8]u8 align(@alignOf(u64)) = undefined;
    var fba = FixedBufferAllocator.init(buf[0..]);
    const a = fba.allocator();

    const X = 0xeeeeeeeeeeeeeeee;
    const Y = 0xffffffffffffffff;

    const x = try a.create(u64);
    x.* = X;
    try std.testing.expectError(error.OutOfMemory, a.create(u64));

    fba.reset();
    const y = try a.create(u64);
    y.* = Y;

    // 我们预计 Y 已覆盖 X。
    try std.testing.expect(x.* == y.*);
    try std.testing.expect(y.* == Y);
}

test "reuse memory on realloc" {
    var small_fixed_buffer: [10]u8 = undefined;
    // 检查是否复用了内存
    {
        var fixed_buffer_allocator = FixedBufferAllocator.init(small_fixed_buffer[0..]);
        const a = fixed_buffer_allocator.allocator();

        const slice0 = try a.alloc(u8, 5);
        try std.testing.expect(slice0.len == 5);
        const slice1 = try a.realloc(slice0, 10);
        try std.testing.expect(slice1.ptr == slice0.ptr);
        try std.testing.expect(slice1.len == 10);
        try std.testing.expectError(error.OutOfMemory, a.realloc(slice1, 11));
    }
    // 检查非最新块的内存不会被复用
    {
        var fixed_buffer_allocator = FixedBufferAllocator.init(small_fixed_buffer[0..]);
        const a = fixed_buffer_allocator.allocator();

        var slice0 = try a.alloc(u8, 2);
        slice0[0] = 1;
        slice0[1] = 2;
        const slice1 = try a.alloc(u8, 2);
        const slice2 = try a.realloc(slice0, 4);
        try std.testing.expect(slice0.ptr != slice2.ptr);
        try std.testing.expect(slice1.ptr != slice2.ptr);
        try std.testing.expect(slice2[0] == 1);
        try std.testing.expect(slice2[1] == 2);
    }
}

test "thread safe version" {
    var fixed_buffer_allocator = FixedBufferAllocator.init(test_fixed_buffer_allocator_memory[0..]);

    try std.heap.testAllocator(fixed_buffer_allocator.threadSafeAllocator());
    try std.heap.testAllocatorAligned(fixed_buffer_allocator.threadSafeAllocator());
    try std.heap.testAllocatorLargeAlignment(fixed_buffer_allocator.threadSafeAllocator());
    try std.heap.testAllocatorAlignedShrink(fixed_buffer_allocator.threadSafeAllocator());
}