TurboFan: the sea-of-nodes optimiser

Why a graph instead of a list of statements

A traditional compiler models a function as a control-flow graph (CFG) of basic blocks, each a fixed sequence of statements. Order is baked in from the start: statement 3 comes after statement 2 because you wrote it that way. To move computation, such a compiler must prove the move is legal against that imposed order.

TurboFan inverts this. Its IR is a sea-of-nodes graph in which a node is an operation and the edges — not the source order — encode every constraint that actually matters. There is no notion of “instruction order” until the very end. The graph carries three kinds of edge:

• Value edges (data dependencies): subtract has value edges to the two loads it consumes. This says “I need these inputs”, nothing about when.
• Effect edges (ordering of observable side effects): a store, a call that might mutate state, a property load that could trigger a getter — these are chained on an effect chain so their relative order is preserved. Pure operations (arithmetic on known numbers) carry no effect edge and float free.
• Control edges (branches, merges, loops): the skeleton of if/loop/return that decides which nodes execute at all.

Because a pure subtraction has only value edges and no effect or control constraint, the scheduler (a late phase) can place it anywhere its inputs are available — including hoisting it out of a loop if its inputs are loop-invariant. This is what mrale.ph’s writing means by “the scheduler places computation late”: nodes have no fixed home until scheduling assigns one, and it assigns the cheapest legal one.

The phase pipeline

Why does the order of passes matter? Because front phases can still rewrite the graph freely — once you commit to machine instructions, rewriting is too expensive. TurboFan is a sequence of well-defined passes over that graph. The shape, in order:

Graph building turns bytecode into the initial sea-of-nodes graph, attaching the feedback vector’s observations so later phases know the speculated types. Typing and typed lowering propagate types through the graph (a + of two SignedSmall-typed nodes is typed as a number in a known range) and replace abstract operations with type-specialised ones — a generic JSAdd becomes a NumberAdd, then potentially an Int32Add.

Then the optimisation passes rewrite the graph:

• Inlining — a call node whose feedback names a small, known target is replaced by a copy of the callee’s graph, splicing its value and effect edges into the caller. This is what unlocks cross-function optimisation; without it, every call is an opaque effect.
• Escape analysis with scalar replacement — an object whose reference never escapes the function (covered in depth in lesson 04) has its allocation deleted and its fields turned into ordinary graph nodes (registers), eliminating the heap allocation and the GC pressure.
• Load/store elimination — a load that must read a value just stored is replaced by the stored value directly; a store overwritten before any read is deleted.
• Redundancy elimination and constant folding — a CheckMaps that a dominating CheckMaps already proved is removed; 2 * 3 becomes 6; a branch on a known-true condition is collapsed.
• Representation selection — decides the machine representation of each value: a tagged pointer, a 32-bit integer in a register, or a 64-bit float in an FP register, inserting conversions only where a representation boundary is actually crossed.

Scheduling is the phase that finally assigns nodes to basic blocks and an order within them — placing pure nodes as late and as un-loopy as legal. Instruction selection matches graph patterns to the target ISA’s machine instructions. Register allocation (TurboFan uses a sophisticated allocator, not the linear scan Maglev uses) assigns physical registers and inserts spills. Code generation emits the final bytes. The output is a blob of native machine code installed on the function.

Where it runs and how to inspect it

TurboFan compiles on a background thread (concurrent compilation, lesson 01): the main thread keeps running the function on its current tier and the optimised code is swapped in when ready. This is the source of the most common mental error about it (see below). To inspect the graph, --trace-turbo dumps the IR at each phase into files you can open in the Turbolizer visualiser; --trace-opt logs the higher-level decisions. mrale.ph and the v8.dev/blog posts are the canonical deep references for the graph and its phases.