Documentation

Efficient mapping for record field names

The shape of a record: which fields it has, and where each one sits in a record value's slots.

One of these is built per record-construction site and is carried by every value built there. Reaching it from the value is what lets Eq and compareClosure -- which are pure, with no access to the code cache -- order two records of *different* shapes by field name. That case is reachable: two records with different fields can be compared once they are wrapped in Any, which erases their types.

A shape from its reference, its field names ascending, and the number of each field in that order (so the field at slot i has number refs !! i).

The slot of a field in a record of this shape: a binary search of shapeKeys. A field the shape lacks is an error, not a result: typechecked code only reads fields the record has, so there is nothing to recover from, and nothing to allocate on the way out.

Build the shape for a record schema, assigning a FieldRef to any field name not yet seen.

Build the shape for a record schema from already-interned field names. Returns Nothing if any of them is unknown, which shouldn't happen for a schema that is itself already interned.

What a let body's combinator knows about the frame it is resumed over: the wide variables of the frame, each as (the index of its value slot from the top of the frame, its width in slots), in increasing order; and, for a section the explosion rewrote, the frames the unoptimized code has at this point, for a continuation written out (Deopt).

The slots a frame layout adds over one per variable, for a frame that holds n variables. A section inside a let's binding lists the wide variables of the enclosing frames too, below its own slots (wideSlots walks the whole context), and those are not this frame's: a wide variable at wide index i is the frame's when its narrow index, i less the padding of the wide variables above it, is below n. (Until 2026-11-02 every listed variable counted, so a frame inside a binding with a wide variable in the enclosing frame came up short.)

The same for a frame of f slots, wide.

How a continuation's frame for a section the explosion rewrote is written out as the frames the unoptimized code has at that point (design.md, "Continuations across processes"; built by deoptOf, applied by deoptCont). The frames come innermost first, each as the index of the unoptimized section it resumes, in the group, and its slots from the top; a let whose binding the rewrite moved into the enclosing frame (sinkCalls) gives two, the binding's and the let's, and the optimized frame's pending arguments go with the last. A slot is copied from the optimized frames, by frame (0 this one, 1 the enclosing let's, counting the continuation's Push frames outward) and narrowed index from the top, or is a product the optimized code no longer holds, packed from such slots, or is dead, a slot the unoptimized code never reads there, written as unit.

A native code cell (see unison-runtimesrcUnisonRuntimeJIT/design.md): the mutable part of a combinator, 40 bytes outside the Haskell heap, never moved and never freed, so generated code can refer to it by address. As a C struct:

struct cell {
  void    *code;    // offset 0: the compiled entry point, NULL until compiled
  int64_t  count;   // offset 8: calls made while code was NULL
  int64_t  state;   // offset 16: 0 not yet requested, 1 queued, 2 taken by the compile thread
  int64_t  verdict; // offset 24: whether it is worth compiling (see readNativeVerdict)
  void    *entry;   // offset 32: the register entry, for native callers in other modules
};

The state only moves forward, so a combinator is asked for only once. The layout is a contract between two readers: this module (the and accessors below, at those offsets) and the generated code, which loads at offset 0 or at offset 32 to call through a cell and writes @ at offset 8 (JIT/Codegen.hs); nothing in the C runtime reads a cell. The register entry is a function with the signature native code agrees on across modules for the combinator's arity (design.md, "The register entry"): null when the combinator is not compiled, or compiled without a worker.

The count starts at minus the JIT's compilation threshold when the JIT compiles what gets hot, so that "hot" is the count reaching zero: the interpreter's test is one comparison with a constant. A count that starts at zero or above never gets there.

Reads the compiled code pointer of a cell. Null means "interpret". An atomic (acquire) load: the compile thread writes a module's pool entries and exit and frame tables before it publishes the code pointer, and an interpreter thread that sees the pointer must then see those too, which on a weakly ordered machine (arm64) a plain load does not promise (an ldar, a few cycles on an entry that costs tens of nanoseconds).

