Last updated: 2026-11-15
Inside a Compiled PatLang 2.0 Program
For new readers
This page describes what v2.exe produces: how a value is laid out in memory, how functions call each other, how memory is counted and freed without the program ever freeing anything, how a crash inside a world unwinds cleanly, and how threads allocate without locks. None of it is visible to a PatLang program except through speed and memory use, but it is what the language's promises in Part 1 of the specification rest on, and it explains why compiled v2 code behaves as it does.
The rules are Part 2 of the values-and-memory specification and the executable section of the IR specification. Every runtime function named here is PatLang source in self_hosting/v2/runtime/, compiled into the program by the same stages as the program's own code. The compiler holds no list of facts about any runtime function by name; whatever it knows about one, it derives from that function's source.the runtime is just more PatLang code
A value is two words FoundationalKnowledge that endures for decades โ core principles
Every value is two machine words. The type word holds the class and some flags; the data word holds the full 64-bit payload: an int's bits, a float's IEEE bits, a bool or unit, or a pointer to a heap block for anything larger. The type is never stored in the data word, so an int uses all 64 bits and no address range or tag pattern is needed to tell one kind of value from another.tag bits let you read the type fast
| Bits of the type word | Meaning |
|---|---|
| 0โ31 | The class id |
| 32 | The heap bit: the data word points to a counted heap block |
| 33 | Reserved for per-value metadata; nothing uses it yet |
| Id | Class | Id | Class |
|---|---|---|---|
| 0 | unit | 8 | string |
| 1 | bool | 9 | list |
| 2 | int | 10 | closure |
| 3 | float | 11 | string_builder |
| 4 | bigint | 12 | vec |
| 5 | rational | 13 | bool_array |
| 6 | complex | 14 | rule_store |
| 7 | interval | 15 | modint |
Id 16 is the unwinding mark, which no value has. Classes a program declares get ids from 64 up, named in the class table.
v1 packed a value's type into the top 16 bits of one word. That held immediate integers to 48 bits, split floats into raw and boxed forms, and needed an address-range test to tell a string literal from a heap string. Two words cost twice the memory per list slot and argument; the design review accepted that cost to remove a whole family of special cases.
A list slot, an argument and a result are each a two-word value. A heap block is a 16-byte header, [count:8][size:8], then its payload. The block records its own size, so freeing it never recomputes the size from the contents: v1 once freed a trimmed bigint into the wrong size class for that reason. A list's block holds its length and its room after the header, and its elements from offset 32, 16 bytes each. A string literal is laid out like a string block but with the heap bit clear, so it is never counted.
Calls Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
- Before a call, the caller pushes each argument's data word and then its type word, from the last argument to the first, and removes them afterwards. Inside the function, parameter i's type word is at
[rbp+16+16i]and its data word at[rbp+24+16i]. - A function returns its result's type word in
raxand its data word inrdx. - Calls to the operating system use the Windows x64 convention, through
extern_call(dll, function, args...), orextern_call_floatfor C functions taking and returning doubles. - A closure is a heap block holding its code address at offset 16, its parameter count at 32, whether its last parameter is
restat 40, and its captured values from 48. A closure call whose argument count matches, with norest, calls the code directly; any other goes through a runtime routine that fits the arguments as a named call would, or stops the program.
Ownership: five rules FoundationalKnowledge that endures for decades โ core principles
The language says no program frees memory and none can observe when memory is freed. The runtime meets that with reference counts, applied by five rules, and the specification says there are no others:
- A call borrows its arguments and returns a value its caller owns.
- A local owns the value a call or a literal gave it. A copy of a local into another takes its own reference.
- A structure (list, object, cell, rational, complex, interval) owns each value it holds, and releases each when it is freed or a slot is overwritten.
- A heap block is freed when its last reference is released. Freeing it releases what it holds.
- A value with no heap block (int, float, bool, unit) has nothing to count, and its type word says so, so the data word need not be tested. Where the compiler can see that a slot only ever holds such a value, because every write to it is a literal, a machine word or a copy of another such slot, it does not test the type word either.
The ownership stage, own.patlang, applies these rules to each function's IR and inserts retain and release instructions. Nothing else in the compiler counts references. The result for each function is recorded as its summary: its arity, which parameters it borrows, and that its result is owned. A caller is compiled against its callee's summary, never its body, which is what lets the compiler cache each function separately (see The swarm compiler).caching by summary enables parallel compilation
A few consequences of the rules show up in practice:
- A count of 1 means sole ownership. A variable passed to a call goes through a temporary that takes its own reference, released after the call. So a count of 1 inside the callee means nothing else holds the value, and
list_pushandlist_setchange a list in place, and only then. The count has to be read straight from the parameter's block, since passing it to a helper adds a reference. - Giving a value to a call. In
let l = list_push(l, x)the lowering givesl's value to the call, so building a list is amortised O(1). Every argument is evaluated before the value is given, so another argument may read the list. An earlier version did not give it when another argument mentioned it, and 16,000 pushes of that shape took 2,574 milliseconds; they take 3 now. - A temporary nothing reads is released when it is made, so an overwritten field's old value does not outlive the overwrite.
- Counting inline. The generated code counts with a locked exchange-add and calls the runtime only at the last reference.
Reference counts are atomic. Making them plain where a summary proves a value never leaves its thread is an allowed optimisation, not yet made.
Unwinding a stop Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
A stop inside a world_call ends the frames between it and the call, and those frames release what they own, by the same five rules:
- The stop returns the unwinding mark, a value whose type word is 16, a class no value has, so a program never holds it.
- After each call, and each operator, list or closure step that may run program code, the compiled code compares the result's type word with 16. On the mark, the function releases every slot it owns at that point and returns the mark in turn. Every slot starts as unit when the function is entered, so each holds a value of its own or unit, and releasing all of them is always safe.
- The mark stops at a call written
caught(f(...)), which gives it as its value. Only the runtime writescaught, where a world call, a fiber or a thread begins, and where the interpreter gives back an interpreted frame.
caught(...)"] --> F["f"] F --> G["g"] G --> H["h: contract fails"] H -. "returns the mark
(type word 16)" .-> G2["g: result is the mark?
release own slots, return mark"] G2 -. mark .-> F2["f: release own slots, return mark"] F2 -. mark .-> WC2["caught: gives [stopped, 3]"] WC2 --> GO(["the caller goes on"])
A function that makes no call that may give the mark has no unwind code, and a test costs one compare. The change made the compiler itself 9.6% larger, from 18.3 to 20.0 MB, with no change in how long it takes to build itself.
The memory manager Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
- The heap reserves one address range of 64 GB at start, and commits pages from the system in steps of 256 MB, only as allocation passes the committed mark. Freed memory is never returned to the system.
- A block's size is rounded up to a size class: 8-byte steps up to 256 bytes, then four classes per power of two.
- Each thread has a context of its own, found through a thread-local slot, holding a 1 MB bump chunk taken from the reservation and a free list for each size class. A thread allocates from, and frees to, its own lists with no lock and no atomic operation.
- A block freed by another thread goes onto the freeing thread's lists. When one of a thread's lists grows past 256 blocks, half of it goes to a shared pool, and an empty list takes a batch from the pool before taking new memory. The pool's lock is taken once per batch, never per block: a thread reusing another's 2,000 freed blocks takes it 14 times.
- When a chunk is replaced or its thread ends, the unused end of the chunk becomes free blocks, so no memory is lost.
The same thread context holds the thread's list of running event handlers (swapped in and out by each fiber), its fibers, a word for system calls to write counts into, a 64-byte buffer for formatting numbers, and the world its code runs in. The runtime's shared state is 65,536 bytes at a fixed address, runtime_state(), laid out field by field in the runtime's source.
Operators in machine code Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
a + b compiles to an inline fast path under a condition, and a method call otherwise. When both type words are int, and no handler is registered for +'s events, it is a machine add, calling the runtime's op_add on overflow, which gives a bigint. Otherwise it calls the left operand's method, which raises its declared events. The other arithmetic, comparison and bit operators are inline for two ints in the same way, except /, which may give a rational and is never inline. A program with no handler for added or added_to is compiled with the event test left out altogether.
Contracts in every build FoundationalKnowledge that endures for decades โ core principles
Every runtime function and every compiler stage states its contract with require and ensure: its ownership behaviour and its representation invariants. rt_live(v), the contract for a parameter that may be any value, rests on the value_live primitive, which checks that no type-word bit above 33 is set, that the class is a runtime class or a declared one, and that a heap value's block has a count of at least 1. A broken contract stops the program at the call that broke it, naming the contract, where before it showed up later and elsewhere as a leak or a double release.the contract syntax lives here
Contract checks run in every build. That policy is one setting, read in one place, contracts.patlang, and no contract and no other part of the compiler or runtime depends on it, so turning checks off for some builds later is a change to that file alone. The IR has a contract of its own, ir_well_formed: every jump has its label, every slot is written before it is read, and retain and release appear only after the ownership stage. Each stage requires it of its input and ensures it of its output.
The executable Applied / MethodologicalKnowledge with a 5โ10 year half-life โ stable practice
- The entry calls
runtime_init(), then__main(), the program's top level, then exits the process with code 0. - The thread entry receives a job in
rcxby the Windows convention, callsrt_thread_main(job)and returns 0. - The file is a PE32+ console executable importing each external function by name, with a 256 MB stack reserve committed a page at a time. A frame longer than a page touches each page on the way down; before that, a function with a long frame crashed at start when its first write fell past the guard page.
- Beside it a build writes
OUT.asm,OUT.facts(the program facts: events handled, functions reached by name, rules),OUT.ledger(each function and whether it was built or reused) andOUT.timing. A build of a program that declaresjb_compiler_key, as the compiler does, also writesOUT.key.
Where the time goes Ephemeral / ToolingKnowledge that evolves in months to a year โ check for updates
Inline counting, a primitive for the liveness test, and slots held across a function took a list read l[3] from 1,880 to 245 nanoseconds or less, and an allocation with its free from 3 microseconds to under 1. Small ints no longer go through bigint limbs, which took 10 / 2 from 90 milliseconds to 50 microseconds in one early measurement. What remains is mostly the shape of the generated code: every temporary goes to the stack, every reference count is an atomic add, and contracts are checked as it runs. A word operation inside the modint routines costs about 15 nanoseconds.
See also
The v2 IR and its readers specifies the instructions this code is generated from. Blocks, ownership and memory tells how the design review arrived at these rules. What the language promises about memory gives the promises this page implements.
Graduate Attributes
Modelled on this page
- Subject Specialist: Technical specifications for memory layout and reference counting are presented with precise numerical constraints and structural definitions.
- Critical Thinker: Design choices are justified by comparing performance metrics and memory costs against previous implementations.
- Researcher: The derivation of compiler behaviour from source code rather than hardcoded facts is explicitly documented as a methodological principle.
University of Reading Graduate Attributes framework.