跳转到内容

std.heap.memory_pool

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

第 1 行

std.heap.memory_pool.Aligned

类型函数

第 12 行

可以快速分配单一类型对象的内存池。 需要分配大量同类型对象时应使用它,因为其性能优于通用分配器。 已分配元素的地址按 alignment 字节对齐,或者按 @alignOf(Item) 对齐,后者适用于 alignment 为 null 的情况。 可能分配内存的函数接受 Allocator 参数。

pub fn Aligned(comptime Item: type, comptime alignment: Alignment) type

参数

Item: type
alignment: Alignment

字段

arena_state: std.heap.ArenaAllocator.State
free_list: std.SinglyLinkedList

std.heap.memory_pool.Alignment

别名

第 3 行

别名目标 std.mem.Alignment

std.heap.memory_pool.Allocator

别名

第 2 行

别名目标 std.mem.Allocator

std.heap.memory_pool.Extra

类型函数

第 29 行

可以极快分配单一类型对象的内存池。 需要分配大量同类型对象时使用, 因为它比通用分配器性能更高。 可能分配内存的函数接受 Allocator 参数。

pub fn Extra(comptime Item: type, comptime pool_options: Options) type

参数

Item: type
pool_options: Options

字段

arena_state: std.heap.ArenaAllocator.State
free_list: std.SinglyLinkedList

std.heap.memory_pool.Extra.addCapacity

函数

第 79 行

预分配 num 个元素,并将其加入内存池。 这允许在调用 create() 可能发生 OutOfMemory 错误之前,至少拥有 num 个活动分配。

pub fn addCapacity(pool: *Pool, allocator: Allocator, num: usize) Allocator.Error!void

参数

pool: *Pool
allocator: Allocator
num: usize

错误

OutOfMemory

std.heap.memory_pool.Extra.allocNew

函数

第 132 行

fn allocNew(pool: *Pool, allocator: Allocator) Allocator.Error!*align(item_alignment.toByteUnits()) [item_size]u8

参数

pool: *Pool
allocator: Allocator

错误

OutOfMemory

std.heap.memory_pool.Extra.create

函数

第 113 行

创建新元素并将其加入内存池。 如果池不是 growable,则 allocator 可以为 undefined。

pub fn create(pool: *Pool, allocator: Allocator) Allocator.Error!ItemPtr

参数

pool: *Pool
allocator: Allocator

错误

OutOfMemory

std.heap.memory_pool.Extra.deinit

函数

第 71 行

销毁内存池并释放所有已分配内存。

pub fn deinit(pool: *Pool, allocator: Allocator) void

参数

pool: *Pool
allocator: Allocator

std.heap.memory_pool.Extra.destroy

函数

第 127 行

销毁先前创建的项。 传给 ptr 的项必须由同一个内存池的 create() 创建!

pub fn destroy(pool: *Pool, ptr: ItemPtr) void

参数

pool: *Pool
ptr: ItemPtr

std.heap.memory_pool.Extra.empty

常量

第 55 行

不含元素的 MemoryPool。

Pool

std.heap.memory_pool.Extra.initCapacity

函数

第 63 行

创建新内存池,并预分配 num 个条目。 这允许至多 num 个活动分配,之后调用 create() 才可能出现 OutOfMemory 错误。

pub fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Pool

参数

allocator: Allocator
num: usize

错误

OutOfMemory

std.heap.memory_pool.Extra.item_alignment

常量

第 49 行

内存池元素的对齐要求。不一定等于 @alignOf(Item), 因为池也会将元素用于内部用途。

Alignment

std.heap.memory_pool.Extra.item_size

常量

第 45 行

内存池项目大小。不一定等于 @sizeOf(Item),因为内存池也会将项目用于内部用途。

std.heap.memory_pool.Extra.ItemPtr

类型

第 52 行

std.heap.memory_pool.Extra.Node

别名

第 51 行

别名目标 std.SinglyLinkedList.Node

std.heap.memory_pool.Extra.Pool

别名

第 38 行

别名目标 std.heap.memory_pool.Extra

std.heap.memory_pool.Extra.reset

函数

第 98 行

重置内存池并销毁全部已分配项目。 可用于批量销毁所有对象,而不使内存池失效。

返回重置操作是否成功。 若重新分配失败,返回 false。此时内存池仍 完全可用,全部内存均已释放;只是后续分配 可能变慢。

