From 104c12886f0347f9558ab6ba4c719063afd35ba5 Mon Sep 17 00:00:00 2001 From: TJKoury Date: Mon, 16 Nov 2026 15:12:32 -0500 Subject: [PATCH 1/3] Expose browser thread pool arming timeout and report Co-Authored-By: Codex --- src/host/browserModuleHarness.js | 13 +++++++++++++ src/index.d.ts | 7 +++++++ 2 files changed, 20 insertions(+) diff --git a/src/host/browserModuleHarness.js b/src/host/browserModuleHarness.js index cb1a2f3..b18903d 100644 --- a/src/host/browserModuleHarness.js +++ b/src/host/browserModuleHarness.js @@ -429,6 +429,7 @@ async function instantiateBrowserModule(options = {}) { // the module will actually ask for. Ignored by the Node lazy path. requestedThreads: options.maxThreads, poolSize: options.wasiThreadPoolSize, + probeTimeoutMs: options.wasiThreadProbeTimeoutMs, hostcallChannel: options.threadHostcallChannel, requiresHostcalls: needsHostBridge, enableBrowserThreads: options.enableBrowserWasiThreads, @@ -485,8 +486,14 @@ async function instantiateBrowserModule(options = {}) { * @param {number} [options.wasiThreadSpawnWaitMs] - How long a guest spawn that * finds every pooled thread busy waits for one to finish before * pthread_create fails (createWasiThreadSpawn `spawnWaitMs`, default 250). + * @param {number} [options.wasiThreadProbeTimeoutMs] - Positive finite browser + * pool arming deadline in milliseconds (default 1500). */ export async function createBrowserModuleHarness(options = {}) { + if (options.wasiThreadProbeTimeoutMs !== undefined && + (!Number.isFinite(options.wasiThreadProbeTimeoutMs) || options.wasiThreadProbeTimeoutMs <= 0)) { + throw new Error("wasiThreadProbeTimeoutMs must be a positive finite number."); + } let wasmSource = options.wasmSource; const signaturePolicy = resolveModuleSignaturePolicy(options); // Bytes THIS function materializes itself (Response/URL fetch, or the @@ -596,6 +603,7 @@ export async function createBrowserModuleHarness(options = {}) { wasiThreadWorkerUrl: options.wasiThreadWorkerUrl, wasiThreadSpawnWaitMs: options.wasiThreadSpawnWaitMs, wasiThreadPoolSize: options.wasiThreadPoolSize, + wasiThreadProbeTimeoutMs: options.wasiThreadProbeTimeoutMs, }); const { instance, bridge, wasi, memory, threadHost } = activeContext; let lastCommandContext = null; @@ -862,6 +870,7 @@ export async function createBrowserModuleHarness(options = {}) { wasiThreadWorkerUrl: options.wasiThreadWorkerUrl, wasiThreadSpawnWaitMs: options.wasiThreadSpawnWaitMs, wasiThreadPoolSize: options.wasiThreadPoolSize, + wasiThreadProbeTimeoutMs: options.wasiThreadProbeTimeoutMs, }); lastCommandContext = commandContext; let exitError = null; @@ -974,6 +983,10 @@ export async function createBrowserModuleHarness(options = {}) { // spawn host so callers can observe real thread activity // (spawnCount/distinctOsThreadCount). get threadHost() { return lastCommandContext?.threadHost ?? threadHost; }, + get wasiThreadPoolReport() { + const report = (lastCommandContext?.threadHost ?? threadHost)?.spawnReport(); + return report ? Object.freeze({ requested: report.poolSize, armed: report.armed }) : null; + }, callHost, invokeDirect, invoke, diff --git a/src/index.d.ts b/src/index.d.ts index 5022b8d..40d93fa 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -2156,6 +2156,11 @@ export function createBrowserWasiShim(options?: { }; }): BrowserWasiShim; export interface BrowserModuleHarness { + /** Pool workers requested and armed; excludes the calling thread. Null for non-threaded artifacts. + * Command calls report the most recent invocation, including after its pool is terminated. + * Node starts workers on demand; requested is null without an explicit pool size. + */ + readonly wasiThreadPoolReport: Readonly<{ requested: number | null; armed: number }> | null; runtime: { kind: "browser"; profile: string; @@ -2234,6 +2239,8 @@ export function createBrowserModuleHarness(options?: { wasiThreadSpawnWaitMs?: number; // Explicit wasi-threads pool size (createWasiThreadSpawn poolSize). wasiThreadPoolSize?: number; + /** Positive finite browser pool arming deadline in milliseconds. Default 1500. */ + wasiThreadProbeTimeoutMs?: number; // Request-isolated BroadcastChannel descriptor a nested pthread hostcall // dispatches over; supplied by createWorkerModuleHarness for the in-worker // harness instance, not something a top-level caller usually sets by hand. From 7feacfccb03c396248245253cfb8a8a4de715eac Mon Sep 17 00:00:00 2001 From: TJKoury Date: Mon, 16 Nov 2026 15:14:45 -0500 Subject: [PATCH 2/3] Exercise browser pool deadlines and cleanup with the thread wave guest Co-Authored-By: Codex --- test/browser-pool-probe-timeout.test.js | 77 +++++++++++++++++++++++++ test/support/browserPoolProbeOwner.mjs | 53 +++++++++++++++++ test/support/threadWaveBrowser.mjs | 4 +- test/support/threadWaveGuest.mjs | 9 ++- 4 files changed, 139 insertions(+), 4 deletions(-) create mode 100644 test/browser-pool-probe-timeout.test.js create mode 100644 test/support/browserPoolProbeOwner.mjs diff --git a/test/browser-pool-probe-timeout.test.js b/test/browser-pool-probe-timeout.test.js new file mode 100644 index 0000000..1c52c75 --- /dev/null +++ b/test/browser-pool-probe-timeout.test.js @@ -0,0 +1,77 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { chromium } from "playwright-core"; +import { cleanupCompilation } from "../src/compiler/compileModule.js"; +import { resolveHeadlessShell } from "../src/testing/headlessShell.js"; +import { compileThreadWaveGuest, threadWaveEnv, threadWaveRequest } from "./support/threadWaveGuest.mjs"; +import { startThreadWaveServer } from "./support/threadWaveBrowser.mjs"; + +test("Chromium: browser pool deadline, arming report, cleanup, and result parity", { timeout: 240000 }, async () => { + const compilation = await compileThreadWaveGuest(); + let server, browser; + try { + server = await startThreadWaveServer({ + wasmBytes: compilation.wasmBytes, + ownerEntry: fileURLToPath(new URL("./support/browserPoolProbeOwner.mjs", import.meta.url)), + }); + browser = await chromium.launch({ executablePath: await resolveHeadlessShell(), headless: true }); + const page = await browser.newPage(); + const pageErrors = []; + const failedRequests = []; + page.on("pageerror", error => pageErrors.push(error.message)); + page.on("requestfailed", request => failedRequests.push(request.url())); + await page.goto(server.url); + await page.waitForFunction(() => typeof window.__runWaves === "function"); + const run = (options) => page.evaluate(options => window.__runWaves(options), { + request: threadWaveRequest(), ...options, + }); + for (const surface of ["direct", "command"]) { + const baseline = await run({ surface, poolSize: 0, env: threadWaveEnv(1) }); + assert.equal(baseline.error, undefined); + assert.equal(baseline.statusCode, 0); + assert.deepEqual(baseline.report, { requested: 0, armed: 0 }); + // Existing fixture regression value; byte equivalence is host validation, + // not an independent reference for a physical computation. + assert.equal(Buffer.from(baseline.outputs[0]).toString("hex"), "ecbe247c0e7e1dec"); + for (const probeTimeoutMs of [30000, 1]) { + const result = await run({ surface, poolSize: 4, probeTimeoutMs, env: threadWaveEnv(4, { mode: "inline" }) }); + assert.equal(result.error, undefined); + assert.equal(result.statusCode, 0, result.errorMessage); + assert.deepEqual(result.outputs, baseline.outputs); + assert.equal(result.initial.requested, 4); + assert.equal(result.report.requested, 4); + assert.equal(result.frozen, true); + assert.equal(result.readOnly, true); + assert.equal(result.liveAfterArming, result.initial.armed, "unarmed workers are terminated before the harness returns"); + assert.equal(result.liveAfterInvoke, surface === "direct" ? result.report.armed : result.initial.armed); + assert.equal(result.liveAfterDestroy, 0); + assert.equal(result.created, surface === "direct" ? 4 : 8); + assert.equal(result.spawnReport.failedToArm, 4 - result.report.armed); + if (probeTimeoutMs === 30000) { + assert.equal(result.initial.armed, 4); + assert.equal(result.report.armed, 4); + assert.equal(result.spawnReport.spawned, 9); + assert.equal(result.spawnReport.declined, 0); + } else { + assert.ok(result.initial.armed < 4); + assert.ok(result.report.armed < 4); + if (result.report.armed === 0) assert.equal(result.spawnReport.declined, 9); + } + console.log(`${surface}: timeout=${probeTimeoutMs}, requested=${result.report.requested}, armed=${result.report.armed}, spawned=${result.spawnReport.spawned}, declined=${result.spawnReport.declined}, liveAfterDestroy=${result.liveAfterDestroy}, identical=true`); + } + } + for (const probeTimeoutMs of [0, -1, NaN, Infinity, -Infinity, "1500", null]) { + const result = await run({ surface: "direct", poolSize: 4, probeTimeoutMs }); + assert.equal(result.error, "wasiThreadProbeTimeoutMs must be a positive finite number."); + assert.equal(result.created, 0); + assert.equal(result.liveAfterDestroy, 0); + } + assert.deepEqual(pageErrors, []); + assert.deepEqual(failedRequests, []); + } finally { + await browser?.close(); + await server?.close(); + await cleanupCompilation(compilation); + } +}); diff --git a/test/support/browserPoolProbeOwner.mjs b/test/support/browserPoolProbeOwner.mjs new file mode 100644 index 0000000..4749634 --- /dev/null +++ b/test/support/browserPoolProbeOwner.mjs @@ -0,0 +1,53 @@ +import { createBrowserModuleHarness } from "../../src/host/browserModuleHarness.js"; + +// Observe termination calls while every worker executes the real SDK pool code. +const NativeWorker = globalThis.Worker; +const live = new Set(); +let created = 0; +globalThis.Worker = class extends NativeWorker { + constructor(...args) { + super(...args); + created += 1; + live.add(this); + } + terminate() { + live.delete(this); + return super.terminate(); + } +}; + +self.onmessage = async ({ data }) => { + const { id, poolSize, probeTimeoutMs, surface, env, request } = data; + let harness; + const before = created; + const reply = { id }; + try { + harness = await createBrowserModuleHarness({ + wasmSource: "/module.wasm", + surface, + env, + enableBrowserWasiThreads: true, + wasiThreadPoolSize: poolSize, + wasiThreadProbeTimeoutMs: probeTimeoutMs, + wasiThreadWorkerUrl: new URL("/wasi-thread-worker.js", self.location.href).href, + }); + reply.initial = harness.wasiThreadPoolReport; + reply.liveAfterArming = live.size; + reply.frozen = Object.isFrozen(harness.wasiThreadPoolReport); + try { harness.wasiThreadPoolReport = {}; } catch { reply.readOnly = true; } + const response = await harness.invoke(request); + reply.statusCode = response.statusCode; + reply.errorMessage = response.errorMessage; + reply.outputs = response.outputs.map(output => Array.from(output.payload)); + reply.report = harness.wasiThreadPoolReport; + reply.spawnReport = harness.threadHost.spawnReport(); + reply.liveAfterInvoke = live.size; + } catch (error) { + reply.error = error.message; + } finally { + await harness?.destroy(); + } + reply.created = created - before; + reply.liveAfterDestroy = live.size; + self.postMessage(reply); +}; diff --git a/test/support/threadWaveBrowser.mjs b/test/support/threadWaveBrowser.mjs index dfc8a3c..0795367 100644 --- a/test/support/threadWaveBrowser.mjs +++ b/test/support/threadWaveBrowser.mjs @@ -44,9 +44,9 @@ window.__runWaves = (options) => new Promise((resolve) => { }); `; -export async function startThreadWaveServer({ wasmBytes }) { +export async function startThreadWaveServer({ wasmBytes, ownerEntry = path.join(here, "threadWaveOwner.mjs") }) { const [owner, threadWorker] = await Promise.all([ - bundle(path.join(here, "threadWaveOwner.mjs")), + bundle(ownerEntry), bundle(path.join(here, "..", "..", "src", "host", "wasiThreadBrowserWorker.mjs")), ]); const isolation = { diff --git a/test/support/threadWaveGuest.mjs b/test/support/threadWaveGuest.mjs index 3a6b42b..cca64a5 100644 --- a/test/support/threadWaveGuest.mjs +++ b/test/support/threadWaveGuest.mjs @@ -17,12 +17,13 @@ // spawns ONE thread, which spawns the other // N - 2 and joins them (spawns from a guest // thread that is not the main thread) +// "inline": declined stripes run on the calling thread // SDM_WAVES waves per invoke (default 3) // SDM_WAVE_ROUNDS mixing rounds per cell (default 2048) // // The work is a fixed 840-cell grid (840 = lcm(1..8)), so the response bytes // never depend on N or the mode: parity compares them across lanes AND thread -// counts. A declined spawn fails the invoke with status 20 + wave (30 + wave +// counts. Except in inline mode, a declined spawn fails the invoke with status 20 + wave (30 + wave // from the nested spawner) and error "thread-spawn-declined", the way // std::thread aborts on EAGAIN. @@ -192,7 +193,11 @@ int waves(void) { uint32_t created = 0; int declined = 0; for (uint32_t t = 0; t < spawned; ++t) { - if (pthread_create(&threads[t], 0, thread_main, &plan[first_spawned + t]) != 0) { + if (pthread_create(&threads[created], 0, thread_main, &plan[first_spawned + t]) != 0) { + if (strcmp(mode, "inline") == 0) { + run_stripe(&plan[first_spawned + t]); + continue; + } declined = 1; break; } From dbc48c7a9202018c63d2356e7769d1c005fe0f3d Mon Sep 17 00:00:00 2001 From: TJKoury Date: Mon, 16 Nov 2026 15:15:44 -0500 Subject: [PATCH 3/3] Document browser pool startup configuration and reporting Co-Authored-By: Codex --- CHANGELOG.md | 1 + docs/isomorphic-pthreads.md | 33 ++++++++++++++++++++++++++++ examples/isomorphic-loader/README.md | 12 +++++++--- 3 files changed, 43 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c79aa8..74f8d04 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## 0.10.3 +- The browser module harness accepts `wasiThreadProbeTimeoutMs` (positive finite milliseconds, default 1500) and exposes read-only `wasiThreadPoolReport` counts for requested and armed pool workers. Explicit pools retain workers that arm; workers that miss the deadline are terminated, and the host decides how to handle reduced capacity. - MODULE compilation accepts hash-verified prebuilt WebAssembly objects and static archives through `prebuiltLibraries`. Input order and producer symbols are preserved; input bytes participate in the link cache. - Guest-link output carries prebuilt libraries into FLOW compilation. Identical names and hashes link once; conflicting content for a name or namespace is refused. - The compile CLI accepts guest-link metadata with `--prebuilt-libraries`. Artifact guards retain their checks and include library names in failures. diff --git a/docs/isomorphic-pthreads.md b/docs/isomorphic-pthreads.md index 6dcc35b..37ce678 100644 --- a/docs/isomorphic-pthreads.md +++ b/docs/isomorphic-pthreads.md @@ -422,6 +422,39 @@ worker bundles and the browser capability probe. ### Explicit pool size, partial spawns, supervision hooks +`createBrowserModuleHarness` accepts `wasiThreadProbeTimeoutMs`, the browser +pool arming deadline in milliseconds. It forwards the value as +`createWasiThreadSpawn`'s `probeTimeoutMs`. The default is 1500. An explicit +value must be a positive finite number; invalid values throw an `Error` before +the artifact is loaded. The option applies to the initial context and each +fresh command invocation. It has no effect on Node's on-demand pool startup. + +After harness creation, the read-only `harness.wasiThreadPoolReport` property +returns a frozen `{ requested, armed }` snapshot. Counts refer to pool workers +and exclude the calling thread. With `wasiThreadPoolSize`, `requested` is that +explicit size, including when threading is unavailable. Without an explicit +size, it is the browser's selected pool size. Non-threaded artifacts return +`null`. Node reports its explicit cap (or `null` without one) and the number +of workers started on demand. + +For an explicit browser pool, fewer armed workers do not throw. Workers that +miss the deadline are terminated before the harness returns; successfully +armed workers remain available. The host uses the report to decide whether +the capacity meets its needs. A guest must handle declined spawns to execute +successfully with fewer workers. After a command invocation, the property +reports that invocation's arming counts, even though its pool is terminated. +These are startup counts, not a live-worker health report. + +```js +const harness = await createBrowserModuleHarness({ + wasmSource, + enableBrowserWasiThreads: true, + wasiThreadPoolSize: 8, + wasiThreadProbeTimeoutMs: 10000, +}); +const { requested, armed } = harness.wasiThreadPoolReport; +``` + `createWasiThreadSpawn` options added in 0.8.22: | Option | Effect | diff --git a/examples/isomorphic-loader/README.md b/examples/isomorphic-loader/README.md index f8fe226..8686112 100644 --- a/examples/isomorphic-loader/README.md +++ b/examples/isomorphic-loader/README.md @@ -41,9 +41,15 @@ Then open: The browser demo uses: -- `loadModule(...)` from [`src/host/isomorphicLoader.js`](/Users/tj/software/space-data-module-sdk/src/host/isomorphicLoader.js) -- browser edge shims from [`src/host/browserEdgeShims.js`](/Users/tj/software/space-data-module-sdk/src/host/browserEdgeShims.js) -- browser host adapter from [`src/host/browserHost.js`](/Users/tj/software/space-data-module-sdk/src/host/browserHost.js) +- `loadModule(...)` from [`src/host/isomorphicLoader.js`](../../src/host/isomorphicLoader.js) +- browser edge shims from [`src/host/browserEdgeShims.js`](../../src/host/browserEdgeShims.js) +- browser host adapter from [`src/host/browserHost.js`](../../src/host/browserHost.js) + +For threaded artifacts loaded with `createBrowserModuleHarness`, +`wasiThreadProbeTimeoutMs` sets the browser pool arming deadline (default 1500 +milliseconds; positive finite values only). The read-only +`harness.wasiThreadPoolReport` exposes `{ requested, armed }` worker counts. +See [pool configuration and reporting](../../docs/isomorphic-pthreads.md#explicit-pool-size-partial-spawns-supervision-hooks). ## Run In WasmEdge