Shared-Memory Threads #

Status: active Last reviewed: 2026-10-19 Owner: theMackabu

Goal #

Give Ant programs shared-memory parallelism with a new Thread(fn) API in the spirit of WebKit's "Concurrent JavaScript: It can work!" (2017), built on the isolate-per-thread runtime instead of one shared heap. Programs share fixed-layout objects, arrays, mutexes and conditions by reference across threads and workers. Code that never touches shared objects must not get slower: no new checks on ordinary property, call or allocation fast paths.

Background and Direction #

The WebKit design shares the whole heap: any object can be reshaped from any thread. That needs transition-thread-locality tags in pointer bits, segmented butterflies, buffered inline-cache updates and a multi-mutator GC; WebKit estimated ~7x for transitions on shared objects and ~2x for their other accesses, and never shipped it (bug 174276). In Ant it would reverse the isolate ownership work in worker-threads-isolates.md:

• ant_t *js appears ~5,300 times in 212 files and mixes per-thread state (vm, this_val, current_func, exception state) with heap state (object list, arenas, shapes, intern table, GC).
• ant_object_t holds shape and overflow_prop as separate words, so a transition is two non-atomic stores; arrays reallocate u.array.data; every allocation links into the isolate's objects list.
• The GC is stop-the-world with one mutator; ICs, feedback sidecars, MIR code, rope flattening and interning all mutate without synchronization.

Fixed-layout shared objects remove the hardest part (concurrent reshaping). Ant is well placed for them because every isolate lives in one pointer cage: a NaN-boxed reference to a shared region means the same thing in every isolate, with no handle translation.

The reference semantics are V8's experimental shared structs (Node 22, node --harmony-struct), checked on 2026-10-19:

• new SharedStructType(['x', 'y']) returns a constructor; instances have a null prototype, are sealed and non-extensible; adding a field throws TypeError: Cannot add property z, object has fixed layout.
• Fields accept undefined, null, booleans, numbers, strings and shared objects; BigInt, Symbol, ordinary objects, arrays, functions and even SharedArrayBuffer throw TypeError: ... cannot be shared.
• new SharedArray(n) is fixed length, filled with undefined; out-of-range stores throw the fixed-layout error.
• Atomics.Mutex.lock(m, fn) returns fn(); also tryLock, lockWithTimeout, isMutex. Atomics.Condition.wait(c, m[, timeout]), notify(c[, count]), isCondition.
• Shared objects keep identity through workerData and postMessage.

API #

import { Thread, Lock, Condition, ThreadLocal } from 'ant:thread';

const Counter = new SharedStructType(['value', 'lock']);
const counter = new Counter();
counter.value = 0;
counter.lock = new Lock();

const workers = Array.from({ length: 4 }, () =>
  new Thread((c, n) => {
    for (let i = 0; i < n; i++) c.lock.hold(() => { c.value++; });
    return c.value;
  }, counter, 1e5));

await Promise.all(workers.map(t => t.asyncJoin()));

• new Thread(fn, ...args) runs fn(...args) on a new isolate thread. fn must be closure-free (no captured upvalues, not bound, not native); the constructor throws TypeError otherwise. Its source is re-evaluated in the child, like a worker eval entry. Shared objects in args pass by reference; everything else is structured-cloned.
• thread.join() blocks and returns the result or rethrows; allowed on any thread, matching Atomics.wait on Node's main thread. thread.asyncJoin() returns a promise. Thread.current is the calling thread's Thread (the main thread has one too).
• Lock and Condition are WebKit's names over Atomics.Mutex and Atomics.Condition: lock.hold(fn), lock.asyncHold(), cond.wait(lock), cond.asyncWait(lock), cond.notify(), cond.notifyAll().
• ThreadLocal exposes value per isolate. In the isolate model every global is already thread-local; it exists for API parity.
• Thread.restrict from the WebKit design is not needed: ordinary objects can never cross threads.

Phases #

Each phase lands separately with tests, TSan on the thread tests and the GC gauntlet (fixture, apps2, v8fixed) showing no instruction-count regression.

1. Shared synchronization objects #

• Atomics.Mutex and Atomics.Condition as refcounted native objects living outside any isolate, wire-serialized by reference like SharedArrayBuffer blocks, so they work with Worker, worker_threads and later Thread.
• Blocking waits reuse the futex-style wait queue in src/modules/atomics.c; async waits reuse the waitAsync path (uv_async_t per waiter). Waiting stays interruptible by terminate() through atomics_wake_isolate.
• Lock/Condition wrappers and the ant:thread module skeleton.
• Acceptance: Node --harmony-struct parity for lock, tryLock, lockWithTimeout, wait, notify across workers; a contention test.