注意:若 mode 为 free_all,此函数始终返回 true。

pub fn reset(pool: *Pool, allocator: Allocator, mode: ResetMode) bool

参数

pool: *Pool
allocator: Allocator
mode: ResetMode

std.heap.memory_pool.Extra.ResetMode

别名

第 87 行

别名目标 std.heap.ArenaAllocator.ResetMode

std.heap.memory_pool.MemoryPool

别名

第 4 行

别名目标 std.heap.MemoryPool

std.heap.memory_pool.Options

容器

第 16 行

字段

alignment: ?Alignment = null

内存池项目的对齐值。使用 null 表示自然对齐。

growable: bool = true

为 true 时,内存池初始化后仍可分配更多元素。 为 false 时,调用 initPreheated 后内存池不再分配元素。

std.heap.memory_pool.std

别名

第 1 行

别名目标 std

源码

std/heap/memory_pool.zig

const std = @import("../std.zig");
const Allocator = std.mem.Allocator;
const Alignment = std.mem.Alignment;
const MemoryPool = std.heap.MemoryPool;

/// 可以快速分配单一类型对象的内存池。
/// 需要分配大量同类型对象时应使用它,因为其性能优于通用分配器。
/// 已分配元素的地址按 `alignment` 字节对齐,或者按 `@alignOf(Item)` 对齐,后者适用于 `alignment` 为 `null` 的情况。
/// 可能分配内存的函数接受 `Allocator` 参数。
///
///
pub fn Aligned(comptime Item: type, comptime alignment: Alignment) type {
    return Extra(Item, .{ .alignment = alignment });
}

pub const Options = struct {
    /// 内存池项目的对齐值。使用 `null` 表示自然对齐。
    alignment: ?Alignment = null,

    /// 为 `true` 时,内存池初始化后仍可分配更多元素。
    /// 为 `false` 时,调用 `initPreheated` 后内存池不再分配元素。
    growable: bool = true,
};

/// 可以极快分配单一类型对象的内存池。
/// 需要分配大量同类型对象时使用,
/// 因为它比通用分配器性能更高。
/// 可能分配内存的函数接受 `Allocator` 参数。
pub fn Extra(comptime Item: type, comptime pool_options: Options) type {
    if (pool_options.alignment) |a| {
        if (a.compare(.eq, .of(Item))) {
            var new_options = pool_options;
            new_options.alignment = null;
            return Extra(Item, new_options);
        }
    }
    return struct {
        const Pool = @This();

        arena_state: std.heap.ArenaAllocator.State,
        free_list: std.SinglyLinkedList,

        /// 内存池项目大小。不一定等于 `@sizeOf(Item)`,因为内存池也会将项目用于内部用途。
        ///
        pub const item_size = @max(@sizeOf(Node), @sizeOf(Item));

        /// 内存池元素的对齐要求。不一定等于 `@alignOf(Item)`,
        /// 因为池也会将元素用于内部用途。
        pub const item_alignment: Alignment = .max(pool_options.alignment orelse .of(Item), .of(Node));

        const Node = std.SinglyLinkedList.Node;
        const ItemPtr = *align(item_alignment.toByteUnits()) Item;

        /// 不含元素的 MemoryPool。
        pub const empty: Pool = .{
            .arena_state = .{},
            .free_list = .{},
        };

        /// 创建新内存池,并预分配 `num` 个条目。
        /// 这允许至多 `num` 个活动分配,之后调用 `create()`
        /// 才可能出现 `OutOfMemory` 错误。
        pub fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Pool {
            var pool: Pool = .empty;
            errdefer pool.deinit(allocator);
            try pool.addCapacity(allocator, num);
            return pool;
        }

        /// 销毁内存池并释放所有已分配内存。
        pub fn deinit(pool: *Pool, allocator: Allocator) void {
            pool.arena_state.promote(allocator).deinit();
            pool.* = undefined;
        }

        /// 预分配 `num` 个元素,并将其加入内存池。
        /// 这允许在调用 `create()` 可能发生 `OutOfMemory`
        /// 错误之前,至少拥有 `num` 个活动分配。
        pub fn addCapacity(pool: *Pool, allocator: Allocator, num: usize) Allocator.Error!void {
            var i: usize = 0;
            while (i < num) : (i += 1) {
                const memory = try pool.allocNew(allocator);
                pool.free_list.prepend(@ptrCast(memory));
            }
        }

        pub const ResetMode = std.heap.ArenaAllocator.ResetMode;

        /// 重置内存池并销毁全部已分配项目。
        /// 可用于批量销毁所有对象,而不使内存池失效。
        ///
        /// 返回重置操作是否成功。
        /// 若重新分配失败,返回 `false`。此时内存池仍
        /// 完全可用,全部内存均已释放;只是后续分配
        /// 可能变慢。
        ///
        /// 注意:若 `mode` 为 `free_all`,此函数始终返回 `true`。
        pub fn reset(pool: *Pool, allocator: Allocator, mode: ResetMode) bool {
            // TODO: 也可考虑将所有已分配对象存储在列表中,
            // 从而只需将它们移入空闲链表,而非实际释放内存。

            var arena = pool.arena_state.promote(allocator);
            defer pool.arena_state = arena.state;

            const reset_successful = arena.reset(mode);
            pool.free_list = .{};

            return reset_successful;
        }

        /// 创建新元素并将其加入内存池。
        /// 如果池不是 `growable`,则 `allocator` 可以为 `undefined`。
        pub fn create(pool: *Pool, allocator: Allocator) Allocator.Error!ItemPtr {
            const ptr: ItemPtr = if (pool.free_list.popFirst()) |node|
                @ptrCast(@alignCast(node))
            else if (pool_options.growable)
                @ptrCast(try pool.allocNew(allocator))
            else
                return error.OutOfMemory;

            ptr.* = undefined;
            return ptr;
        }

        /// 销毁先前创建的项。
        /// 传给 `ptr` 的项必须由同一个内存池的 `create()` 创建!
        pub fn destroy(pool: *Pool, ptr: ItemPtr) void {
            ptr.* = undefined;
            pool.free_list.prepend(@ptrCast(ptr));
        }

        fn allocNew(pool: *Pool, allocator: Allocator) Allocator.Error!*align(item_alignment.toByteUnits()) [item_size]u8 {
            var arena = pool.arena_state.promote(allocator);
            defer pool.arena_state = arena.state;
            const memory = try arena.allocator().alignedAlloc(u8, item_alignment, item_size);
            return memory[0..item_size];
        }
    };
}

