Standard library · System and tools

mem

Working with memory directly: allocating and freeing, copying, arenas and pools, and leak checking.

import mem

Most programs never need this package: vectors, maps and strings look after their own memory. The mem package is for low-level work, such as talking to a C library, filling a byte buffer by hand or building a data structure of your own. Its functions are thin wrappers over the C allocator (malloc, realloc, free, memcpy), plus two allocators of its own and leak counters.

  • Allocate, Reallocate and Free: one block at a time, freed by you.
  • An arena is one large block you take pieces off the front of and then release all at once; it is very fast for many small objects that share a lifetime.
  • A pool hands out and takes back blocks of one fixed size, in any order.

For a growing list of values, Vector is the safer choice; for bytes and binary formats, see encoding.binary. To watch memory from outside a function, debug has MemStats and runtime reports the machine's memory.

The things people get wrong:

  • Nothing is checked. Writing past the end of a block, freeing it twice or using it after Free, ArenaReset or PoolFree corrupts memory without an error message. salam memcheck finds these for blocks from Allocate, but not inside an arena or a pool, which are one block to it.
  • Give memory back the way it was taken: mem.Free for Allocate, the C library's own function for what a C library returns. In a -DSALAM_MEM_DEBUG build every block from Allocate has a hidden 8 byte header, so mixing the two crashes there even when a normal build seems fine.
  • Check for null. Allocate, ArenaAlloc and PoolAlloc all return it when there is no memory or no room.
  • The arena and the pool hand out memory aligned to 8 bytes, which suits every Salam type but not data that needs 16 byte alignment.

A buffer that grows

The classic use of Reallocate is a buffer that does not know its final size. Keep the length and the capacity next to the pointer, and when the buffer is full ask for twice as much. Reallocate keeps the old contents, may move them to a new address, and works on a null pointer as well, so the first growth needs no special case.

mem-guide-buffer.salam
import mem

struct Buffer:
    pub data: u8* = null
    pub len: u64 = 0
    pub cap: u64 = 0
end

func append(b &: Buffer, byte: u8):
    if b.len == b.cap:
        mut next := b.cap * (2 as u64)
        if next == (0 as u64):
            next = 4 as u64
        end
        b.data = mem.Reallocate(b.data as void*, next) as u8*
        b.cap = next
        println "grew to", b.cap, "bytes"
    end
    b.data[b.len] = byte
    b.len++
end

func main:
    mut b := Buffer {}
    text := "Hello, arena and pool!"
    repeat text.Len() in i:
        append(b, text[i] as u8)
    end
    println "length:", b.len, "capacity:", b.cap
    mut sum := 0
    repeat b.len as int in i:
        sum += b.data[i] as int
    end
    println "byte sum:", sum
    mem.Free(b.data as void*)
end
Outputgrew to 4 bytes grew to 8 bytes grew to 16 bytes grew to 32 bytes length: 22 capacity: 32 byte sum: 1941

Doubling means 22 bytes cost only four reallocations, and a million bytes about twenty. Always store the pointer that Reallocate returns: the old one may no longer be valid. For most programs a Vector<u8> does exactly this for you.

An arena per request

An arena shines when many small objects live and die together, such as everything made while handling one request or parsing one line. Allocate from the arena while you work, then call ArenaReset once at the end instead of freeing each object. The memory is reused for the next round, so the program never asks the system for more.

mem-guide-arena.salam
import mem

struct Token:
    pub start: int = 0
    pub size: int = 0
end

func tokenize(a &: mem.Arena, line: str): int:
    mut count := 0
    mut i := 0
    until i < line.Len():
        if line[i] == ' ':
            i++
        else:
            t := mem.ArenaAlloc(a, sizeof(Token)) as Token*
            t[0] = Token { start = i }
            until i < line.Len() and line[i] != ' ':
                i++
            end
            t[0].size = i - t[0].start
            count++
        end
    end
    ret count
end

func main:
    mut arena := mem.NewArena(4096 as u64)
    lines := ["GET /index.html HTTP/1.1", "POST /api/orders HTTP/1.1", "DELETE /api/orders/7"]
    each line in lines:
        n := tokenize(arena, line)
        println n, "tokens,", mem.ArenaUsed(arena), "bytes used"
        mem.ArenaReset(arena)
    end
    println "after the last reset:", mem.ArenaUsed(arena), "bytes used of", mem.ArenaCapacity(arena)
    mem.ArenaFree(arena)
end
Output3 tokens, 24 bytes used 3 tokens, 24 bytes used 2 tokens, 16 bytes used after the last reset: 0 bytes used of 4096

