89. The architecture of Viscosity

Twenty-five lines

You have spent six parts collecting pieces: arrays of objects and why they are slow to scan, parsers, IRs, SSA, dominators, escape analysis, differential tests. Part VII puts them together into Viscosity, the compiler in this repository’s engine/ts folder.

The surprise is how small the top of it is. The file packages/core/src/index.ts is 25 lines long, and this is the part that matters:

function compile(source, plugin, opts) {
  const lowered = plugin.lower(source);
  const analysis =
    analyze(lowered.module);
  const p = plan(analysis, opts);
  const code =
    plugin.emit(source, lowered, p);
  return { code, plan: p, analysis,
    explain: explain(p) };
}

(Trimmed: the real one merges opts with defaults and passes along the @viscosity annotations the plugin found.) Every chapter from here to 112 lives inside one of those four calls.

Four steps, two owners

Step through one program. Watch the label above each stage: some steps belong to the language plugin, the rest to the core.

const ps = [];
for (let i = 0; i < 1000; i++)
  ps.push({ x: i, vx: 1 });
for (let i = 0; i < ps.length; i++)
  ps[i].x += ps[i].vx;
console.log(ps[3].x);

The steps, with what each consumes and produces:

• lower (plugin): source text → a VIR module. For JavaScript that means parsing with acorn into an ESTree tree, resolving scopes, then lowering the tree to VIR.
• analyze (core): VIR → facts. Which bindings are collections, which fields are numbers, which loops touch which fields, and the reasons it isn’t safe, if any.
• plan (core): facts → a layout per collection, with reasons.
• emit (plugin): the original source, plus the plan → new source.

Notice what emit does not do. It doesn’t print the program from VIR. It takes your original text and replaces only the ranges the plan requires, such as ps[i].x becoming ps.x[i]. VIR instructions keep a pointer back to the source range they came from, which is what makes that possible. Your comments, formatting and every unrelated line come through exactly as you wrote them.

Output that is source code

Here are the last lines that viscosity build really wrote for the program in the diagram. A class __Vsc_ps with one Float64Array per field is generated above them (chapter 103 builds it), along with a bounds-check helper:

const ps = new __Vsc_ps();
for (let i = 0; i < 1000; i++)
  ps.push(i, 1);
for (let i = 0; i < ps.length; i++)
  ps.x[i] += ps.vx[i];
console.log(ps.x[__vsc_bc(ps, 3, 'x',
  false)]);

The input was JavaScript, and so is the output. You can read it, diff it, ship it, and run it on any engine.

// Before: an array of objects.
const ps = [];
for (let i = 0; i < 4; i++)
  ps.push({ x: i, vx: 1 });
for (let i = 0; i < ps.length; i++)
  ps[i].x += ps[i].vx;
console.log(ps[3].x);

// After: what a source-to-source
// compiler could write instead.
const qs = { length: 0,
  x: new Float64Array(4),
  vx: new Float64Array(4) };
for (let i = 0; i < 4; i++) {
  qs.x[i] = i; qs.vx[i] = 1;
  qs.length++;
}
for (let i = 0; i < qs.length; i++)
  qs.x[i] += qs.vx[i];
console.log(qs.x[3]);

Ahead of time, or inside the engine

Viscosity is not the first system to turn arrays of JavaScript objects into columns. Makor and colleagues did it at run time, inside a JavaScript engine built on Truffle and Graal^[1][3], and a follow-up generated specialized loop code for the converted arrays^[2].

The trade is real in both directions. A run-time transformation sees the actual values and can speculate, then back out with deoptimization if a guess fails. But it only helps programs run on that engine. Viscosity’s output runs anywhere, adds no compile work at start-up, and can be read by a person. In exchange it gets one look at the code, with no values and no way to back out. Every decision must be proved from the text alone, and when the proof fails the collection stays as it was.

Try it

This is the real compiler, running in your browser. Change the program and press the buttons: see the decision, the compiled code, and “Run both”, which checks the two versions print the same thing. Then try console.log(ps[3]) on the last line, and see what changes.

Your turn

function rewrite(src, name, fields) {
  // your code here
  return src;
}

console.log(rewrite(
  'ps[i].x += ps[i].vx;',
  'ps', ['x', 'vx']));

function compile(src, plugin, core) {
  // your code here
  return { code: src, explain: '' };
}

What you learned

• The Viscosity pipeline is lower → analyze → plan → emit, in a 25-line compile function.
• Lower and emit belong to a language plugin; analyze and plan belong to the core and only see VIR.
• Emit rewrites the original text range by range, so untouched code survives exactly.
• Viscosity is a source-to-source compiler: JavaScript in, JavaScript out, runnable on any engine.
• Doing the change ahead of time trades run-time knowledge and deoptimization for portability and readable output, so every decision must be proved from the code.