test "basic" {
    const a = std.testing.allocator;

    var pool: MemoryPool(u32) = .empty;
    defer pool.deinit(a);

    const p1 = try pool.create(a);
    const p2 = try pool.create(a);
    const p3 = try pool.create(a);

    // 断言唯一性
    try std.testing.expect(p1 != p2);
    try std.testing.expect(p1 != p3);
    try std.testing.expect(p2 != p3);

    pool.destroy(p2);
    const p4 = try pool.create(a);

    // 断言内存复用
    try std.testing.expect(p2 == p4);
}

test "initCapacity (success)" {
    const a = std.testing.allocator;

    var pool: MemoryPool(u32) = try .initCapacity(a, 4);
    defer pool.deinit(a);

    _ = try pool.create(a);
    _ = try pool.create(a);
    _ = try pool.create(a);
}

test "initCapacity (failure)" {
    const failer = std.testing.failing_allocator;
    try std.testing.expectError(error.OutOfMemory, MemoryPool(u32).initCapacity(failer, 5));
}

test "growable" {
    const a = std.testing.allocator;

    var pool: Extra(u32, .{ .growable = false }) = try .initCapacity(a, 4);
    defer pool.deinit(a);

    _ = try pool.create(a);
    _ = try pool.create(a);
    _ = try pool.create(a);
    _ = try pool.create(a);

    try std.testing.expectError(error.OutOfMemory, pool.create(a));
}

test "greater than pointer default alignment" {
    const Foo = struct {
        data: u64 align(16),
    };
    const a = std.testing.allocator;

    var pool: MemoryPool(Foo) = .empty;
    defer pool.deinit(a);

    const foo: *Foo = try pool.create(a);
    pool.destroy(foo);
}

test "greater than pointer manual alignment" {
    const Foo = struct {
        data: u64,
    };
    const a = std.testing.allocator;

    var pool: Aligned(Foo, .@"16") = .empty;
    defer pool.deinit(a);

    const foo: *align(16) Foo = try pool.create(a);
    pool.destroy(foo);
}