Each allocation is rounded up to a multiple of 8 bytes, which is why one Token of two ints takes 8. ArenaAlloc returns null when the arena is full, so check the result or make the arena big enough for the largest round. After ArenaReset every pointer from the arena is stale; do not keep them across rounds.

A pool of fixed size blocks

A pool suits objects of one size that come and go in any order, such as the nodes of a list or a tree. PoolFree puts a block back on the pool's free list and the next PoolAlloc hands it out again, with no call to the system allocator either way. A pool has a fixed number of blocks; PoolAlloc returns null when they are all in use. PoolFree does not check its argument: a block freed twice goes on the free list twice and is later handed out to two owners.

mem-guide-pool.salam
import mem
import str

struct Node:
    pub value: int = 0
    pub next: Node* = null
end

func push(p &: mem.Pool, head: Node*, value: int): Node*:
    n := mem.PoolAlloc(p) as Node*
    if n == null:
        println "pool is full, dropping", value
        ret head
    end
    n[0] = Node { value = value, next = head }
    ret n
end

func pop(p &: mem.Pool, head: Node*): Node*:
    next := head[0].next
    mem.PoolFree(p, head as void*)
    ret next
end

func main:
    mut pool := mem.NewPool(sizeof(Node), 3 as u64)
    mut head := null as Node*
    repeat 1 to 4 in v:
        head = push(pool, head, v * 10)
    end
    println "top:", head[0].value
    head = pop(pool, head)
    head = push(pool, head, 99)
    mut out := ""
    until head != null:
        out = out + str.FromInt(head[0].value) + " "
        head = pop(pool, head)
    end
    println "stack:", out.Trim()
    mem.PoolDestroy(pool)
end
Outputpool is full, dropping 40 top: 30 stack: 99 20 10

Finding leaks

Build with -DSALAM_MEM_DEBUG and Allocate and Free start counting. CheckLeaks then prints the totals to standard error and warns if any bytes are still allocated. A normal build skips the counting and costs nothing.

mem-guide-leaks.salam
import mem

func make copy(text: str): u8*:
    n := text.Len() as u64
    p := mem.Allocate(n + (1 as u64)) as u8*
    repeat text.Len() in i:
        p[i] = text[i] as u8
    end
    p[text.Len()] = 0 as u8
    ret p
end

func main:
    a := make copy("first")
    b := make copy("second")
    mem.Free(a as void*)
    if mem.IsMemDebug():
        println "allocations:", mem.AllocCount(), "frees:", mem.FreeCount()
        println "bytes still allocated:", mem.LiveBytes()
    else:
        println "build with -DSALAM_MEM_DEBUG to count allocations"
    end
    mem.CheckLeaks()
    mem.Free(b as void*)
end
Outputbuild with -DSALAM_MEM_DEBUG to count allocations

With the flag, the same program reports the one buffer that was still allocated when CheckLeaks ran:

$ salam run -DSALAM_MEM_DEBUG mem-guide-leaks.salam
allocations: 2 frees: 1
bytes still allocated: 7
[salam memcheck] allocs=2 frees=1 live=7 peak=13
[WARNING] leak bytes=7

The counters see memory taken through this package, and also vector storage and many string operations, but not memory a C library takes with its own malloc. For that, salam memcheck file.salam builds with AddressSanitizer and reports each leak with the place it was allocated.

Which allocator for which job

SituationUseFree with
One block of any sizeAllocate, AllocateZeroedFree
An array of N itemsAllocateArray(n, sizeof(T))Free
A block that has to growReallocateFree
A block the program cannot go on withoutMustAllocate, MustAllocateZeroed, MustReallocateFree
Many small objects with one lifetimeNewArena and ArenaAllocArenaReset, then ArenaFree
Many objects of one size, freed in any orderNewPool and PoolAllocPoolFree, then PoolDestroy

Types

Arena

struct Arena
A memory arena.
NameTypeDescription
bufvoid*The address of the arena's memory.
capu64 = 0The capacity in bytes.
usedu64 = 0How much has been taken.
mem-Arena.salam
import mem

func main:
    mut arena := mem.NewArena(1024 as u64)
    println mem.ArenaCapacity(arena), mem.ArenaUsed(arena)
    a := mem.ArenaAlloc(arena, 100 as u64)
    b := mem.ArenaAllocZeroed(arena, 200 as u64)
    println a != null, b != null, mem.ArenaUsed(arena) >= 300, mem.ArenaRemaining(arena) <= 724
    println mem.ArenaAlloc(arena, 4000 as u64) == null
    mem.ArenaReset(arena)
    println mem.ArenaUsed(arena), arena.cap
    mem.ArenaFree(arena)
