@woosh/meep-engine 2.169.4 → 2.170.0

package/src/engine/ecs/async/WorkerSystem.js

@@ -0,0 +1,702 @@
+import { assert } from "../../../core/assert.js";
+import { computeSystemName } from "../computeSystemName.js";
+import { System } from "../System.js";
+import {
+    WORKER_SYSTEM_NO_TICK,
+    WorkerSystemControl,
+    worker_system_allocate_shared,
+    worker_system_command_view,
+    worker_system_control_view
+} from "./WorkerSystemProtocol.js";
+
+/**
+ * Milliseconds to wait for the worker's boot handshake before giving up. Long
+ * enough to cover a cold module-worker load on a slow connection, short enough
+ * that a genuinely broken entry point fails the system's startup rather than
+ * hanging it. {@link EntityManager} warns about slow startups at 5 s.
+ * @type {number}
+ */
+const DEFAULT_READY_TIMEOUT_MS = 15000;
+
+/**
+ * Milliseconds {@link WorkerSystem.shutdown} waits for in-flight work to settle
+ * before terminating the worker anyway.
+ * @type {number}
+ */
+const DEFAULT_SETTLE_TIMEOUT_MS = 1000;
+
+/**
+ * Milliseconds a single step may stay outstanding before the bridge is declared
+ * dead. This is the watchdog that keeps a hung worker from freezing the
+ * simulation forever: the gate blocks while a step is in flight, and a worker
+ * that hangs (infinite loop in the core, killed by the browser under memory
+ * pressure, a protocol desync) fires no `error` event, so without a deadline
+ * there would be no path back. Generous enough that ordinary slowness never
+ * trips it — slowness is handled by deferring steps, not by failing.
+ * @type {number}
+ */
+const DEFAULT_STEP_DEADLINE_MS = 2000;
+
+/**
+ * How many consecutive blocked gate checks before warning that the worker
+ * cannot sustain the fixed rate. At 60 Hz this is about two seconds of the
+ * simulation running slower than real time.
+ * @type {number}
+ */
+const BLOCKED_CYCLES_BEFORE_WARNING = 120;
+
+/**
+ * Returned by {@link WorkerSystem.postToWorker} when the message could not be
+ * sent. Never acknowledged, so {@link WorkerSystem.isMessageHandled} reports
+ * `false` for it rather than reporting a dropped message as delivered.
+ * @type {number}
+ */
+export const WORKER_SYSTEM_MESSAGE_NOT_SENT = -1;
+
+/**
+ * How many `Atomics.load` probes to run between wall-clock samples while
+ * spinning. `performance.now()` is itself expensive enough that sampling it per
+ * probe would dominate a short spin.
+ * @type {number}
+ */
+const SPIN_PROBES_PER_CLOCK_SAMPLE = 64;
+
+/**
+ * A {@link System} whose per-tick work runs on a worker thread over shared
+ * memory, with a **synchronous** hot path.
+ *
+ * Each fixed tick `T` the system does exactly two things:
+ *
+ *   1. **join** step `T - 1` — already guaranteed complete by the fixed-step
+ *      gate, so this is a load and an {@link apply} call, not a wait;
+ *   2. **dispatch** step `T` — {@link collect} writes the command words, then a
+ *      single `Atomics.store` publishes the request.
+ *
+ * Between dispatch and the next join **the worker owns the shared state** and
+ * the main thread must not touch it. That is made safe for the simulation by a
+ * gate registered with {@link EntityManager}: the fixed loop will not advance
+ * into tick `T + 1` until step `T` has landed, so every system's `fixedUpdate`
+ * runs with the worker idle. Subclasses must document the same constraint for
+ * any main-thread reader outside the fixed pass.
+ *
+ * Exactly one step is in flight at a time — see {@link #in_flight} for why that
+ * is structural rather than a tuning choice.
+ *
+ * Nothing here is `async` on the hot path, deliberately. `await` always defers
+ * its continuation to a microtask, so an `async fixedUpdate` could never consume
+ * a result during the pass even when shared memory shows it has been ready for
+ * milliseconds; the coroutine form would buy syntax while costing the manager's
+ * synchronous-pass guarantees. See `ASYNC_SYSTEMS_PROPOSAL.md`.
+ *
+ * Subclasses implement:
+ *
+ *   - {@link createWorker} — spawn the worker (kept as a hook so the spawn
+ *     expression, which needs `import.meta.url` under webpack, stays out of any
+ *     module a test might import);
+ *   - {@link collect} — on-tick, prepare shared state and command words;
+ *   - {@link apply} — on-tick, integrate a completed step;
+ *   - optionally {@link buildBootPayload}, {@link handleWorkerMessage}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WorkerSystem extends System {
+
+    /**
+     * Milliseconds the fixed-step gate spins waiting for a result before giving
+     * up on this cycle.
+     *
+     * Spinning is worth a little because a worker that is *nearly* done costs
+     * far less here than a whole ticker cycle of delay. When the budget expires
+     * the fixed loop simply breaks with the accumulator loaded, and catches up
+     * on a later call — the wait affects wall-clock pacing only, never which
+     * state a tick computes.
+     *
+     * @type {number}
+     */
+    join_spin_budget_ms = 0.25;
+
+    /**
+     * Size of the command region, in `Float64` words.
+     * @type {number}
+     */
+    command_word_count = 16;
+
+    /**
+     * Milliseconds a step may stay outstanding before the bridge is failed.
+     * @see DEFAULT_STEP_DEADLINE_MS
+     * @type {number}
+     */
+    step_deadline_ms = DEFAULT_STEP_DEADLINE_MS;
+
+    /** @type {Worker|null} */
+    #worker = null;
+
+    /** @type {SharedArrayBuffer|null} */
+    #buffer = null;
+
+    /** @type {Int32Array|null} */
+    #control = null;
+
+    /** @type {Float64Array|null} */
+    #command = null;
+
+    /**
+     * The dispatched-but-unjoined tick, or {@link WORKER_SYSTEM_NO_TICK}.
+     *
+     * **Exactly one step is ever in flight**, which is a property of the
+     * ownership model rather than a tuning choice. The worker mutates shared
+     * state in place, so the main thread cannot prepare a second step's input
+     * while the first is running — there is nowhere to put it. It also could not
+     * publish one if it wanted to: {@link WorkerSystemControl.REQ} holds a single
+     * tick, so a second dispatch before the worker consumed the first would
+     * silently replace it and drop a step.
+     *
+     * A deeper pipeline would need double-buffered payloads and a request queue.
+     * That is a different design, not a knob on this one.
+     *
+     * @type {number}
+     */
+    #in_flight = WORKER_SYSTEM_NO_TICK;
+
+    /**
+     * Latest tick whose result has been handed to {@link apply}.
+     * @type {number}
+     */
+    #last_joined = WORKER_SYSTEM_NO_TICK;
+
+    /**
+     * Cold-plane messages posted so far, mirrored into
+     * {@link WorkerSystemControl.MSG_SEQ}.
+     * @type {number}
+     */
+    #message_sequence = 0;
+
+    /**
+     * Set when the bridge is unusable — the worker died, failed to boot, or a
+     * step threw. A failed system stops dispatching and its gate stops blocking,
+     * so a broken worker degrades the feature instead of freezing the game.
+     * @type {boolean}
+     */
+    #failed = false;
+
+    /** @type {boolean} */
+    #gate_registered = false;
+
+    /**
+     * `performance.now()` at the moment the outstanding step was dispatched.
+     * @type {number}
+     */
+    #dispatch_time = 0;
+
+    /**
+     * Consecutive gate checks that have refused to advance.
+     * @type {number}
+     */
+    #blocked_cycles = 0;
+
+    /** @type {boolean} */
+    #slow_worker_reported = false;
+
+    /**
+     * @returns {boolean} whether the bridge is live.
+     */
+    get is_worker_alive() {
+        return this.#worker !== null && !this.#failed;
+    }
+
+    /**
+     * @returns {number} latest tick whose result has been applied.
+     */
+    get last_joined_tick() {
+        return this.#last_joined;
+    }
+
+    /**
+     * Whether a step is currently outstanding — equivalently, whether the worker
+     * currently owns the shared state. Subclasses should expose this rather than
+     * tracking ownership separately, so the two cannot disagree (in particular
+     * after a failure, where no join ever happens).
+     *
+     * @returns {boolean}
+     */
+    get is_step_in_flight() {
+        return this.#in_flight !== WORKER_SYSTEM_NO_TICK;
+    }
+
+    // ────────────────────────────────────────────────────────────────────────
+    // Subclass surface
+    // ────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Create the worker. Called once during {@link startup}.
+     *
+     * Under webpack the idiomatic body is
+     * `new Worker(new URL("./x.worker.js", import.meta.url), { type: "module" })`
+     * — keep that expression in a module no test imports, because `import.meta`
+     * is a parse error under the CommonJS transform Jest uses.
+     *
+     * @returns {Worker}
+     */
+    createWorker() {
+        throw new Error(`${computeSystemName(this)}: createWorker() must be overridden`);
+    }
+
+    /**
+     * One-off payload delivered with the boot message, before the worker reports
+     * ready.
+     * @returns {*}
+     */
+    buildBootPayload() {
+        return null;
+    }
+
+    /**
+     * Prepare shared state and write the command words for tick `tick`. Runs
+     * on-tick with the worker idle, so it has exclusive access to everything the
+     * worker touches.
+     *
+     * @param {Float64Array} command
+     * @param {number} tick
+     * @param {number} time_delta_seconds
+     * @returns {boolean} `false` to skip dispatching this tick
+     */
+    collect(command, tick, time_delta_seconds) {
+        return true;
+    }
+
+    /**
+     * Integrate the result of `tick`. Runs on-tick, at this system's position in
+     * the execution order, with the worker idle.
+     *
+     * Bridges whose results live entirely in shared memory (the worker mutated
+     * them in place) have nothing to do here.
+     *
+     * @param {number} tick
+     */
+    apply(tick) {
+        // override as necessary
+    }
+
+    /**
+     * A cold-plane message from the worker. `{type: "ready"}` and
+     * `{type: "error"}` are consumed by the base class and never reach this.
+     * @param {*} data
+     */
+    handleWorkerMessage(data) {
+        // override as necessary
+    }
+
+    // ────────────────────────────────────────────────────────────────────────
+    // Lifecycle
+    // ────────────────────────────────────────────────────────────────────────
+
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async startup(entityManager) {
+        // A system may be restarted after shutdown (EntityManager.addSystem
+        // accepts STOPPED systems), and startup allocates a FRESH buffer whose
+        // counters begin at zero. Every piece of per-life state has to be reset
+        // with it, or the two sides disagree forever: a surviving
+        // #message_sequence would sit permanently ahead of the new worker's ack
+        // count, and a surviving #failed would keep a healthy bridge disabled.
+        this.#failed = false;
+        this.#message_sequence = 0;
+        this.#in_flight = WORKER_SYSTEM_NO_TICK;
+        this.#last_joined = WORKER_SYSTEM_NO_TICK;
+        this.#blocked_cycles = 0;
+        this.#slow_worker_reported = false;
+
+        this.#buffer = worker_system_allocate_shared(this.command_word_count);
+        this.#control = worker_system_control_view(this.#buffer);
+        this.#command = worker_system_command_view(this.#buffer);
+
+        const worker = this.createWorker();
+
+        this.#worker = worker;
+
+        await new Promise((resolve, reject) => {
+            let settled = false;
+
+            const timeout = setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+
+                settled = true;
+
+                this.#fail(`worker did not report ready within ${DEFAULT_READY_TIMEOUT_MS}ms`);
+
+                reject(new Error(
+                    `${computeSystemName(this)}: worker did not report ready within ${DEFAULT_READY_TIMEOUT_MS}ms`
+                ));
+            }, DEFAULT_READY_TIMEOUT_MS);
+
+            worker.onmessage = (event) => {
+                const data = event.data;
+
+                if (data !== null && typeof data === "object" && data.type === "ready") {
+                    if (settled) {
+                        return;
+                    }
+
+                    settled = true;
+                    clearTimeout(timeout);
+
+                    if (this.#failed) {
+                        // An error arrived before ready did. Booting "successfully"
+                        // here would register a gate for a bridge that can never
+                        // dispatch.
+                        reject(new Error(`${computeSystemName(this)}: worker reported an error before it was ready`));
+
+                        return;
+                    }
+
+                    resolve();
+
+                    return;
+                }
+
+                if (data !== null && typeof data === "object" && data.type === "error") {
+                    this.#fail(`step ${data.tick} threw in the worker: ${data.message}\n${data.stack}`);
+
+                    return;
+                }
+
+                this.handleWorkerMessage(data);
+            };
+
+            worker.onerror = (event) => {
+                this.#fail(`worker error: ${event && event.message ? event.message : event}`);
+
+                if (settled) {
+                    return;
+                }
+
+                settled = true;
+                clearTimeout(timeout);
+                reject(new Error(`${computeSystemName(this)}: worker failed to start`));
+            };
+
+            worker.postMessage({
+                type: "boot",
+                buffer: this.#buffer,
+                payload: this.buildBootPayload()
+            });
+        });
+
+        entityManager.registerFixedStepGate(this);
+        this.#gate_registered = true;
+    }
+
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async shutdown(entityManager) {
+        // Settle FIRST, while the gate is still registered: until the worker has
+        // finished, it still owns the shared state, and releasing the gate early
+        // would let the fixed loop advance other systems over memory that is
+        // being written.
+        if (this.#control !== null) {
+            await this.#settle();
+        }
+
+        if (this.#gate_registered) {
+            entityManager.unregisterFixedStepGate(this);
+            this.#gate_registered = false;
+        }
+
+        this.#terminate_worker();
+
+        this.#control = null;
+        this.#command = null;
+        this.#buffer = null;
+        this.#in_flight = WORKER_SYSTEM_NO_TICK;
+        this.#last_joined = WORKER_SYSTEM_NO_TICK;
+    }
+
+    // ────────────────────────────────────────────────────────────────────────
+    // Hot path
+    // ────────────────────────────────────────────────────────────────────────
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    fixedUpdate(time_delta_seconds) {
+        const control = this.#control;
+
+        if (control === null || this.#failed) {
+            return;
+        }
+
+        const tick = this.entityManager.fixedStepTick;
+
+        const join_tick = this.#in_flight;
+
+        if (join_tick !== WORKER_SYSTEM_NO_TICK) {
+            // The gate does not let a tick begin while a step is outstanding, so
+            // by construction the result is already published. Kept on one line
+            // and free of semicolons so the production build's assert-stripping
+            // pattern can actually remove it.
+            assert.ok(Atomics.load(control, WorkerSystemControl.DONE) >= join_tick, `step ${join_tick} still in flight at tick ${tick} - the fixed-step gate was bypassed`);
+
+            this.#in_flight = WORKER_SYSTEM_NO_TICK;
+            this.#last_joined = join_tick;
+
+            if (Atomics.load(control, WorkerSystemControl.ERR) !== 0) {
+                // Details already arrived on the cold plane and called #fail.
+                // Stop rather than applying a result that was never produced.
+                // #in_flight is already cleared, so ownership has been released
+                // even though no apply() ran.
+                this.#fail(`step ${join_tick} failed in the worker`);
+
+                return;
+            }
+
+            this.apply(join_tick);
+        }
+
+        if (this.collect(this.#command, tick, time_delta_seconds) === false) {
+            return;
+        }
+
+        this.#in_flight = tick;
+        this.#dispatch_time = performance.now();
+
+        Atomics.store(control, WorkerSystemControl.REQ, tick);
+        Atomics.notify(control, WorkerSystemControl.REQ);
+    }
+
+    /**
+     * Fixed-step gate consulted by {@link EntityManager} before it advances the
+     * simulation. Returns whether the result this system will need at
+     * `next_tick` is available.
+     *
+     * Every "not available" path must be transient, or the simulation freezes.
+     * The gate opens unconditionally when the bridge has failed and whenever
+     * nothing is in flight — which covers priming and ticks {@link collect}
+     * declined.
+     *
+     * `next_tick` is unused: the invariant is that no step is outstanding when a
+     * tick begins, which does not depend on which tick is next.
+     *
+     * @param {number} next_tick
+     * @returns {boolean}
+     */
+    may_advance(next_tick) {
+        const control = this.#control;
+
+        if (control === null || this.#failed) {
+            return true;
+        }
+
+        const need = this.#in_flight;
+
+        if (need === WORKER_SYSTEM_NO_TICK) {
+            return true;
+        }
+
+        if (Atomics.load(control, WorkerSystemControl.DONE) >= need) {
+            this.#blocked_cycles = 0;
+
+            return true;
+        }
+
+        if (this.#spin_for(need)) {
+            this.#blocked_cycles = 0;
+
+            return true;
+        }
+
+        // Everything below turns "blocked" into something observable. Blocking
+        // is the one way this class can stop the simulation, so it must never be
+        // both permanent and silent.
+        const waited = performance.now() - this.#dispatch_time;
+
+        if (waited > this.step_deadline_ms) {
+            // The worker is not merely slow, it has stopped answering: a hung
+            // core, or a worker the browser killed without an error event.
+            // Failing opens the gate unconditionally, so the simulation resumes
+            // without this system rather than freezing with it.
+            this.#fail(`step ${need} did not complete within ${this.step_deadline_ms}ms; treating the worker as hung`);
+
+            return true;
+        }
+
+        this.#blocked_cycles++;
+
+        if (this.#blocked_cycles >= BLOCKED_CYCLES_BEFORE_WARNING && !this.#slow_worker_reported) {
+            this.#slow_worker_reported = true;
+
+            console.warn(
+                `${computeSystemName(this)}: the worker cannot sustain the fixed step rate, so the simulation is`
+                + ` running slower than real time. A gated system advances at most one fixed step per simulate()`
+                + ` call, so this debt is not recoverable — reduce the per-step work or raise fixedUpdateStepSize.`
+            );
+        }
+
+        return false;
+    }
+
+    // ────────────────────────────────────────────────────────────────────────
+    // Cold plane
+    // ────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Send a structural message to the worker and wake its pump so the message
+     * can actually be delivered (a worker parked in `Atomics.wait` never runs its
+     * event loop).
+     *
+     * Rare by design — every cold-plane post costs the worker a scheduling round
+     * trip.
+     *
+     * @param {*} message
+     * @param {Transferable[]} [transfer]
+     * @returns {number} sequence number; pass to {@link isMessageHandled} to tell
+     *                   when the worker has consumed it
+     */
+    postToWorker(message, transfer) {
+        if (this.#worker === null || this.#failed) {
+            return WORKER_SYSTEM_MESSAGE_NOT_SENT;
+        }
+
+        if (transfer === undefined) {
+            this.#worker.postMessage(message);
+        } else {
+            this.#worker.postMessage(message, transfer);
+        }
+
+        this.#message_sequence++;
+
+        Atomics.store(this.#control, WorkerSystemControl.MSG_SEQ, this.#message_sequence);
+        Atomics.notify(this.#control, WorkerSystemControl.REQ);
+
+        return this.#message_sequence;
+    }
+
+    /**
+     * @param {number} sequence value returned by {@link postToWorker}
+     * @returns {boolean} whether the worker has consumed that message
+     */
+    isMessageHandled(sequence) {
+        if (this.#control === null || sequence === WORKER_SYSTEM_MESSAGE_NOT_SENT) {
+            return false;
+        }
+
+        return Atomics.load(this.#control, WorkerSystemControl.ACK_SEQ) >= sequence;
+    }
+
+    // ────────────────────────────────────────────────────────────────────────
+    // Internals
+    // ────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Spin until the worker publishes `need`, or the budget runs out.
+     *
+     * @param {number} need
+     * @returns {boolean}
+     */
+    #spin_for(need) {
+        const control = this.#control;
+        const deadline = performance.now() + this.join_spin_budget_ms;
+
+        do {
+            for (let i = 0; i < SPIN_PROBES_PER_CLOCK_SAMPLE; i++) {
+                if (Atomics.load(control, WorkerSystemControl.DONE) >= need) {
+                    return true;
+                }
+            }
+        } while (performance.now() < deadline);
+
+        return false;
+    }
+
+    /**
+     * Wait for in-flight work to settle, bounded. Asynchronous — this runs
+     * during shutdown, off the hot path, where yielding is free and spinning
+     * would just block teardown.
+     *
+     * @returns {Promise<void>}
+     */
+    #settle() {
+        const control = this.#control;
+        const target = this.#in_flight;
+
+        if (target === WORKER_SYSTEM_NO_TICK || Atomics.load(control, WorkerSystemControl.DONE) >= target) {
+            return Promise.resolve();
+        }
+
+        return new Promise((resolve) => {
+            const deadline = performance.now() + DEFAULT_SETTLE_TIMEOUT_MS;
+
+            const poll = () => {
+                if (Atomics.load(control, WorkerSystemControl.DONE) >= target) {
+                    resolve();
+
+                    return;
+                }
+
+                if (performance.now() > deadline) {
+                    console.warn(
+                        `${computeSystemName(this)}: worker did not settle within ${DEFAULT_SETTLE_TIMEOUT_MS}ms,`
+                        + ` terminating with step ${target} in flight`
+                    );
+
+                    resolve();
+
+                    return;
+                }
+
+                setTimeout(poll, 1);
+            };
+
+            poll();
+        });
+    }
+
+    /**
+     * @param {string} reason
+     */
+    #fail(reason) {
+        if (this.#failed) {
+            return;
+        }
+
+        this.#failed = true;
+
+        // Release ownership of the shared state. Without this, a failure seen
+        // from the cold plane (rather than at join) would leave #in_flight set
+        // forever, and is_step_in_flight — which subclasses key their ownership
+        // contract on — would answer "the worker is still writing" for the rest
+        // of the session.
+        this.#in_flight = WORKER_SYSTEM_NO_TICK;
+
+        console.error(`${computeSystemName(this)}: worker bridge failed — ${reason}`);
+
+        // A failed bridge is never dispatched to again, so a worker left running
+        // only burns a thread and pins the shared buffer.
+        this.#terminate_worker();
+    }
+
+    /**
+     * Ask the worker's pump to stop and drop the thread. Idempotent.
+     */
+    #terminate_worker() {
+        if (this.#control !== null) {
+            Atomics.store(this.#control, WorkerSystemControl.QUIT, 1);
+            Atomics.notify(this.#control, WorkerSystemControl.REQ);
+        }
+
+        if (this.#worker === null) {
+            return;
+        }
+
+        this.#worker.onmessage = null;
+        this.#worker.onerror = null;
+        this.#worker.terminate();
+        this.#worker = null;
+    }
+}