# Memory

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

## 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.

```lane
[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.

```lane
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.

```lane
*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`.

```lane
[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:

```lane
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.

```lane
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:

```lane
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.

```lane
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](/docs/modules.md).
