Arenas

An arena is a big block of memory. You push data into it one piece after another. You do not free pieces one by one. Instead you reset the whole arena at once.

This is the best way to work with temporary memory. It is fast and you can not forget to free something.

Temp arenas

The standard library has a few scratch arenas per thread. #temp_arena() takes one and resets it at the end of the current scope:

fn work() {
    arena := #temp_arena();

    buf : []u8 = arena_push(arena, 1024); // 1024 bytes
    ptr : *i64 = arena_push(arena, i64);  // one i64

    // everything is gone after this function ends
}

Pushing data

buf : []u8 = arena_push(arena, 1024);
ptr : *i64 = arena_push(arena, i64);

// copies
ptr = arena_push_copy(arena, ptr.*);
buf_copy : []u8 = arena_push_slice_copy(arena, buf);

// string copies
str : []u8 = arena_push_str_copy(arena, "hello world!");
str_c : []u8 = arena_push_str_copy_c(arena, "hello world!"); // with zero at the end

Avoiding conflicts

Sometimes a function puts its result into memory from the caller and also needs its own temp memory. If both use the same scratch arena, the temp memory can overwrite the result.

To avoid this, pass the allocator of the result to #temp_arena. It will pick a different scratch arena:

other := get_context_temp_arena_as_alloc();
arena := #temp_arena(other); // never the arena behind other

An allocator that is not backed by a scratch arena never conflicts.

Temp buffers

#temp_buffer is a short way to get temporary bytes:

buf := #temp_buffer(1024);
buf := #temp_buffer(1024, other); // avoid conflict with other

#temp_c_string makes a temporary C string (with zero at the end) from a slice:

c_str := #temp_c_string("hello world");
c_str := #temp_c_string("hello world", other);

Full example

This function reads a line from the console. It uses a temp buffer for reading, then copies the result into the arena the caller passed:

#linkc fn gets(buf: *u8): *u8;

fn read_line(arena: *Arena = get_context_temp_arena()): []u8 {
    const max_len := 1024i64;

    // a different scratch arena than `arena`, freed at the end of this scope
    tmp_buf := #temp_buffer(max_len, arena_as_allocator(arena));
    gets(tmp_buf.ptr);

    str_len := c_strlen(tmp_buf.ptr, max_len);

    // copy into the caller's arena, so it lives after we return
    dst := arena_push(arena, str_len);
    mem_copy(dst, tmp_buf);

    return dst;
}