Module allocator
Memory allocation abstractions and global allocator interface.
Stability
stable — Layout, AllocError, GlobalAllocator, and the pluggable
surface: Allocator (a context pointer plus a vtable, Zig's
std.mem.Allocator shape; it and AllocatorVTable are defined in the
prelude, this module holds their methods). The
vtable (alloc, realloc, free, context first; interface version 2:
every call carries the alignment and realloc/free the block's size) and
the owner record in the 16 bytes before every block are frozen: codegen
writes the same record for every RC object placed by an alloc : .Some(a)
argument (plans/archive/EXPLICIT_ALLOCATORS.md, plans/VALUES_BY_DEFAULT.md
"After V2b: the allocator interface, version 2"). Implementors: the global
allocator and the counting allocators in tests/explicit_allocators.test.yo
and the collection tests.
Placement
A creation with no allocator argument goes to the global allocator; there
is no allocation scope. A block is placed in another allocator by an
argument at its creation site: Rc.new(v, alloc : .Some(a)), Box.new(v, alloc : .Some(a)), Arc.new(v, alloc : .Some(a)), ArrayList(T).new(alloc : .Some(a))
(plans/backlog/ALLOCATOR_PLACEMENT.md). clone_in(a) places a copy of a
container in a; clone() keeps the copy where its source lives.
Explicit allocators and the owner prefix
Every block handed out by Allocator.alloc(size, align) carries a prefix of
max(16, align) bytes immediately before the returned pointer; its last 16
hold the allocator's ctx and vtable. Allocator.realloc and
Allocator.free read them, so a block is always released to the allocator
that made it, whoever releases it and on whichever thread. The caller tells
realloc and free the size and alignment it asked for, as Zig's
Allocator does, so a size-class allocator (a pool, a slab) needs no header
of its own. Implementors never see the prefix: their alloc is asked for a
raw block of the prefix plus size, aligned to max(16, align), and this
module owns the layout. Codegen places reference-counted objects the same
way, with the object's extent ({size, align}) in the 16 bytes before the
owner record (a 32-byte prefix, or max(32, align)), because their release
path does not know the type; the two sides must never diverge.
Types
Describes the size and alignment requirements for a memory allocation.
Fields
| Name | Type | Description |
|---|---|---|
size | usize | Size in bytes. |
alignment | usize | Alignment in bytes (must be a power of two). |
Trait Implementations
impl(generic(T : Type), where(T <: Clone), T : (Clone))
impl(generic(T : Type), where(T <: Clone), T : (Clone), CloneInto)
clone_into : fn(self : &Self, dst : *(Self)) -> unitWrite a clone of self into the uninitialized slot dst, which has
room for size_of_val(self) bytes at align_of_val(self).
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self | |
dst | *(Self) |
Returns: unit
Memory allocation error variants.
Variants
| Variant | Fields | Description |
|---|---|---|
OutOfMemory | Allocator ran out of memory. |
Trait Implementations
impl(generic(T : Type), where(T <: Clone), T : (Clone))
impl(generic(T : Type), where(T <: Clone), T : (Clone), CloneInto)
clone_into : fn(self : &Self, dst : *(Self)) -> unitWrite a clone of self into the uninitialized slot dst, which has
room for size_of_val(self) bytes at align_of_val(self).
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self | |
dst | *(Self) |
Returns: unit
Methods
clone : (AllocError) fn(self : &AllocError) -> AllocErrorFunctions
Check if allocating count elements of type T would overflow usize.
Parameters
| Name | Type | Notes |
|---|---|---|
T | Type | comptime |
count | usize |
Returns: bool
Constants
The process-wide global allocator: the one --allocator selects (system
by default, mimalloc or fixed).
Two allocation families live here and they are not interchangeable:
| allocate with | release with |
|---|---|
malloc / calloc / realloc |
free |
aligned_alloc |
aligned_free |
Crossing the two corrupts the heap on Windows, where the aligned family is
the CRT's separate _aligned_malloc / _aligned_free pair.
Under --allocator fixed there is ONE family: aligned_free and free
are the same function, so the split above cannot bite (the region's
aligned_alloc splits a misaligned front piece back into the pool and
every release path coalesces through the same TLSF free).
Value: source_namespace_18332534865118561964_0(malloc: <unknown: fn(size : usize) -> ?(*(void))>, calloc: <unknown: fn(nmemb : usize, size : usize) -> ?(*(void))>, realloc: <unknown: fn(ptr : ?(*(void)), size : usize) -> ?(*(void))>, free: <unknown: fn(ptr : ?(*(void))) -> unit>, aligned_alloc: <fn(alignment, size)>, aligned_free: <unknown: fn(ptr : ?(*(void))) -> unit>)
Size of the owner record in front of every Allocator.alloc block, and the
smallest prefix: a block of alignment align has max(16, align) bytes in
front of it, the owner record in the last 16. 16 keeps the returned pointer
aligned for any scalar the plain family serves.
Value: 16