Skip to content

wasm: Thread.spawn and Worker under Node, on a shared memory - #818

Merged
ASDAlexander77 merged 6 commits into
mainfrom
wasm-threads
Nov 12, 2026
Merged

ASDAlexander77 merged 6 commits into
mainfrom
wasm-threads

Conversation

@ASDAlexander77

@ASDAlexander77 ASDAlexander77 commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Thread.spawn, Worker, Atomics.wait and Atomics.notify now run on wasm32 and wasm64 under Node. Before this, the wasm test runner skipped every test that used them.

Builds on #817 (wasm async), now merged; main is merged in.

How it works

  • A program that starts a thread gets a shared memory. Such a program is one whose module calls tslang_thread_spawn. It is linked with:

    • --shared-memory --import-memory;
    • --max-memory: 4 GB on wasm32, 16 GB on wasm64, V8's limits;
    • --export=__stack_pointer, so each thread can set its own stack.

    Every other program keeps an unshared memory, so it still runs in a browser page that is not cross-origin isolated.

  • Each thread is a Node worker (docs/how/wasm/test/thread.mjs). It instantiates the same compiled module on the same memory and gets a 1 MB stack. When the module has thread-local data, it gets its own copy through __wasm_init_tls. It does not run the module's constructors again.

  • join waits on the thread's control block with Atomics.wait. The control block records how the thread ended:

    • it returned;
    • it called exit(): join then ends the program with that code, as a native exit() from a thread does;
    • it failed: join then throws.
  • Atomics.wait and Atomics.notify use the real atomics on a shared memory. On an unshared memory nothing else can run, so a wait checks the value and then sleeps out its timeout. A wait with no timeout fails instead of hanging.

Compiler

  • obj.cpp: every wasm object, the default library's included, is compiled with +atomics,+bulk-memory. A shared memory needs these from everything linked into it. An unshared memory works with them too: I checked that such objects link with and without --shared-memory.
  • exe.cpp: adds the link flags above when CompileOptions::wasmThreads is set. obj.cpp sets it when the optimized module still calls tslang_thread_spawn.
  • wasm32 heap block header is now 8 bytes, not 4. With real atomics, Atomics.add on a BigInt64Array trapped on wasm32 with "operation does not support unaligned accesses". The index-sized block word put 64-bit elements at a 4-byte offset. Until now that was harmless, because without the atomics feature LLVM lowered atomics to plain loads and stores.
    • The new CompileOptions::heapBlockHeaderBytes() returns 8 on wasm32, and the index width everywhere else.
    • The count is still an index-sized word at the start of the block, so the code that counts, retains and releases is unchanged.
    • Only the static layouts get wider: string literals, constant arrays, static array headers, stack-promoted blocks, and the type descriptor record, whose last field is the tag's block word.
    • Checked: wasm64 and x64 IR is the same before and after (254 comparisons over 43 tests and 3 models, ignoring the pointer-hash names that vary from run to run). wasm32 IR has no 4-byte block word left.
    • i686 and ARM32 have the same 4-byte layout. Native x86 tolerates an unaligned 64-bit atomic, but ARM32 would not. This PR leaves them unchanged.

Host (docs/how/wasm/test)

  • The heap now lives in the module's memory, behind a lock, because one thread frees what another allocated. It keeps the same scheme: free lists per 16-byte size class above a bump pointer. Each block has a 16-byte header holding a magic number, its size, and its free-list link while it is free. The lock is an Atomics compare-exchange, which also works on an unshared memory. Every program uses this heap, so the whole suite exercises it.
  • memoryOf(bytes) also reads an imported memory's limits. instantiate makes the shared memory, with BigInt page counts on memory64, or takes the one a worker is given.
  • run.mjs passes Node's worker_threads and os to the host.
  • readStr copies the bytes of a shared memory before decoding them, because a browser's TextDecoder rejects a view of a SharedArrayBuffer.
  • run_tests.mjs no longer skips thread tests. README.md has a new "Threads" section, which also states the limits:
    • Node only: a browser can't block its main thread in join, and shares memory only on a cross-origin-isolated page;
    • per-thread host state (regex matches, async tasks, exceptions in flight) stays on its thread.

Default library

No source change, but the wasm archives must be rebuilt with this compiler (scripts\build_wasm.bat). Archives with the old 4-byte header must not be linked with code built with the 8-byte one. I rebuilt them locally for these runs.

