90. The plugin API

The same loop, twice

Here is a loop you have seen many times, written in Python:

ps = []
for i in range(1000):
    ps.append(P(float(i), 1.0))
for p in ps:
    p.x += p.vx

P is a dataclass with fields x and vx. Run viscosity explain on it and the answer is the opposite of the JavaScript version’s:

ps (line 8) {x, vx} → kept as array of
  objects
  · CPython: column access measured
    slower per element than objects
    (the win is about 5x less memory);
    add "# @viscosity soa" above the
    list to opt in

Same program, same analyses, different verdict. To see how one compiler handles two languages, and why it can answer differently for each, you need the interface between the core and a language.

Two functions

This is the whole interface, from packages/core/src/plugin.ts:

interface LoweredModule {
  module: Module;
  annotations: Map<BindingId, Annotation>;
}

interface LanguagePlugin {
  id: string;      // 'javascript'
  extensions: string[];
  lower(source: string,
    filename?: string): LoweredModule;
  emit(source: string,
    lowered: LoweredModule,
    plan: Plan): string;
}

lower turns source text into a VIR Module, plus any @viscosity annotations it found in comments (each language writes comments differently, so finding them is the plugin’s job). emit gets the source back, the same lowered object, and the plan, and returns new source.

There is no parse in the interface. Parsing happens inside lower, and the parser is the plugin’s own business: the JavaScript plugin uses acorn or a hand-written parser (chapter 92), the Python plugin its own tokenizer and parser. The core only ever receives VIR.

Look again at emit’s arguments. It gets lowered back, typed as a plain LoweredModule, but a plugin may return a bigger object from lower. The JavaScript plugin adds its ESTree tree, its scope resolution, and the JavaScript text it actually analysed (TypeScript is stripped first). The core passes that object along without looking inside, and emit takes out what it needs. Each plugin keeps private state across the core this way, without the core knowing its type.

Why this split

Step through both programs:

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

Some work can only be done by someone who knows the language. Parsing, obviously. Lowering too: only the Python plugin knows that P(...) builds a record, because it saw the @dataclass; only the JavaScript plugin knows that { x: i } does. And emit must write correct syntax, with Python’s indentation or JavaScript’s braces.

The rest is about data, not syntax. “Which fields does this loop touch?” has the same answer however the loop was spelled. Writing that analysis once, on VIR, means the escape checks, the numeric inference and the bounds proofs from earlier chapters serve every language, and a bug fixed there is fixed for all of them.

A language is also a fact

So why did the Python program keep its objects? The core never sees Python syntax, but it does read one field of the module, module.language, in two places. The numeric analysis needs it because “a number” differs: any JavaScript number fits a Float64Array, but in Python only a float may go into an array('d') column (an int would come back as 1.0). And the planner needs it here, because the repository’s measurements say so. In this book’s benchmark run on CPython 3.13 with 100,000 elements (packages/bench/FINDINGS.md, section 6), the update loop took 26.7 ns per element over dataclass objects and 72.7 ns over array('d') columns. Memory went from 16.0 MB to 3.3 MB.

CPython is an interpreter. Reading an element of array('d') creates a new float object each time, so the cache-friendlier layout loses on time. V8’s optimizing compiler reads a Float64Array element as a raw double, which is why JavaScript wins. So Python keeps objects by default, explains why, and lets you opt in with # @viscosity soa (or --python-auto) when memory matters more.

Layout strategies

The other axis of extension is how a collection is stored. The same file declares it:

interface LayoutStrategy {
  id: string;
  describe: string;
}

const STRATEGIES: LayoutStrategy[] = [
  { id: 'aos', describe: '…' },
  { id: 'soa', describe: '…' },
  { id: 'aosoa', describe: '…' },
];

Be honest about where this stands. The comment says “strategies are plugins too”, but today the list is a registry of names and descriptions. The planner’s Layout type names the same three, and each emitter implements each one: the JavaScript emitter writes all three, while the Python emitter supports aos and soa and throws on aosoa. Adding a fourth strategy, say hot/cold splitting, means a planner rule plus emitter code in each plugin. The strategies are cleanly separated, but not yet loaded like language plugins.

Your turn

// The shared core: language-neutral.
function fold(mod) {
  const plan = new Map();
  for (const i of mod.insts) {
    if (i.op !== 'add') continue;
    plan.set(i.line, i.a + i.b);
  }
  return plan;
}
function compile(src, plugin) {
  const low = plugin.lower(src);
  const plan = fold(low.module);
  return plugin.emit(src, low, plan);
}

// Your plugin.
const eq = {
  id: 'eq',
  lower(src) {
    // return { module: { insts } }
  },
  emit(src, low, plan) {
    return src;
  },
};

console.log(compile('x = 1 + 2', eq));

// The shared core: language-neutral.
function fold(mod) {
  const plan = new Map();
  for (const i of mod.insts) {
    if (i.op !== 'add') continue;
    plan.set(i.line, i.a + i.b);
  }
  return plan;
}
function compile(src, plugin) {
  const low = plugin.lower(src);
  const plan = fold(low.module);
  return plugin.emit(src, low, plan);
}

const lisp = {
  id: 'lisp',
  lower(src) {
    // return { module: { insts } }
  },
  emit(src, low, plan) {
    return src;
  },
};

What you learned

• A language plugin provides id, extensions, lower and emit. Parsing lives inside lower.
• lower returns VIR and annotations; the plugin can add private data to that object, and emit gets it back.
• Syntax work (parse, lower, emit) is per-language; work on data (analysis, planning) is shared, on VIR.
• The core reads module.language as a fact, in numeric inference and in the planner. CPython measured slower with columns, so Python keeps objects unless you opt in.
• A layout strategy is a way of storing a collection: aos, soa, aosoa. Today they are a fixed list implemented by each emitter.