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
| Type | Syntax | Example |
|---|---|---|
| Bitstream pointer | bs# | bs# p = @x |
| Object pointer | name# | node# np = @n |
Core Operations
| Operation | Syntax | What It Does |
|---|---|---|
| Address-of | @var | Get the memory address of a variable |
| Dereference | #ptr | Read the value at a pointer address |
| Address assign | ptr #= @var | Change what a pointer points to |
| Address equality | p =#= q | Compare two pointers (1 if same address) |
| Element step | ptr += n | Advance pointer by n × sizeof(element) |
| Bit step | ptr +#= n | Advance pointer by n raw bits |
| Free | free var | Release heap-allocated memory |
Safety Notes
- No garbage collection: All heap allocations must be explicitly freed.
- Use-after-free: Accessing memory after
freeis 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 Operation | C Output |
|---|---|
make T args | struct T_t var = { .field1 = arg1, ... }; |
make T args auto | struct T_t* var = raml_alloc(sizeof(struct T_t)); var->field1 = arg1; ... |
@var | &var |
#ptr | *ptr |
ptr #= @var | ptr = &var |
p =#= q | p == q |
ptr += n | ptr += n |
ptr +#= n | (void*)((char*)ptr + n) |
free var | raml_free(var) |
node:field | node.field (direct access) |
node#:field | node->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:
- Heap allocations must be freed: Every
make ... automust have a matchingfreeon all control flow paths. - No double-free:
freeon an already-freed pointer is a compile-time error. - No use-after-free: Reading or writing through a pointer after its referent has been freed is a compile-time error.
- 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. - 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 Type | Alignment | Offset Multiple |
|---|---|---|---|
| 0–8 | uint8_t | 1 byte | 1 |
| 9–16 | uint16_t | 2 bytes | 2 |
| 17–32 | uint32_t | 4 bytes | 4 |
| 33–64 | uint64_t | 8 bytes | 8 |
The struct's total alignment is the maximum alignment of any field.
Edge Cases
freeas leading declaration:free n1 n2 n3frees multiple allocations in one statement.freeon 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 = 0creates a null pointer. Dereferencing it triggers a runtime crash.