std.heap.memory_pool.Aligned
类型函数
可以快速分配单一类型对象的内存池。
需要分配大量同类型对象时应使用它,因为其性能优于通用分配器。
已分配元素的地址按 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
别名
别名目标 std.mem.Alignment
std.heap.memory_pool.Allocator
别名
别名目标 std.mem.Allocator
std.heap.memory_pool.Extra
类型函数
可以极快分配单一类型对象的内存池。
需要分配大量同类型对象时使用,
因为它比通用分配器性能更高。
可能分配内存的函数接受 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
函数
预分配 num 个元素,并将其加入内存池。
这允许在调用 create() 可能发生 OutOfMemory
错误之前,至少拥有 num 个活动分配。
pub fn addCapacity(pool: *Pool, allocator: Allocator, num: usize) Allocator.Error!void
参数
错误
- OutOfMemory
std.heap.memory_pool.Extra.allocNew
函数
fn allocNew(pool: *Pool, allocator: Allocator) Allocator.Error!*align(item_alignment.toByteUnits()) [item_size]u8
参数
错误
- OutOfMemory
std.heap.memory_pool.Extra.create
函数
创建新元素并将其加入内存池。
如果池不是 growable,则 allocator 可以为 undefined。
pub fn create(pool: *Pool, allocator: Allocator) Allocator.Error!ItemPtr
参数
错误
- OutOfMemory
std.heap.memory_pool.Extra.deinit
函数
销毁内存池并释放所有已分配内存。
pub fn deinit(pool: *Pool, allocator: Allocator) void
参数
std.heap.memory_pool.Extra.destroy
函数
销毁先前创建的项。
传给 ptr 的项必须由同一个内存池的 create() 创建!
pub fn destroy(pool: *Pool, ptr: ItemPtr) void
参数
std.heap.memory_pool.Extra.empty
常量
不含元素的 MemoryPool。
Pool
std.heap.memory_pool.Extra.initCapacity
函数
创建新内存池,并预分配 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
常量
内存池元素的对齐要求。不一定等于 @alignOf(Item),
因为池也会将元素用于内部用途。
Alignment
std.heap.memory_pool.Extra.item_size
常量
内存池项目大小。不一定等于 @sizeOf(Item),因为内存池也会将项目用于内部用途。
std.heap.memory_pool.Extra.ItemPtr
类型
std.heap.memory_pool.Extra.Node
别名
std.heap.memory_pool.Extra.Pool
别名
std.heap.memory_pool.Extra.reset
函数
重置内存池并销毁全部已分配项目。 可用于批量销毁所有对象,而不使内存池失效。
返回重置操作是否成功。
若重新分配失败,返回 false。此时内存池仍
完全可用,全部内存均已释放;只是后续分配
可能变慢。
注意:若 mode 为 free_all,此函数始终返回 true。
pub fn reset(pool: *Pool, allocator: Allocator, mode: ResetMode) bool
参数
std.heap.memory_pool.Extra.ResetMode
别名
std.heap.memory_pool.MemoryPool
别名
别名目标 std.heap.MemoryPool
std.heap.memory_pool.Options
容器
字段
alignment: ?Alignment = null内存池项目的对齐值。使用 null 表示自然对齐。
growable: bool = true为 true 时,内存池初始化后仍可分配更多元素。
为 false 时,调用 initPreheated 后内存池不再分配元素。
std.heap.memory_pool.std
别名
别名目标 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);
}