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,ReallocateandFree: 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,ArenaResetorPoolFreecorrupts memory without an error message.salam memcheckfinds these for blocks fromAllocate, but not inside an arena or a pool, which are one block to it. - Give memory back the way it was taken:
mem.FreeforAllocate, the C library's own function for what a C library returns. In a-DSALAM_MEM_DEBUGbuild every block fromAllocatehas a hidden 8 byte header, so mixing the two crashes there even when a normal build seems fine. - Check for
null.Allocate,ArenaAllocandPoolAllocall 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.
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*)
endDoubling 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.
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)
endEach 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.
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)
endFinding 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.
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*)
endWith 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
| Situation | Use | Free with |
|---|---|---|
| One block of any size | Allocate, AllocateZeroed | Free |
| An array of N items | AllocateArray(n, sizeof(T)) | Free |
| A block that has to grow | Reallocate | Free |
| A block the program cannot go on without | MustAllocate, MustAllocateZeroed, MustReallocate | Free |
| Many small objects with one lifetime | NewArena and ArenaAlloc | ArenaReset, then ArenaFree |
| Many objects of one size, freed in any order | NewPool and PoolAlloc | PoolFree, then PoolDestroy |
Types
Arena
struct Arena| Name | Type | Description |
|---|---|---|
buf | void* | The address of the arena's memory. |
cap | u64 = 0 | The capacity in bytes. |
used | u64 = 0 | How much has been taken. |
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)
endPool
struct Pool| Name | Type | Description |
|---|---|---|
block_size | u64 = 0 | The size of each block. |
block_count | u64 = 0 | The number of blocks. |
blocks | void* | The address of the blocks' memory. |
free_list | void* | The list of free blocks. |
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)
endFunctions
NewArena
func NewArena(capacity: u64): ArenaArenaAlloc returns null.The example for this item is shown with the ones above: mem-Arena.salam
ArenaAlloc
func ArenaAlloc(a &: Arena, size: u64): void*The example for this item is shown with the ones above: mem-Arena.salam
ArenaAllocZeroed
func ArenaAllocZeroed(a &: Arena, size: u64): void*ArenaAlloc, with the memory zeroed.The example for this item is shown with the ones above: mem-Arena.salam
ArenaReset
func ArenaReset(a &: Arena)The example for this item is shown with the ones above: mem-Arena.salam
ArenaFree
func ArenaFree(a &: Arena)The example for this item is shown with the ones above: mem-Arena.salam
ArenaUsed
func ArenaUsed(a &: Arena): u64The example for this item is shown with the ones above: mem-Arena.salam
ArenaCapacity
func ArenaCapacity(a &: Arena): u64The example for this item is shown with the ones above: mem-Arena.salam
ArenaRemaining
func ArenaRemaining(a &: Arena): u64The example for this item is shown with the ones above: mem-Arena.salam
NewPool
func NewPool(block_size: u64, block_count: u64): Poolblock_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*The example for this item is shown with the ones above: mem-Pool.salam
PoolFree
func PoolFree(p &: Pool, ptr: void*)The example for this item is shown with the ones above: mem-Pool.salam
PoolBlockSize
func PoolBlockSize(p &: Pool): u64The example for this item is shown with the ones above: mem-Pool.salam
PoolCapacity
func PoolCapacity(p &: Pool): u64The example for this item is shown with the ones above: mem-Pool.salam
PoolDestroy
func PoolDestroy(p &: Pool)The example for this item is shown with the ones above: mem-Pool.salam
Allocate
func Allocate(size: u64): void*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)
endReallocate
func Reallocate(ptr: void*, size: u64): void*The example for this item is shown with the ones above: mem-Allocate.salam
Free
func Free(ptr: void*)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)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)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*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*The example for this item is shown with the ones above: mem-Allocate.salam
OutOfMemory
func OutOfMemory()salam: out of memory and aborts. For a program that checks a null result itself and has no way to go on.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*)
endMustAllocate
func MustAllocate(size: u64): void*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*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*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*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(): i64import mem
func main:
println mem.IsMemDebug(), mem.IsAsanActive(), mem.MemDebugActive()
println mem.AllocCount(), mem.FreeCount(), mem.LiveBytes(), mem.PeakBytes()
mem.CheckLeaks()
endFreeCount
func FreeCount(): i64The example for this item is shown with the ones above: mem-Debug.salam
LiveBytes
func LiveBytes(): i64The example for this item is shown with the ones above: mem-Debug.salam
PeakBytes
func PeakBytes(): i64The example for this item is shown with the ones above: mem-Debug.salam
IsMemDebug
func IsMemDebug(): boolThe example for this item is shown with the ones above: mem-Debug.salam
IsAsanActive
func IsAsanActive(): boolThe example for this item is shown with the ones above: mem-Debug.salam
MemDebugActive
func MemDebugActive(): boolThe example for this item is shown with the ones above: mem-Debug.salam
CheckLeaks
func CheckLeaks()The example for this item is shown with the ones above: mem-Debug.salam