The compiled code the interpreter should enter, if any. Null means "interpret": there is no code, or the function is so small that getting into native code and back costs more than interpreting it (verdict 3; native callers still call it directly).

Installs compiled code. A single atomic (release) pointer write: readers on other threads see either the old value or the new one, and a reader that sees the new one sees everything the compile thread wrote before it (see readNativeCode).

Counts a call made while the cell had no compiled code, and says whether that made it hot (the count reached zero). Not atomic; a lost count under contention does not matter.

Sets a cell's count: negative, to make it hot after that many more calls.

Marks the cell as requested (state 0 to 1), atomically, and says whether this call was the one that did. Whoever does owns the request, and queues it.

The offset of the register entry in a cell, for the generated code.

Installs the register entry (null for none), the same way as the code pointer; written before the code pointer, so that a thread which sees the code sees the entry.

Puts the state back to 0: for a request that could not be queued.

The compile thread takes the cell (state 2), whether it was requested or not, and says whether this call was the one that did. A combinator that is taken is being compiled, or has been, or can't be. A request found already taken when it comes off the queue is dropped: its combinator went into an earlier batch.

Whether a request for the cell is queued.

What the JIT has decided about compiling the cell's combinator. Zero: nothing yet. Otherwise the low two bits say: 1 worth compiling, 2 better left to the interpreter, because native code for it would spend its time leaving native code, 3 worth compiling for native callers but too small to be worth entering from the interpreter. The bits above hold an estimate the JIT keeps for judging callers (see JIT.Estimate). Only the thread that compiles writes this; the interpreter reads it when it finds code in the cell.

Cells are handed out from a pool, so that loading code (an STM transaction) never has to allocate memory: a retried transaction would leak it. The pool is a block of cells and a count of how many are in use. When it runs out, a new block is allocated outside the transaction with growNativeCellPool. Old blocks stay in use, and are never freed.

Allocates zeroed cells for n combinators, as one block that is never freed.

The cell at index i of a block from newNativeCells.

Takes n cells from the pool, or fails if it has fewer left.

A fresh block with room for at least n cells, and at least twice the old capacity so that growing stays rare.

A shared cell for combinators that are never compiled: builtins, and combinators that were not loaded through the code cache.

Gives every combinator in a group of freshly loaded code its own cell from base, numbering them in order. Returns the count used.

The fixed point of a GComb where all references to a Comb are themselves Combs.

Map of combinators, parameterized by comb reference type

A reference to a combinator, parameterized by comb

A case of a branch: the fields it binds and its code.

How many fields a match arm binds: the number of slots emitCase lays the arm's context out with. A data or request match's arm carries it (Arm), because it is the one thing about an arm that the object being matched cannot say: the interpreter pushes the object's own fields and runs the arm only when their count is the arm's (dataBranch), and native code reads the object's count (its pointer tag, or the lengths of a wide constructor's arrays) and takes the arm only when the two agree. The arms of a match on an unboxed value bind no fields (0).

No field names assigned yet. The starting state for emitCombs and friends, in the same spirit as emptyRNs.

Note that the Ord instance for Field Refs is arbitrary and not tied to the field name Ord instance.

The combinators of a group, under its number, and, when the explosion rewrote any of its lambdas so that a frame differs, the group as the unoptimized code has it, under the second number: what a continuation written out by this process resumes in another, and what one from another process resumes here (design.md, "Continuations across processes").

lazily replace all references to combinators with the combinators themselves, tying the knot recursively when necessary.

If running in a sandboxed environment, replace all restricted foreign functions with an error.

How many slots an instruction pushes onto the frame, or Nothing where the interpreter takes over from here (a capture, a sandboxing failure). The one account of an instruction's effect on the frame: the JIT's code generator lays frames out by it and resultCount counts a primitive's results by it, so the two cannot disagree.