Skip to content

Programs compiled to JavaScript

A program written in C or C++ and compiled for the web with Emscripten does not arrive as ordinary JavaScript. It arrives as asm.js: a subset of JavaScript where the type of every value can be worked out before anything runs. The engine compiles such a module ahead of time and runs it as typed code, which is many times faster than running it as ordinary JavaScript.

Nothing has to be switched on. A module that validates is compiled the first time the engine parses it, and a module that does not is run as ordinary JavaScript, which is what a browser does too.

How to tell what happened

KiteJs(Rhino).use { js ->
    js.evaluate(source, "game.js")
    for (report in js.asmReports) println(report)
}

Each line covers one function whose body starts with "use asm":

asm: compiled
asm: not compiled (Oa: a division mixes signed and double)
asm: compiled, not linked (Math.imul is not the engine's own)

The reason names the first thing in the module that asm.js does not allow. It is the answer to "why is this slow": a module that does not compile still gives the same results, only slower.

What a module looks like

var m = (function (stdlib, foreign, heap) {
  "use asm";
  var H32 = new stdlib.Int32Array(heap);
  var imul = stdlib.Math.imul;
  function scramble(n) {
    n = n | 0;
    var i = 0, x = 0;
    for (i = 0; (i | 0) < (n | 0); i = (i + 1) | 0) {
      x = (imul(x, 1103515245) + 12345) | 0;
      H32[(i << 2) >> 2] = x;
    }
    return x | 0;
  }
  return { scramble: scramble };
})({ Math: Math, Int32Array: Int32Array }, {}, new ArrayBuffer(1 << 20));

m.scramble(1000000);

The three arguments are the standard library, an object of functions the module imports from outside, and an ArrayBuffer the module uses as its memory. All three are checked when the module is called: stdlib.Math.imul has to be the engine's own Math.imul, not something that shares the name. A module given anything else is run as ordinary JavaScript instead. The heap length must be a multiple of every declared view's element width. A length that cannot construct those views runs ordinarily and keeps its original construction error.

Linking accepts stored data properties on plain objects and their ordinary prototypes, and checks built-ins against their original identities. Getters, proxies, host-backed property lookups and numeric imports requiring object conversion use ordinary initialization. This keeps their effects and errors in their original order, exactly once, even when a later import would prevent linking.

An imported function's result is discarded without conversion when the module uses a bare call. Explicit +, | 0 and fround conversions still read that result, including their conversion hooks and errors, even when the final numeric value is discarded.

Compiling is a decision about types, not about speed

Every rule asm.js has exists so that a value's type is known in advance. x = x | 0 at the top of a function says the parameter is a 32 bit integer. 0 declares an integer variable and 0.0 declares a double. (a | 0) / (b | 0) | 0 is integer division and a / b on two doubles is not. The spelling -0 also declares a floating value, since integer slots cannot retain its sign.

The rule that matters most is the one about uncoerced values. The result of +, - or * on two integers may only be read where its overflow cannot be seen: under |, &, ^, a shift, a byte heap index, or inside another +, - or *. This is what lets the engine add two integers with one machine instruction and let the result wrap at 32 bits, where plain JavaScript would widen the sum to a double and keep every bit of it.

A heap read is written H32[p >> 2], where the shift matches the width of the view. The engine reads the bytes directly. An out-of-range read answers zero after integer coercion and NaN after floating-point coercion. An out-of-range write does nothing, the same as through a typed array view.

What the compiler does not take

  • A module the engine cannot read as asm.js at all, for example one using a value whose type is not fixed.
  • Arithmetic on floats where the result is not passed to Math.fround, since that is how asm.js says a float result is rounded back to a float.
  • Functions whose returns do not agree on a type, or whose typed result can be missing on some path. They run as ordinary JavaScript, including its undefined result on a path that reaches the end.
  • Modules with variable declarations after the export return, since their initializers must remain unreachable.
  • Modules that reuse a function's name for another binding. They run ordinarily so the exports retain the values assigned during initialization.
  • Conditions using uncoerced integer arithmetic, since its wider JavaScript result can have different truthiness from a wrapped 32-bit value.
  • An engine set to big-endian byte order through KiteJsConfig.littleEndian, because the compiled code reads and writes the heap in little-endian order and the views around it have to agree.

Turning it off

KiteJs(Rhino) { asmJs = false }.use { js -> /* ... */ }

A module then runs as ordinary JavaScript. The answers are the same either way, so this is only useful for comparing the two, or as a way around a problem in the compiler.

Budgets and stopping

An instruction budget and interruptWhen both apply to compiled code. The runner charges bounded groups of typed instructions at control-flow entries, after calls, and within long straight-line blocks. Recursive call trees and functions without loops therefore reach the observer too.

The budget covers the whole outer call, including imports and reentrant calls into the module. A later call from Kotlin gets a fresh budget. The instruction units depend on the execution path, and a group is charged before it runs, so stopping need not occur at the same statement as in ordinary JavaScript. With neither a budget nor an interrupt hook, the runner uses its original code without accounting instructions.

Compiled calls use the native stack and count toward RhinoConfig.maxHostCallDepth, including calls made while an import or observer has reentered the engine. Exceeding it throws RangeError and leaves the engine usable.