Debug probes
How a debug build tells the runtime where it is, keeps a shadow stack, and writes a frame's locals
A program nanyx run runs has debug probes: at the start of each function, at each statement and at each place a
function ends, its code can call the runtime, which keeps a shadow stack from them and can ask for the locals of the
frame it is in. They are the foundation of the debugger, which is planned on Debugging.
A release build has none, and nor does a debug build written to a file by nanyx build or nanyx wasm, which another
WebAssembly runtime, without the imports below, may run (WasmOptions.Probes).
Probes in the core IR
A probe is a core IR expression, Probe(kind, locals) (CoreIr.fs), of unit type, at a place (see
Crash stacks). The lowering puts one before each statement of a block, written
to write the locals in scope there, and wraps each function the source writes, a lifted lambda among them, in
CoreIrProbes.around: an entry probe, which names the function and writes its parameters, and a return probe at each
place it ends. A function that ends in a call ends before the call, so that a tail call stays one, and the callee’s
entry follows; one that ends in another value ends once it has it, in a local. A local is written only if a dbg
printer can write its type (CoreIrLowerDbg.printable), and not a cell’s, whose local holds its box.
A probe uses none of its locals, so reference counting never keeps a value alive for one, and a debug build frees and reuses memory as a release build does. The inliner doesn’t count probes in a function’s size, so debug and release builds inline alike, and a probe inlined with its function keeps the place it was written at, with the calls it was inlined through.
The code
The emitter writes a probe as a check of whether the runtime is probing: the start function sets a global,
$__nanyx_probing, from the runtime’s nanyx:debug enabled before anything else runs, and each function with probes
copies it into a local when it starts, which can stay in a register. When it is set, the probe calls nanyx:debug probe with its
number; if that gives 1, it writes each of its locals that is still alive there through its printer, and passes the
local’s name and text to nanyx:debug local. A local is still alive where the rest of the code reads it and doesn’t
bind it again (CoreIrEmit.aliveAt): one never read again may have been given up already. A probe that a printer
takes its argument over from first gives it a reference of its own.
Before the probe’s code go the marker of its place and its own, ;;@probe 3 statement or ;;@probe 1 entry count.
WasmBinary writes each probe into the table of places, nanyx.spans, by its number: its kind, its function’s name for
an entry, and its place, so the runtime knows each probe without the program telling it more than a number.
The runtime
Probing.define answers the imports. Without a listener, enabled gives 0 and the program never calls the runtime;
with one (WasmRunner.runListening, an IProbeListener), each probe the program passes is given to it by its number in
the table, and it says whether it wants the locals. ShadowStack keeps the frames from the probes, innermost first,
each at the place of the last probe it passed: an entry pushes a frame, a statement moves the top one, and a return pops
it. A function inlined into another has a frame of its own, since its probes were inlined with it.
dbg
A module with probes gives what each dbg prints to the runtime too: nanyx:debug dbg(file, line, column, text),
the file’s name and the text as strings, says whether the runtime has dealt with it, and when it hasn’t the program
writes [file:line] text to its stderr itself, as a module without the import does (EmitContext.DbgToRuntime). The
runtime’s handler is the host’s (Probing.defineDbg): WasmRunner leaves it to the program, so that it keeps its place
among what else the program writes to stderr, and WasmServer writes it to the server’s log with the request it came
from (Hosts). A module compiled with WasmOptions.DbgToEmbedder imports
nanyx:debug dbg in the same way but none of the probes’ imports, for an embedder that only wants dbg, such as a
page.
What it costs
Without a listener, a probe is a read of a local and a branch. Against the same program built without probes, with the module’s size and the fastest of 21 runs:
| Program | Without | Without a listener | Listening | Reading locals at every statement |
|---|---|---|---|---|
fib(30), a call for each node | 2.3 KB, 9.9 ms | 7.0 KB, 13.4 ms (+35%) | ×62 | ×60 |
| A tail-recursive loop of 30 million | 2.4 KB, 61 ms | 7.2 KB, 75 ms (+22%) | ||
map, filter and fold over 300,000 | 4.6 KB, 13.1 ms | 11.2 KB, 16.4 ms (+25%) |
Reading the global at each probe rather than a local cost about twice as much (+42% for the loop, +57% for the lists).
Reading every frame’s locals at every statement costs little more than listening: it is the call to the runtime at each probe that costs, so a debugger listens only while it is stepping or has a breakpoint, and asks for locals where it stops.
The design call, how a frame’s locals stay reachable: they are written by the program when the runtime asks, at the probe, rather than spilled to a shadow frame in linear memory at each probe. Spilling would cost stores at every probe while a debugger listens, and would leave the runtime with references that reference counting may already have given up, since a local is dropped after its last use, not at the end of its scope; keeping them alive would change when memory is freed, and stop in-place reuse, in every debug run.