Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
33 changes: 33 additions & 0 deletions docs/isomorphic-pthreads.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
12 changes: 9 additions & 3 deletions examples/isomorphic-loader/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
13 changes: 13 additions & 0 deletions src/host/browserModuleHarness.js
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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,
Expand Down
7 changes: 7 additions & 0 deletions src/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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.
Expand Down
77 changes: 77 additions & 0 deletions test/browser-pool-probe-timeout.test.js
Original file line number Diff line number Diff line change
@@ -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);
}
});
53 changes: 53 additions & 0 deletions test/support/browserPoolProbeOwner.mjs
Original file line number Diff line number Diff line change
@@ -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);
};
4 changes: 2 additions & 2 deletions test/support/threadWaveBrowser.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
9 changes: 7 additions & 2 deletions test/support/threadWaveGuest.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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;
}
Expand Down
Loading