Module allocator

allocator
Stability: stable — changes additively from here.

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

Layout struct
Layout

Describes the size and alignment requirements for a memory allocation.

Fields

NameTypeDescription
sizeusize

Size in bytes.

alignmentusize

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)) -> unit

Write a clone of self into the uninitialized slot dst, which has room for size_of_val(self) bytes at align_of_val(self).

Parameters

NameTypeNotes
selfSelf
dst*(Self)

Returns: unit

Methods
clone : (Layout) fn(self : &Layout) -> Layout

Parameters

NameTypeNotes
selfLayout

Returns: Layout

AllocError enum
AllocError

Memory allocation error variants.

Variants

VariantFieldsDescription
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)) -> unit

Write a clone of self into the uninitialized slot dst, which has room for size_of_val(self) bytes at align_of_val(self).

Parameters

NameTypeNotes
selfSelf
dst*(Self)

Returns: unit

Methods
clone : (AllocError) fn(self : &AllocError) -> AllocError

Parameters

NameTypeNotes
selfAllocError

Returns: AllocError

Functions

fn(comptime(T) : Type, count : usize) -> bool

Check if allocating count elements of type T would overflow usize.

Parameters

NameTypeNotes
TTypecomptime
countusize

Returns: bool

layout_of function
fn(comptime(T) : Type) -> comptime(Layout)

Get the memory layout (size and alignment) of a type at compile time.

Parameters

NameTypeNotes
TTypecomptime

Returns: comptime(Layout)

Constants

GlobalAllocator constant module (malloc : fn(size : usize) -> ?(*(void)), calloc : fn(nmemb : usize, size : usize) -> ?(*(void)), realloc : fn(ptr : ?(*(void)), size : usize) -> ?(*(void)), free : fn(ptr : ?(*(void))) -> unit, aligned_alloc : fn(alignment : usize, size : usize) -> ?(*(void)), aligned_free : fn(ptr : ?(*(void))) -> unit)

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>)

ALLOC_PREFIX_SIZE constant usize

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