end
Output1024 0 true true true true true 0 1024

Pool

struct Pool
A pool of equally sized blocks.
NameTypeDescription
block_sizeu64 = 0The size of each block.
block_countu64 = 0The number of blocks.
blocksvoid*The address of the blocks' memory.
free_listvoid*The list of free blocks.
mem-Pool.salam
import mem

func main:
    mut pool := mem.NewPool(32 as u64, 4 as u64)
    println mem.PoolBlockSize(pool), mem.PoolCapacity(pool)
    b1 := mem.PoolAlloc(pool)
    b2 := mem.PoolAlloc(pool)
    println b1 != null, b2 != null, b1 != b2
    mem.PoolFree(pool, b1)
    b3 := mem.PoolAlloc(pool)
    println b3 == b1
    mem.PoolDestroy(pool)
end
Output32 4 true true true true

Functions

NewArena

func NewArena(capacity: u64): Arena
Builds an arena of the given capacity in bytes. If the memory cannot be had, every ArenaAlloc returns null.

The example for this item is shown with the ones above: mem-Arena.salam

ArenaAlloc

func ArenaAlloc(a &: Arena, size: u64): void*
Takes memory off the arena; the size is rounded up to a multiple of eight. It returns null when there is no room, or when the size is zero.

The example for this item is shown with the ones above: mem-Arena.salam

ArenaAllocZeroed

func ArenaAllocZeroed(a &: Arena, size: u64): void*
Like ArenaAlloc, with the memory zeroed.

The example for this item is shown with the ones above: mem-Arena.salam

ArenaReset

func ArenaReset(a &: Arena)
Takes back everything at once so the arena can be used again; every pointer it handed out is now stale.

The example for this item is shown with the ones above: mem-Arena.salam

ArenaFree

func ArenaFree(a &: Arena)
Releases the arena's memory.

The example for this item is shown with the ones above: mem-Arena.salam

ArenaUsed

func ArenaUsed(a &: Arena): u64
The bytes taken so far.

The example for this item is shown with the ones above: mem-Arena.salam

ArenaCapacity

func ArenaCapacity(a &: Arena): u64
The arena's capacity.

The example for this item is shown with the ones above: mem-Arena.salam

ArenaRemaining

func ArenaRemaining(a &: Arena): u64
The bytes left.

The example for this item is shown with the ones above: mem-Arena.salam

NewPool

func NewPool(block_size: u64, block_count: u64): Pool
Builds a pool of block_count blocks of block_size bytes, rounded up to a multiple of 8 and at least 8. If the memory cannot be had, the pool has no blocks.

The example for this item is shown with the ones above: mem-Pool.salam

PoolAlloc

func PoolAlloc(p &: Pool): void*
Hands out a free block, or null when none is left.

The example for this item is shown with the ones above: mem-Pool.salam

PoolFree

func PoolFree(p &: Pool, ptr: void*)
Gives a block back to the pool; the next allocation hands out the same one. It does not check that the block came from this pool or is not already free.

The example for this item is shown with the ones above: mem-Pool.salam

PoolBlockSize

func PoolBlockSize(p &: Pool): u64
The block size.

The example for this item is shown with the ones above: mem-Pool.salam

PoolCapacity

func PoolCapacity(p &: Pool): u64
The total number of blocks.

The example for this item is shown with the ones above: mem-Pool.salam

PoolDestroy

func PoolDestroy(p &: Pool)
Releases the pool's memory.

The example for this item is shown with the ones above: mem-Pool.salam

Allocate

func Allocate(size: u64): void*
Takes a block of the given size in bytes, or returns null when there is no memory. Its contents are undefined.
mem-Allocate.salam
import mem

func main:
    b := mem.Allocate(8 as u64)
    mem.Set(b, 0, 8 as u64)
    bytes := b as i8*
    bytes[0] = 65 as i8
    bytes[1] = 66 as i8
    b2 := mem.AllocateZeroed(8 as u64)
    mem.Copy(b2, b, 2 as u64)
    bytes2 := b2 as i8*
    println bytes2[0], bytes2[1], bytes2[2]
    mem.MemMove(b, (b as i64 + 1) as void*, 1 as u64)
    println bytes[0]
    b3 := mem.Reallocate(b, 64 as u64)
    arr := mem.AllocateArray(4 as u64, 8 as u64)
    arr64 := arr as i64*
    println arr64[3]
    mem.Free(b3)
    mem.Free(b2)
    mem.Free(arr)
