Memory

Arrays, slices, pointers, cast and slice, and arenas. There is no new, no global heap and no destructor.

Markdown version of this page

#What there is, and what there is not

There is no new or destroy, no global heap and no destructors. Memory comes from arenas, which are library values passed explicitly, and is released a whole arena at a time. Data lives in tables and refers to other data by integer handle, not by pointer. Pointers exist for FFI and for slices inside a kernel. defer runs a statement at scope exit for the rare owned resource.

Nothing allocates, bounds-checks or copies behind the programmer's back.

#Arrays

[N]T is N values of type T back to back. N is a constant expression of at least 1 and T is any type but nul. a.len is N, a usz. Elements are stored at the type's real size and natural alignment.

An array is memory and is never copied: assigning a whole array, initializing one from another, comparing two and returning one are all refused. Passing an array to a function passes its address, in every mode. A variable declared without a value is zero, arrays included, and the declaration zeroes it every time it runs.

[300000]u8 a;
a[0] = 3; a[299999] = 4;
ret i32(a[0]) * 10 + i32(a[299999]) + i32(a.len);

The program that contains these lines builds, runs and exits with code 300034: 3 * 10 + 4 + 300000. A function's frame holds its variables, and a frame of a page or more is probed page by page in the function's first instructions so Windows commits the stack as the frame grows.

There are no bounds checks: an index outside the array reads or writes whatever memory is there. The index is a usz; a literal takes that type.

#Slices

A slice []T is a pointer and a length: s.ptr is a *T, s.len a usz. A string literal is a []u8 of its bytes with no terminator, in read-only memory. An array converts to a slice of its elements wherever a slice is expected; it is the one implicit conversion, and the slice is a view of the same memory, never a copy.

i32 main() { []u8 s = "hello"; usz total = 0; for i in 0..s.len { total += i; } ret i32(total); }

Verified: builds and runs. Exit code 10. No stdout.

x[a..b] and x[a..=b] are the slice of the elements from a up to b, in the same memory. The bounds are unchecked: the length is b - a computed with wrap-around. A sub-slice is a value, not a place: it cannot be assigned or have its address taken.

#Pointers

*T is a pointer. &place is the address of a variable, an element or a dereference, *p reads the pointee, and *p = v writes it. The pointee is read and written at its own size.

*bool p = &b[0];
*p = true;

For p of type *T and a usz n, p + n and p - n move by n elements, and p - q is the number of elements between two pointers of the same type. A pointer cannot be indexed; slice(p, n) makes a slice of it first. The address of a local is valid until its function returns and nothing checks that.

cast(x) converts a pointer to a pointer of another type, a pointer to a usz and a usz to a pointer, without changing a bit. Its target type is the one the context expects: a declared variable type, a parameter, a return type, the other side of an assignment or of ==. slice(p, n) makes the []T of n elements that start at the *T p.

[3]i8 a;
[]u8 raw = slice(cast(&a[0]), 3);

nil is a pointer of whatever pointer type the context wants. Reads and writes through a pointer need not be aligned.

#Arenas

An arena is a block of memory handed out in order. mem.Arena is a record in the standard library:

pub rec Arena { *u8 base; usz used; usz cap; }

From the standard library module mem. It is written in Lane.

alloc returns the next size bytes, aligned as asked, all zero, or an empty slice when they do not fit. A failed call changes nothing. It is ordinary Lane: arithmetic on addresses with cast, and slice to make the result.

pub []u8 alloc(wr Arena a, usz size, usz align) {
    []u8 none;
    if size == 0 || align == 0 || (align & (align - 1)) != 0 { ret none; }
    usz base = cast(a.base);
    usz pad = (-(base + a.used)) & (align - 1);
    if pad > a.cap - a.used { ret none; }
    usz start = a.used + pad;
    if size > a.cap - start { ret none; }
    a.used = start + size;
    ret slice(a.base + start, size);
}

From the standard library module mem. It is written in Lane.

pad is the number of bytes to skip so that the start of the allocation is a multiple of align.

An arena takes its memory from the system (VirtualAlloc on Windows), and release gives it back:

pub nul release(wr Arena a) {
    if a.base != nil { VirtualFree(cast(a.base), 0, MEM_RELEASE); }
    a.base = nil;
    a.used = 0;
    a.cap = 0;
}

From the standard library module mem. It is written in Lane.

A function that needs memory takes the arena as a wr parameter, so the caller sees which calls allocate. The standard library does this: os.read_file reads a file into an arena.

pub bool read_file([]u8 path, wr mem.Arena a, out []u8 data) {

From the standard library module os. It is written in Lane.

mem also has reset, copy (which handles overlap), eq and fill. See Modules and the standard library.