Tests

  • Native ctest: 6976/6976.
  • The default library's thread tests: thread_spawn, thread_move, worker_echo, worker_errors, worker_objects, worker_terminate and atomics_wait.
    • They now run and pass on every leg. atomics.ts passes again on wasm32.
    • I ran each of them 20 times on each of the six legs: 840 runs, all passing.
  • wasm suites, wasm32 and wasm64:
Suite none / rc own
tester 652 pass 486 pass
defaultlib none 206, rc 207 (was 198 / 199) 206 pass (was 198)
  • Release passes on every leg. Debug passes too, except one failure, which I could not reproduce:

    • 00owned_iteration.ts (wasm32, rc, debug) failed an assertion, the same way in all 5 runs of that one build;
    • rebuilt, it passed in 31 builds, and two further runs of the wasm32 debug tester legs passed in full.

    My guess is unproven: a constant array's global is named from a hash of attribute pointers (calc_hash_value), which changes from run to run, so a collision could give one constant array another's data.

  • Browser: index.html still runs a wasm32 and a wasm64 program that starts no thread, in Chromium (the app's browser pane).

🤖 Generated with Claude Code

ASDAlexander77 and others added 5 commits November 12, 2026 00:12
wasm32/wasm64 (not Emscripten) compile with the exception-handling feature and the wasm exception
model, set before the target machine is made (its MCAsmInfo takes it from there; without it every
invoke was lowered to a call).

WasmExceptionPass turns each Itanium landing pad into a catch-all catchpad left at once
(catchswitch, catchpad [ptr null], llvm.wasm.get.exception, catchret), so the code after the pad
runs as ordinary code, as it does on Linux; `resume` becomes llvm.wasm.throw. What the personality
would decide is decided after the catch: a pad's selector is the first clause that takes the
exception (__tslang_wasm_catches: the same type, or a base class's pointer), a pad of typed clauses
only rethrows what none takes, and a matched pointer clause binds the thrown pointer. The C++
runtime's type_infos and type_info vtables get definitions, so each has an address of its own.

The JS host imports the __cpp_exception tag (i32 or i64, read from the module by
host.instantiate), throws a WebAssembly.Exception of it from __cxa_throw, and keeps begin/end catch
and rethrow as libc++abi does. It also maps Node's ERR_FS_* codes and refuses an environment name
with '='.

run_tests.mjs no longer skips tests that catch; json.ts under none is listed (5 GB of strings).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… host

The host implements MLIR's mlirAsyncRuntime* API on the program's one thread, and
run() drains the tasks still queued after main. wasm64 function pointers go through
a BigInt table index (functionAt). New imports: aligned_alloc, std_this_thread_sleep_for.
MemAllocFixPass no longer erases a malloc/realloc/free declaration that is still called
(the coroutine frame's free): its calls go to the ts_ function, else it is kept.
run_tests.mjs no longer skips async tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nto wasm-async

# Conflicts:
#	docs/how/wasm/test/README.md
#	docs/how/wasm/test/host.mjs
#	docs/how/wasm/test/run_tests.mjs
#	docs/how/wasm/test/wasm_skips.txt
A program that calls tslang_thread_spawn is linked with --shared-memory
--import-memory (and a maximum, and __stack_pointer exported); every wasm object
is compiled with +atomics,+bulk-memory, which a shared memory needs. The host
starts each thread in a Node worker (thread.mjs) on the same module and memory;
join waits with Atomics.wait. The host's heap moves into the module's memory
behind a lock. Atomics.wait/notify import functions.

wasm32: a heap block's header is 8 bytes (CompileOptions::heapBlockHeaderBytes),
so a payload of 64-bit elements is 8-aligned: a real 64-bit atomic traps on a
4-aligned address. The count stays an index-sized word at the block's start; the
static layouts (string literals, constant arrays, static array headers, stack
blocks, the type descriptor's block word) widen. Other targets are unchanged.

run_tests.mjs no longer skips thread tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Base automatically changed from wasm-async to main November 12, 2026 08:42
…nto wasm-threads

# Conflicts:
#	docs/how/wasm/test/README.md
#	docs/how/wasm/test/host.mjs
#	docs/how/wasm/test/run_tests.mjs
#	docs/how/wasm/test/wasm_skips.txt
@ASDAlexander77
ASDAlexander77 merged commit 05f98ca into main Nov 12, 2026
8 checks passed
@ASDAlexander77
ASDAlexander77 deleted the wasm-threads branch November 12, 2026 09:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant