The Burn VM

#Values and the runtime library

#Type ids

Every module starts with twelve built-in types. The types it declares are numbered from 12 on.

Runtime functions that have to understand a value take its static type id as an extra argument. For example to_str takes the value and its type, so const 3; rt to_str formats an int and const 11; rt to_str formats an [int] array.

#Heap objects

Heap objects start with a 16-byte header: kind (1 byte), cycle collector color, flags, element kind, type id (4 bytes), size in bytes (4 bytes) and reference count (4 bytes). After the header:

The sized number types (int8, uint8, int16, uint16, int32, uint32, uint64, float32) are written int8 ... float32 in bvm assembly. On the stack they are 64-bit words like every other value: integers are sign- or zero-extended and float32 values are doubles rounded to single precision. Arrays whose element type is one of the packed types (all of them except uint64) store each element in 1, 2 or 4 bytes; the element kind byte in the header says which, and index, setindex and the array runtime functions convert between the packed bytes and 64-bit words.

Values of type any are boxes (or the object itself when it is already on the heap). rt box v tid creates one and unbox reads it. rt is_type, rt cast and rt type_name inspect it.

#Reference counting

Objects are reference counted. A new object has a count of 1, owned by whoever created it: the result of rt functions, newarr, new and calls is owned by the code that receives it. rt retain v adds an owner and returns v, rt release v removes one and frees the object when none is left, releasing what it holds. Both ignore null and strings from the module's string pool, which are static.

Containers own their contents: newarr and new take ownership of the values they are built from, and rt functions that store a value (arr_push, arr_set, map_set, box, ...) add their own owner, so the caller still releases its copy. index, getfield and unbox read without adding an owner. Burn generates these instructions itself; another language on bvm must do the same, or its objects are never freed.

Objects that only refer to each other are found by a cycle collector, which runs when enough memory has been allocated (BURN_GC_THRESHOLD, 32 MB by default; BURN_GC_STATS=1 prints a line each time) and never while spawned threads are running. While threads run, counts are updated atomically.

#Runtime functions

rt name pops the function's arguments (the first argument is deepest on the stack) and pushes its result. Functions without a meaningful result return 0, so pop it. bvm runtime prints every name with its argument count. The most useful ones:

#Written in Burn

The whole runtime is written in Burn, in lib/rt/ of the Burn repository: memory and values, reference counting and the cycle collector, strings, arrays, maps, records, printing and number formatting, files, processes, the network, JSON, time and tasks. It calls the C library through @Extern and works on raw memory in unsafe code (std/memory). Each runtime function is a Burn function with a C name:

@Extern("burn_str_split")
pub unsafe fun strSplit(s: int, sep: int): int {
    ...
}

The same code is compiled into the toolchain, where rt str_split calls burn_str_split directly, and into libburn_runtime.a, which native executables link, so a program behaves the same on bvm and as an executable. A runtime function raises a runtime error that points at loc, the place in the program that called it, as in str_index, arr_get and fail below.

#Text and output

#Arrays and maps

#Everything else