Skip to the content
Diaspar

Decision D042 · accepted; a spike built

The browser's build: the whole diaspar as 64-bit WebAssembly; no 32-bit targets

A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.

Status: accepted (2026-11-18, by the author). The build exists as a spike (mise run wasm:build, compiler/web/, runtime/support/web.c); the website's module for the REPL is not designed yet (open question 1). Carries out the playground entry of the roadmap; amends D028 §1.

Decision

  1. No 32-bit targets, wasm32 included. Every target is 64-bit and little-endian (D028). The browser's build uses 64-bit WebAssembly memory (memory64, standard in WebAssembly 3.0). D028's remark that a wasm32 target would keep the 64-bit word with 32-bit pointers is withdrawn. diaspar.h asserts sizeof(void *) == 8; it used to allow less.

  2. The browser gets the whole diaspar, not a stripped build: the evaluator, the REPL, std, the compiler's front end and its C backend. The backend is about 14% of the program's code, which is little. diaspar build --c-dir works in the browser. A build to a binary fails with "cannot run cc: not available in the browser". Nothing is cut that would change what a program does.

  3. It is built to WebAssembly through C, with Emscripten (-m64): the compiler emits the C of diaspar.cli.web, emcc compiles it with the runtime, and std's sources, the Unicode data std's macros read, and the runtime's C are embedded in the binary's file system. Programs run in the browser on the evaluator. A WebAssembly backend that compiles user programs from the core IR comes later. It is not part of this decision.

  4. The browser is a root of its own (D005): a virtual file system (Emscripten's MEMFS, std at /std, the working directory /home/user), standard streams that the page collects, which are not terminals, no processes, one thread. runtime/support/web.c is the platform layer. It replaces main.c's dsp_main, term.c and the process and file-lock primitives of unsafe.c:

    • Threads off: the program runs on the one thread there is, on the module's stack. Its limit is set from that stack's end.
    • Terminal: none. term-open fails with :no-terminal, as it does natively without a controlling terminal. Ctrl-C never comes; the page stops code by ending the worker.
    • Processes: none. spawn fails with ENOSYS, and std's process errors read "cannot run ls: not available in the browser".
    • File locks: Emscripten's flock does nothing, so the layer keeps them per descriptor, as flock does. Waiting for a lock that another descriptor holds fails with EDEADLK: with one thread, nothing can release it, and natively the wait would hang.

    The native build is unchanged: main.c, term.c and unsafe.c keep their code, and the browser's replacements sit behind DSP_WEB (support.h).

  5. Runs and the REPL in a Web Worker. A run gets an instance of its own: nothing is left over from the previous program, and a program that never ends costs only its worker, which the page ends and starts again from the compiled module, with no download. The REPL session is one instance kept resident. With DIASPAR_WEB_SESSION=1, main gives a function, the session, and the runtime keeps it instead of finishing the program. The page calls it once per input through dsp_web_session_eval, so the REPL keeps its state between inputs without blocking on standard input. It needs no Asyncify, no SharedArrayBuffer and no COOP/COEP headers. An input is handled as diaspar repl handles piped lines.

  6. The page's API (diaspar-web.mjs): load({onProgress}) downloads and compiles the binary while it arrives, reporting the phases download (bytes of the total), compile, start and ready. run(source, {args, stdin, file, timeoutMs}) gives {stdout, stderr, status, timeMs, startMs, memoryBytes}. repl.eval(text) gives {stdout, stderr, status}, where status is ok, incomplete, error, reset or an exit status. stop() ends what runs.

What the spike measured (2026-11-18)

Emscripten 7.0.0, Chromium 155 headless and node 26 on Linux x86-64, at main f4d6ba89; the native evaluator is build/diaspar run --interp.

diaspar.wasm 33.0 MB raw, 6.6 MB gzip, 3.5 MB brotli. Code 17.9 MB; data 15.0 MB, of which 9.4 MB is the embedded files (std 0.8 MB, the runtime's C 0.5 MB, the Unicode data 8.1 MB raw but 0.37 MB in brotli) and the rest is the modules' source text, which reports quote, and their literals
-Os instead of -O2 4% less code and a larger brotli file: not worth it
download and compile streaming compilation finishes 13 ms after the last byte; the download is the size over the link: 3.5 MB is about 0.55 s at 50 Mbit/s and 2.8 s at 10 Mbit/s
the first run about 450 ms (V8 compiles each function the first time it runs); later runs start an instance in about 15 ms
hello world 85 to 105 ms a run (Chromium, node); natively 57 ms for the whole process
a small benchmark (fib 24, a map/filter/reduce over 200,000 numbers, 50,000 assocs) 460 to 480 ms in Chromium and node, 238 ms natively: about 2 times slower
memory an instance grows to 38 MB for hello world and 46 MB for the benchmark (16 MB of it the stack); the native process peaks at 36 MB RSS
behaviour of the 248 programs in tests/cases, 243 give the same output, errors and status as natively; the REPL session gives the same as diaspar repl with piped input (mise run wasm:test)

The five that differ:

  • Deep recursion (4 cases). The engine's own stack, not the runtime's, runs out first. Each level of recursion of a program on the evaluator costs six WebAssembly frames, about 1.2 to 2.4 KB of engine stack. A page cannot choose that stack's size, and Chromium gives a worker about 1 MB. Plain recursion therefore goes 424 levels deep in Chromium (node with 1 MB: 711) against about 87,000 natively. Past that, the run ends with "stack overflow: the browser's stack ran out" instead of the catchable "stack overflow", and a REPL session starts afresh. Firefox's stack is reported to be about three times Chromium's (Pyodide's measurements). Open question 2.
  • The C library (1 case). math.pow, log and cos are musl's, which differ from glibc's in the last bit for some inputs; glibc picks FMA versions on x86-64. A native build on another C library differs in the same way. math.cbrt is the runtime's own and correctly rounded, so it agrees everywhere.

Browser support (sources checked 2026-11-18)

  • memory64: Chrome and Edge 133+, Firefox 134+, Node 24+. Not in Safari: only Safari Technology Preview 251 has it (webassembly.org's feature table; MDN's compatibility data of 2026-11-02). So it does not run on any iPhone or iPad browser, since all of them use WebKit. The page should detect memory64 (validate a tiny module with a 64-bit memory) and say so instead of failing.
  • Speed: memory64 costs about 10% over wasm32 (bounds checks that guard pages cannot remove; Emscripten's benchmarks under V8, SpiderMonkey's measurements). That is the price of rule 1.
  • Module workers, compileStreaming and TransformStream, which the page's module uses, are in every current browser.

Toolchain

Emscripten, not wasi-sdk. wasi-sdk has no 64-bit target (no wasm64-wasip1, none planned; wasm64-wasip2 waits on the component model), and a browser would need a WASI shim with memory64 besides. Emscripten 7 builds wasm64 with -m64 (-sMEMORY64 is deprecated) and supplies what the browser lacks: MEMFS, embedded files, the JavaScript glue, ENVIRONMENT=web,worker,node. The C compiled unchanged: the runtime needed only the platform layer of rule 4.

For the website

  • Files: build/wasm/diaspar.wasm, the Emscripten glue diaspar.mjs, diaspar-engine.mjs, diaspar-worker.mjs, diaspar-web.mjs, and manifest.json (the binary's name, its size for the progress bar, a hash). Serve them from one directory; import diaspar-web.mjs.
  • Headers: Content-Type: application/wasm for the binary, which streaming compilation requires. Compress with brotli or gzip (the progress bar counts decompressed bytes against the manifest's size). No COOP/COEP headers are needed: no SharedArrayBuffer, no threads.
  • Caching: give the binary a content-hashed name, or the manifest's hash in the URL, and Cache-Control: immutable, so a second visit downloads nothing. V8 also caches the compiled code of a module that compileStreaming gets straight from fetch, but the progress bar wraps the response to count its bytes, and a wrapped response has no URL to cache the code under. Since compiling is lazy and the first run costs about 450 ms either way, the spike keeps the progress bar (open question 6). The JavaScript files are small and change with the binary.

Rejected alternatives

  • wasm32 with 64-bit values and 32-bit pointers: about 10% faster and in Safari, but a second pointer width everywhere in the runtime and the C it emits. Rejected by the author: no 32-bit targets.
  • A stripped build (the evaluator and std without the compiler's back end): the back end is a small part of the binary, and a playground that behaves differently from diaspar misleads.
  • Blocking standard input for the REPL through Asyncify (larger and slower code everywhere, since every indirect call may suspend), JSPI (a suspending import and a promising export around every call), or SharedArrayBuffer with Atomics.wait (COOP/COEP headers on the website). The resident session needs none of them.
  • A run in the REPL's instance: a fresh instance is cheap (about 15 ms) and isolates programs.

Open questions

  1. The REPL's module for the page: output (colors, markup), input, maybe the DOM. Not designed yet. Today the session prints plain text, as a pipe gets it.
  2. Recursion depth. The fix has to reduce the engine stack a level uses: an evaluator that keeps the program's calls off the C stack, or the WebAssembly backend, whose calls are one frame each. The stack-switching proposal may later give growable stacks. Meanwhile the runtime cannot see the engine's stack. A limit on the shadow stack that is tight enough for plain recursion stops recursion through closures far too early: shadow-stack use per level ranges from 64 to 500 bytes against an engine-stack use of about 1.2 KB.
  3. Safari: wait for memory64, or show a notice; a wasm32 build is excluded by rule 1.
  4. Interrupting code without ending the worker (Ctrl-C in the REPL): a flag the page sets in a SharedArrayBuffer would need COOP/COEP.
  5. Size: the Unicode data could be fetched only when a program loads std.unicode from source, and the modules' embedded source text could go where reports read it lazily.
  6. Progress or the code cache: count the bytes for the progress bar on the first visit only (when the binary is not in the HTTP cache yet), and pass fetch's own response to compileStreaming otherwise; measure what the code cache saves.
  7. Fibers (D035 step 1a, 2026-11-18): the browser's build has none, so a handler that keeps resume or resumes before a clause's end raises "this build has no fibers" there, and generators and tasks do not run. WebAssembly cannot switch stacks inside a module yet (the stack-switching proposal is at phase 3 and no browser ships it; JSPI only suspends to the event loop). The choices are in design/concurrency.md §10, question 12: Asyncify for the whole binary, which this decision rejected for the REPL's input; an evaluator that keeps a program's calls off the C stack, which would also answer question 2; or waiting.