Skip to main content

Memory Management

Raml provides manual memory management with heap allocation, pointer types, and explicit deallocation. There is no garbage collector.


Overview​

This section covers the core concepts you need to allocate, point, and free memory in Raml.

Allocation with make​

Stack allocation (default):

node:
value
bs# next

:start:
n = make node 42 // stack-allocated, zero-initialized, then value=42

make objectName args zero-initializes all fields, then assigns positional arguments to fields in order.

Heap allocation with auto:

n = make node 42 auto // heap-allocated via raml_alloc()

The auto keyword marks the allocation for the heap. The returned value is a pointer to heap memory.

Empty initialization (no constructor args):

rpt = make report // zero-initialized, all fields = 0

Pointer Types​

TypeSyntaxExample
Bitstream pointerbs#bs# p = @x
Object pointername#node# np = @n

Core Operations​

OperationSyntaxWhat It Does
Address-of@varGet the memory address of a variable
Dereference#ptrRead the value at a pointer address
Address assignptr #= @varChange what a pointer points to
Address equalityp =#= qCompare two pointers (1 if same address)
Element stepptr += nAdvance pointer by n × sizeof(element)
Bit stepptr +#= nAdvance pointer by n raw bits
Freefree varRelease heap-allocated memory

Safety Notes​

  • No garbage collection: All heap allocations must be explicitly freed.
  • Use-after-free: Accessing memory after free is undefined behavior.
  • Stack vs heap: Stack allocations auto-clean on scope exit; heap allocations persist until free.
  • Pointer validity: The compiler does not check pointer validity at compile time.

Deep Dive​

This section covers the internals — memory layout, codegen mapping, pointer arithmetic details, and edge cases.

Memory Model​

Raml's memory model is a direct mapping to C primitives:

Stack: Local variables, struct instances (without auto)
→ Allocated as C local variables on the call stack
→ Lifetime: scope of the declaring block
→ Size: determined at compile time from struct layout

Heap: Struct instances (with auto)
→ Allocated via raml_alloc() (wrapper around malloc)
→ Lifetime: until free() is called
→ Size: sizeof(struct_T_t) determined at compile time

Globals: Top-level variables (not in any block)
→ Allocated as C global variables
→ Lifetime: entire program execution

C Codegen Mapping​

Raml OperationC Output
make T argsstruct T_t var = { .field1 = arg1, ... };
make T args autostruct T_t* var = raml_alloc(sizeof(struct T_t)); var->field1 = arg1; ...
@var&var
#ptr*ptr
ptr #= @varptr = &var
p =#= qp == q
ptr += nptr += n
ptr +#= n(void*)((char*)ptr + n)
free varraml_free(var)
node:fieldnode.field (direct access)
node#:fieldnode->field (pointer access)

Field Access Through Pointers​

When accessing object fields through a pointer, the codegen automatically uses -> instead of .:

node# np = @n
np:value // generates np->value

Chained access works with nested pointers:

np:next:value // follows pointer chain (np->next->value)

Pointer Arithmetic: Element Step vs Bit Step​

The two pointer arithmetic operators differ in how they calculate offsets:

ptr += n (Element-Size Step): Advances the pointer by n × sizeof(*ptr). This is standard C pointer arithmetic. When ptr is a bs# (bitstream pointer), the element size is 1 byte (since bs# maps to uint8_t*).

bs# p = @arr // p points to first element
p += 1 // advance by sizeof(uint8_t) = 1 byte

ptr +#= n (Raw Bit Offset): Advances the pointer by n raw bytes (not scaled by element size). This is implemented as pointer arithmetic on void*:

// C equivalent:
ptr = (typeof(ptr))((void*)((char*)ptr + n))

This is useful for bit-level data structure traversal where you want byte-level control regardless of the underlying type.

Lifetime and Ownership Rules​

The borrow checker (analysis/borrow.py) enforces these rules at compile time:

  1. Heap allocations must be freed: Every make ... auto must have a matching free on all control flow paths.
  2. No double-free: free on an already-freed pointer is a compile-time error.
  3. No use-after-free: Reading or writing through a pointer after its referent has been freed is a compile-time error.
  4. Stack references must not escape: A pointer to a stack-allocated variable (@local_var) cannot be returned from a function or assigned to a longer-lived variable.
  5. Pointer provenance: A bs# pointer can only be dereferenced if it points to valid, live memory.

Heap Allocation Internals​

raml_alloc and raml_free are thin wrappers:

void* raml_alloc(size_t size) {
void* ptr = calloc(1, size); // zero-initialized
if (!ptr) {
fprintf(stderr, "Raml runtime error: allocation failed\n");
exit(1);
}
return ptr;
}

void raml_free(void* ptr) {
free(ptr);
}

The calloc ensures zero-initialization, matching Raml's semantics that make always zeroes fields before assigning constructor args.

Stack Allocation Internals​

Without auto, make T args generates:

struct T_t var = {0}; // zero-initialize
var.field1 = arg1; // positional assignment
var.field2 = arg2;
// ...

The struct is a local variable, so it is automatically reclaimed when the enclosing block exits.

Alignment in Struct Layout​

Struct fields are laid out sequentially with C ABI alignment rules. The codegen computes field offsets based on their C type sizes:

Field Width (bits)C TypeAlignmentOffset Multiple
0–8uint8_t1 byte1
9–16uint16_t2 bytes2
17–32uint32_t4 bytes4
33–64uint64_t8 bytes8

The struct's total alignment is the maximum alignment of any field.

Edge Cases​

  • free as leading declaration: free n1 n2 n3 frees multiple allocations in one statement.
  • free on non-heap memory: Freeing a stack-allocated variable is a compile-time error caught by the borrow checker.
  • Dangling pointer dereference: Not caught at compile time if the pointer was obtained before the free. Results in undefined behavior at runtime.
  • Null pointers: bs# p = 0 creates a null pointer. Dereferencing it triggers a runtime crash.