ona/source/coral/slab.zig

169 lines
5.1 KiB
Zig
Raw Normal View History

const debug = @import("./debug.zig");
const io = @import("./io.zig");
2023-06-03 21:55:59 +02:00
const math = @import("./math.zig");
2023-06-03 21:55:59 +02:00
const std = @import("std");
///
2023-06-03 22:05:47 +02:00
/// Addressable mapping of integers described by `index_int` to values of type `Value`.
2023-06-03 21:55:59 +02:00
///
2023-06-03 22:05:47 +02:00
/// Slab maps are similar to slot maps in that they have O(1) insertion and removal, however, use a flat table layout
/// instead of parallel arrays. This reduces memory usage in some cases and can be useful for data that does not need to
/// be quickly iterated over, as values ordering is not guaranteed.
2023-06-03 21:55:59 +02:00
///
/// *Note* `index_int` values may be as big or as small as desired per the use-case of the consumer, however, integers
/// smaller than `usize` may result in the map reporting it is out of memory due to exhausting the addressable space
/// provided by the integer.
///
pub fn Map(comptime index_int: std.builtin.Type.Int, comptime Value: type) type {
return struct {
2023-06-02 23:43:53 +02:00
free_index: Index = 0,
2023-06-03 21:55:59 +02:00
count: Index = 0,
table: []Entry = &.{},
2023-06-03 21:55:59 +02:00
///
/// Table entry which may either store an inserted value or an index to the next free entry in the table.
///
const Entry = union (enum) {
2023-06-03 21:55:59 +02:00
free_index: Index,
value: Value,
};
2023-06-03 21:55:59 +02:00
///
/// Used for indexing into the slab map.
///
const Index = math.Int(index_int);
///
2023-06-03 22:05:47 +02:00
/// Slab map type.
2023-06-03 21:55:59 +02:00
///
const Self = @This();
2023-06-03 21:55:59 +02:00
///
/// Overwrites the value referenced by `index` in `self`.
///
pub fn assign(self: *Self, index: Index, value: Value) void {
const entry = &self.table[index];
debug.assert(entry.* == .value);
entry.value = value;
}
///
/// Fetches the value referenced by `index` in `self`, returning it.
///
pub fn fetch(self: *Self, index: Index) Value {
const entry = &self.table[index];
2023-06-03 21:55:59 +02:00
debug.assert(entry.* == .value);
2023-06-03 21:55:59 +02:00
return entry.value;
}
2023-06-03 21:55:59 +02:00
///
/// Deinitializes `self` and sets it to an invalid state, freeing all memory allocated by `allocator`.
///
/// *Note* if the `table` field of `self` is an allocated slice, `allocator` must reference the same allocation
/// strategy as the one originally used to allocate the current table.
///
pub fn deinit(self: *Self, allocator: io.Allocator) void {
2023-06-03 21:55:59 +02:00
if (self.table.len == 0) {
return;
}
io.deallocate(allocator, self.table);
self.table = &.{};
self.count = 0;
2023-06-03 22:05:47 +02:00
self.free_index = 0;
}
2023-06-03 21:55:59 +02:00
///
/// Attempts to grow the internal buffer of `self` by `growth_amount` using `allocator`.
///
/// The function returns [io.AllocatorError] if `allocator` could not commit the memory required to grow the
/// table by `growth_amount`, leaving `self` in the same state that it was in prior to starting the grow.
///
/// Growing ahead of multiple insertion operations is useful when the upper bound of insertions is well-
/// understood, as it can reduce the number of allocations required per insertion.
///
/// *Note* if the `table` field of `self` is an allocated slice, `allocator` must reference the same allocation
/// strategy as the one originally used to allocate the current table.
///
pub fn grow(self: *Self, allocator: io.Allocator, growth_amount: usize) io.AllocationError!void {
const grown_capacity = self.table.len + growth_amount;
const entries = try io.allocate_many(allocator, grown_capacity, Entry);
2023-06-03 21:55:59 +02:00
errdefer io.deallocate(allocator, entries);
if (self.table.len != 0) {
for (0 .. self.table.len) |index| {
entries[index] = self.table[index];
}
for (self.table.len .. entries.len) |index| {
entries[index] = .{.free_index = 0};
}
io.deallocate(allocator, self.table);
}
2023-06-03 21:55:59 +02:00
self.table = entries;
}
2023-06-03 21:55:59 +02:00
///
/// Attempts to insert `value` into `self` as a new entry using `allocator` as the allocation strategy,
/// returning an index value representing a reference to the inserted value that may be queried through `self`
/// after.
///
/// The function returns [io.AllocationError] if `allocator` could not commit the memory required to grow the
/// internal buffer of `self` when necessary.
///
/// *Note* if the `table` field of `self` is an allocated slice, `allocator` must reference the same allocation
/// strategy as the one originally used to allocate the current table.
///
pub fn insert(self: *Self, allocator: io.Allocator, value: Value) io.AllocationError!Index {
if (self.count == self.table.len) {
try self.grow(allocator, math.max(1, self.count));
}
if (self.free_index == self.count) {
const entry_index = self.count;
const entry = &self.table[entry_index];
entry.* = .{.value = value};
self.count += 1;
self.free_index += 1;
return entry_index;
}
const entry_index = self.free_index;
const entry = &self.table[self.free_index];
debug.assert(entry.* == .free_index);
self.free_index = entry.free_index;
entry.* = .{.value = value};
return entry_index;
}
///
/// Removes the value referenced by `index` from `self`.
///
pub fn remove(self: *Self, index: Index) void {
2023-06-03 21:55:59 +02:00
const entry = &self.table[index];
debug.assert(entry.* == .value);
2023-06-03 21:55:59 +02:00
entry.* = .{.free_index = self.free_index};
self.free_index = index;
}
};
}