Forge

std.alloc

Heap memory allocation.

from std.alloc import alloc, free

Functions

alloc

def alloc(size: uint64) -> ptr[char]

Allocate size bytes. Returns a ptr[char]. Aborts on OOM.

let buf: ptr[char] = alloc(1024)
unsafe:
    *buf = (65 as char)
free(buf)

Cast the result to other pointer types when needed:

let p = alloc(64) as ptr[int32]

free

def free(p: ptr[char]) -> void

Free a previously allocated block.

• x86_64: prepends the block to the free list; memory is reused by future allocations
• x86_32: returns the block to the free list; memory is reused by future allocations

Allocator Behavior

Target	Allocator	free behavior
x86_64	First-fit free list with splitting, 8-byte header per block (bit 0 = used, bit 1 = mark, rest = size)	Block returned to free list
x86_32	First-fit free list with splitting, 4-byte header per block (bit 0 = used, rest = size)	Block returned to free list
x86_16	Not available	—

On x86_64 the heap is a 4 MiB .bss region. When the free list is exhausted, a conservative mark-and-sweep collection runs automatically and the allocation retries once before aborting. See std.gc.

On x86_32 the heap is also a 4 MiB .bss region, but there is no collector — allocation aborts when the free list is exhausted. Importing std.gc on x86_32 fails at codegen with a clean diagnostic.

Example

from std.alloc import alloc, free
from std.io import puts

pub def main() -> int32:
    let buf: ptr[char] = alloc(16)
    unsafe:
        *buf = (72 as char)          # 'H'
        *(buf + 1) = (105 as char)   # 'i'
        *(buf + 2) = (0 as char)     # null terminator
    puts(buf)
    free(buf)
    return 0

Safety

• Aborts on OOM (does not return null)
• No bounds checking — writes past the requested size corrupt the heap
• Double-free and use-after-free are undefined behavior
• Pass only alloc-returned pointers to free

This site is open source. Improve this page.