end
Output65 66 0 66 0

Reallocate

func Reallocate(ptr: void*, size: u64): void*
Changes the size of a block and keeps its contents; it may return a new address, and on a null pointer it allocates. Store the result: the old pointer may be invalid, and on failure it returns null and the old block stays yours to free.

The example for this item is shown with the ones above: mem-Allocate.salam

Free

func Free(ptr: void*)
Gives back a block from Allocate, Reallocate or the zeroed forms. Null is ignored.

The example for this item is shown with the ones above: mem-Allocate.salam

Set

func Set(ptr: void*, value: int, n: u64)
Fills n bytes with the given value.

The example for this item is shown with the ones above: mem-Allocate.salam

Copy

func Copy(dst: void*, src: void*, n: u64)
Copies n bytes from src to dst; the two ranges must not overlap.

The example for this item is shown with the ones above: mem-Allocate.salam

MemMove

func MemMove(dst: void*, src: void*, n: u64): void*
Like Copy, but correct even when the ranges overlap.

The example for this item is shown with the ones above: mem-Allocate.salam

AllocateZeroed

func AllocateZeroed(size: u64): void*
Takes zeroed memory.

The example for this item is shown with the ones above: mem-Allocate.salam

OutOfMemory

func OutOfMemory()
Flushes standard output, prints salam: out of memory and aborts. For a program that checks a null result itself and has no way to go on.
mem-Must.salam
import mem

func main:
    a := mem.MustAllocate(8 as u64) as i64*
    a[0] = 7
    println a[0]
    b := mem.MustAllocateZeroed(8 as u64) as i64*
    println b[0]
    grown := mem.MustReallocate(a as void*, 64 as u64)
    held := mem.Allocate(16 as u64)
    if held == null:
        mem.OutOfMemory()
    end
    mem.Free(held)
    mem.Free(grown)
    mem.Free(b as void*)
end

MustAllocate

func MustAllocate(size: u64): void*
Like Allocate, but when the memory cannot be had it flushes standard output, prints salam: out of memory and aborts instead of returning null. Vector, HashMap, strings, dyn boxes and closures fail the same way.

The example for this item is shown with the ones above: mem-Must.salam

MustAllocateZeroed

func MustAllocateZeroed(size: u64): void*
Like AllocateZeroed, but aborts with the same message instead of returning null.

The example for this item is shown with the ones above: mem-Must.salam

MustReallocate

func MustReallocate(ptr: void*, size: u64): void*
Like Reallocate, but aborts with the same message instead of returning null. A size of zero is not a failure.

The example for this item is shown with the ones above: mem-Must.salam

AllocateArray

func AllocateArray(count: u64, size: u64): void*
Takes zeroed memory for count elements of size bytes each. Returns null when either is zero or the product does not fit in 64 bits.

The example for this item is shown with the ones above: mem-Allocate.salam

AllocCount

func AllocCount(): i64
The number of allocations; zero unless the program was built with memory debugging.
mem-Debug.salam
import mem

func main:
    println mem.IsMemDebug(), mem.IsAsanActive(), mem.MemDebugActive()
    println mem.AllocCount(), mem.FreeCount(), mem.LiveBytes(), mem.PeakBytes()
    mem.CheckLeaks()
end
Outputfalse false false 0 0 0 0

FreeCount

func FreeCount(): i64
The number of frees; only with memory debugging.

The example for this item is shown with the ones above: mem-Debug.salam

LiveBytes

func LiveBytes(): i64
The bytes taken and not yet given back; zero unless the program was built with memory debugging.

The example for this item is shown with the ones above: mem-Debug.salam

PeakBytes

func PeakBytes(): i64
The most memory held at one moment; only with memory debugging.

The example for this item is shown with the ones above: mem-Debug.salam

IsMemDebug

func IsMemDebug(): bool
True when the program was built with allocation counting.

The example for this item is shown with the ones above: mem-Debug.salam

IsAsanActive

func IsAsanActive(): bool
True when the program was built with the ASan checker.

The example for this item is shown with the ones above: mem-Debug.salam

MemDebugActive

func MemDebugActive(): bool
True when either memory checker is on.

The example for this item is shown with the ones above: mem-Debug.salam

CheckLeaks

func CheckLeaks()
Prints the counters to standard error and warns about bytes never given back; call it at the end of the program. Without memory debugging it prints nothing, and under ASan the report comes at exit.

The example for this item is shown with the ones above: mem-Debug.salam