2. new Thread(fn) on isolates #

• A third front end in src/modules/worker/ (thread.c) on worker_ops_t: entry is the function source plus a wire of the arguments; the result or error comes back through the existing event queue.
• Closure-free check: sv_closure_t with no upvalues, no bound_argc, not a cfunc; class constructors and generators rejected for now.
• Cost note: each Thread creates an isolate (milliseconds). A follow-up can pool idle isolates; measure before deciding.
• Acceptance: join/asyncJoin/error propagation/terminate tests; TSan.

3. Shared arena and SharedStructType #

• A process-wide fixed arena in the cage for shared objects, with its own arena id in the owner table so fixed_arena_holds_offset keeps isolates' marking from treating shared offsets as their own. Allocation is a lock-protected bump/free-list first; per-thread allocation buffers only if profiles demand it.
• SharedStructType(fields) creates an immutable layout (field names interned into a shared, immutable name table); instances store a layout pointer and n 64-bit field slots. Loads and stores are relaxed 64-bit atomics, which matches the SharedArrayBuffer memory model.
• Storable values follow V8. Strings are copied into an immutable shared string region on store (flattened; ropes never enter shared space), so a shared field never points into an isolate heap and no cross-heap write barrier is needed.
• Property access from JS goes through exotic ops on the struct object (ANT_EXOTIC path), so ordinary objects keep their fast paths untouched.
• GC: isolates treat shared offsets as leaves. A shared collection requests a global safepoint through the existing interrupt_pending mechanism, each isolate reports the shared offsets it reaches from its roots and heap, then one thread marks and sweeps the shared arena and releases the isolates. Triggered by shared-allocation volume, never by an isolate's own GC.
• Acceptance: Node --harmony-struct parity on the semantics listed above; identity across postMessage; a GC stress test with threads holding and dropping references; TSan and ASan.

4. SharedArray #

• Fixed-length shared element storage in the same arena with the same value rules; length immutable, out-of-range stores throw.
• Atomics.load/store/exchange/compareExchange/add extended to struct fields and SharedArray elements (WebKit's object-plus-key Atomics idea), with Atomics.wait/notify on them for lock-free algorithms.

5. JIT fast paths #

• Struct layouts are immutable, so a property IC keyed by layout pointer resolves to a fixed slot offset forever; the template JIT and opt tier emit a layout compare plus one load/store. No transitions, no watchpoints.
• Acceptance: a microbenchmark of field updates under Lock and a lock-free Atomics.add counter; no change on the non-shared gauntlet.

6. Research: shared-heap Thread (closures across threads) #

Only if phases 1–5 show demand for capturing closures. Go/no-go needs a prototype with at most 1% serial overhead on the gauntlet. Prerequisites:

• Split ant_t into a heap (ant_heap_t: arenas, object list, shapes, intern table, GC) and a per-thread context (vm, exception, call state).
• Multi-mutator GC: per-thread allocation buffers in the fixed arenas, safepoints at back-edges and allocation, conservative scanning of every thread stack.
• Object model: owner-thread tags in the high bits of overflow_prop (TTL), a segmented overflow layout for objects reshaped by a non-owner, CAS on array storage growth, dictionary-mode reads under a shape lock.
• Per-code-unit "ran on one thread" bits, buffered IC/feedback updates flushed at safepoints, and thread-safe rope flattening and interning.

Decisions #

• Build on isolates plus shared objects, not a shared heap; keep the WebKit Thread/Lock/Condition API on top.
• Follow V8's experimental shared-struct semantics where they exist so code can move between Ant and Node --harmony-struct.
• Shared objects never reference isolate heaps; that is what keeps ordinary code free of new barriers and checks.

Open Questions #

• ant:thread module (recommended, avoids a non-standard global) or a global Thread.
• Whether SharedStructType and SharedArray stay global like V8 or move under ant:thread until TC39 settles the shared struct syntax.
• Isolate pooling for Thread startup cost.

Risks #

• Shared-space GC pauses stop every isolate; keep collections rare and measure pause time with many threads.
• Struct field access through exotic ops is slower than ordinary objects until phase 5.
• String copying on store costs memory for large strings; revisit with shared string interning if profiles show it.

Validation Plan #

• Per phase: focused tests in tests/, parity runs against node --harmony-struct where the API exists, TSan for every thread test, ASan for the shared arena and GC, and the GC gauntlet for regressions.