Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(sidemodules): a game started over and over in one page no longer runs out of WebAssembly memory - the module host has an end, the App that made it disposes it on quit, and the KTX2 transcode workers stop with it

yhh1915e10d11a9
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 16ee77208..490e51282 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -823,7 +823,7 @@ setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
setRunInBackground: (on: boolean) => void
-setSideModules: (host: SideModuleHost) => void
+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
@@ -3127,6 +3127,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
@@ -10076,6 +10077,8 @@ globalName: string | undefined
## SideModuleHost — interface @experimental
```
acquire: (id: SideModuleId) => Promise<SideModule | null>
+dispose: (() => void) | undefined
+onDispose: ((release: () => void) => void) | undefined
source: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined
```
@@ -13900,6 +13903,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index eb69efdc8..c90c1f059 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -823,7 +823,7 @@ setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
setRunInBackground: (on: boolean) => void
-setSideModules: (host: SideModuleHost) => void
+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
@@ -3135,6 +3135,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
@@ -10298,6 +10299,8 @@ globalName: string | undefined
## SideModuleHost — interface @experimental
```
acquire: (id: SideModuleId) => Promise<SideModule | null>
+dispose: (() => void) | undefined
+onDispose: ((release: () => void) => void) | undefined
source: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined
```
@@ -14122,6 +14125,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 41e8c772e..e26384ea4 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -818,7 +818,7 @@ setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
setRunInBackground: (on: boolean) => void
-setSideModules: (host: SideModuleHost) => void
+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
@@ -3122,6 +3122,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
@@ -10071,6 +10072,8 @@ globalName: string | undefined
## SideModuleHost — interface @experimental
```
acquire: (id: SideModuleId) => Promise<SideModule | null>
+dispose: (() => void) | undefined
+onDispose: ((release: () => void) => void) | undefined
source: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined
```
@@ -13895,6 +13898,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 606702c60..814d8d3c8 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -818,7 +818,7 @@ setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
setRunInBackground: (on: boolean) => void
-setSideModules: (host: SideModuleHost) => void
+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
@@ -3122,6 +3122,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
@@ -10368,6 +10369,8 @@ globalName: string | undefined
## SideModuleHost — interface @experimental
```
acquire: (id: SideModuleId) => Promise<SideModule | null>
+dispose: (() => void) | undefined
+onDispose: ((release: () => void) => void) | undefined
source: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined
```
@@ -14198,6 +14201,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 7680b1cc5..49bc67cd7 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -818,7 +818,7 @@ setPaused: (paused: boolean) => void
setPipeline: (pipeline: RenderPipeline) => void
setPlaySpeed: (speed: number) => void
setRunInBackground: (on: boolean) => void
-setSideModules: (host: SideModuleHost) => void
+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => void
setTargetFrameRate: (fps: number) => void
sideModules: SideModuleHost | null
spineInitPromise: Promise<unknown> | undefined
@@ -3122,6 +3122,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
@@ -10078,6 +10079,8 @@ globalName: string | undefined
## SideModuleHost — interface @experimental
```
acquire: (id: SideModuleId) => Promise<SideModule | null>
+dispose: (() => void) | undefined
+onDispose: ((release: () => void) => void) | undefined
source: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined
```
@@ -13929,6 +13932,7 @@ depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
+ownsSideModules: boolean | undefined
plugins: Plugin[] | undefined
quality: QualityConfig | undefined
randomSeed: number | undefined
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 25955f044..843a14caf 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -251,6 +251,8 @@ export class App {
// The realm's acquirer for optional native modules (physics, spine). Set once
// at app creation; physics/spine self-gate off it. Null in headless/test apps.
private sideModules_: SideModuleHost | null = null;
+ /** This App made the host, so quitting disposes it; one handed in is its maker's to end. */
+ private ownsSideModules_ = false;
private pluginsFinished_ = false;
private readonly eventRegistry_ = new EventRegistry();
private readonly sortedSystemsCache_ = new Map<Schedule, SystemEntry[]>();
@@ -312,8 +314,14 @@ export class App {
return this.sideModules_;
}
- setSideModules(host: SideModuleHost): void {
+ /**
+ * `owned` says the host was made for this App alone: quitting then disposes
+ * it, with the workers and module instances tied to it. A host shared with
+ * anything else is left as it is, and whoever made it disposes it.
+ */
+ setSideModules(host: SideModuleHost, options?: { owned?: boolean }): void {
this.sideModules_ = host;
+ this.ownsSideModules_ = options?.owned === true;
}
addPlugins(plugins: Plugin[]): this {
@@ -1556,6 +1564,11 @@ export class App {
this.ownedCppRegistry_ = null;
try { ownedRegistry?.delete(); }
catch (e) { log.warn('app', 'Shutdown registry release error', e); }
+ // After the plugins, which may still have asked it for something on their way out.
+ const modules = this.ownsSideModules_ ? this.sideModules_ : null;
+ this.ownsSideModules_ = false;
+ try { modules?.dispose?.(); }
+ catch (e) { log.warn('app', 'Shutdown module-host release error', e); }
for (const [, entries] of this.systems_) {
entries.length = 0;
@@ -2099,6 +2112,8 @@ export interface WebAppOptions {
/** The realm's optional-native-module acquirer; set before plugins build so
* SpinePlugin (and later physics) can pull from it. See {@link App.sideModules}. */
sideModules?: SideModuleHost;
+ /** `sideModules` was made for this App alone, so quitting disposes it. See {@link App.setSideModules}. */
+ ownsSideModules?: boolean;
/**
* Bitmask of render layers (bits 0..31) that sort by world Y within the
* layer — top-down occlusion (lower on screen draws on top). Project-level
@@ -2192,7 +2207,7 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A
// entry snapshots the baseline — e.g. in unit tests that never load it).
seedEngineComponents();
const app = App.new();
- if (options?.sideModules) app.setSideModules(options.sideModules);
+ if (options?.sideModules) app.setSideModules(options.sideModules, { owned: options.ownsSideModules });
const cppRegistry = new module.Registry() as unknown as CppRegistry;
try {
diff --git a/sdk/src/asset/basisWorkers.ts b/sdk/src/asset/basisWorkers.ts
index 64ee8dcf7..2fff2ef92 100644
--- a/sdk/src/asset/basisWorkers.ts
+++ b/sdk/src/asset/basisWorkers.ts
@@ -55,11 +55,20 @@ self.onmessage = (e) => {
`;
}
+/** A transcoder that owns threads, and so has to be told when it is done with. */
+export interface WorkerBasisTranscoder extends BasisTranscoder {
+ /** Stop the workers. What is still in flight settles as "no result"; later calls do too. Idempotent. */
+ dispose(): void;
+}
+
/**
* A transcoder whose work runs on `count` workers, or null where this realm has
* no `Worker` (mini-game hosts, node) — the caller then transcodes in place.
+ *
+ * The caller owns the workers: each holds its own instance of the module, and a
+ * running worker is never collected, so they last until {@link WorkerBasisTranscoder.dispose}.
*/
-export function createWorkerBasisTranscoder(source: SideModuleSource, count: number): BasisTranscoder | null {
+export function createWorkerBasisTranscoder(source: SideModuleSource, count: number): WorkerBasisTranscoder | null {
if (typeof Worker === 'undefined' || typeof Blob === 'undefined' || typeof URL?.createObjectURL !== 'function') {
return null;
}
@@ -77,6 +86,11 @@ export function createWorkerBasisTranscoder(source: SideModuleSource, count: num
if (e.data.error !== undefined) p.reject(new Error(`transcode worker: ${e.data.error}`));
else p.resolve(e.data.result ?? null);
};
+ // A worker whose script will not even start answers nothing; without this its loads wait for good.
+ w.onerror = (e: ErrorEvent) => {
+ const failed = new Error(`transcode worker: ${e.message || 'the worker stopped'}`);
+ for (const [id, p] of pending) { pending.delete(id); p.reject(failed); }
+ };
// Each worker gets its own copy: a transferred buffer would leave the next one empty.
w.postMessage({ init: true, glueText: source.glueText, globalName: source.globalName, wasmBytes: source.wasmBytes.slice(0) });
workers.push(w);
@@ -86,7 +100,9 @@ export function createWorkerBasisTranscoder(source: SideModuleSource, count: num
}
// Least-loaded, so one slow 4K texture does not queue the small ones behind it.
const inFlight = new Array<number>(workers.length).fill(0);
+ let disposed = false;
const run = (ktx2: Uint8Array, code: number): Promise<TranscodeResult | null> => {
+ if (disposed) return Promise.resolve(null);
const i = inFlight.indexOf(Math.min(...inFlight));
const id = nextId++;
inFlight[i]++;
@@ -100,6 +116,13 @@ export function createWorkerBasisTranscoder(source: SideModuleSource, count: num
return {
transcode: (ktx2: Uint8Array, target: CompressedTextureFormat) => run(ktx2, FORMAT_CODE[target]),
transcodeToRgba: (ktx2: Uint8Array) => run(ktx2, RGBA_CODE) as Promise<RgbaResult | null>,
+ dispose(): void {
+ if (disposed) return;
+ disposed = true;
+ for (const w of workers) w.terminate();
+ // Whoever is still waiting is being torn down with the realm: no result, and no error to report.
+ for (const [id, p] of pending) { pending.delete(id); p.resolve(null); }
+ },
};
}
@@ -114,6 +137,10 @@ function workerCount(): number {
* in front of it where the host can hand over the module's source and the realm
* has `Worker`. A worker that fails once (a CSP refusing blob workers, a module
* that will not start) sends that load and every later one to the main thread.
+ *
+ * The workers are the host's: they stop when it is disposed, which is what an App
+ * does on quit. A realm that starts a game over and over would otherwise keep
+ * every earlier game's workers, each with a WebAssembly memory of its own.
*/
export function basisTranscoderFor(host: SideModuleHost | null | undefined): Promise<BasisTranscoder | null> {
if (!host) return Promise.resolve(null);
@@ -135,11 +162,14 @@ async function makeTranscoder(host: SideModuleHost): Promise<BasisTranscoder | n
const source = host.source ? await host.source('basis').catch(() => null) : null;
const workers = source ? createWorkerBasisTranscoder(source, workerCount()) : null;
if (!workers) return main;
+ host.onDispose?.(() => workers.dispose());
let broken = false;
const either = <R>(off: () => R | Promise<R>, on: () => R | Promise<R>): Promise<R> => {
if (broken) return Promise.resolve(on());
return Promise.resolve(off()).catch((e: unknown) => {
broken = true;
+ // Not coming back, so they do not keep their memory either.
+ workers.dispose();
log.warn('asset', 'KTX2 transcoding moved back to the main thread: the transcode workers failed', e);
return on();
});
diff --git a/sdk/src/runtime/webAppFactory.ts b/sdk/src/runtime/webAppFactory.ts
index e8446f45d..6abc566ae 100644
--- a/sdk/src/runtime/webAppFactory.ts
+++ b/sdk/src/runtime/webAppFactory.ts
@@ -34,6 +34,8 @@ const basePlugins = webBasePlugins();
export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptions): App {
+ // A host built here is this App's alone and ends with it; one passed in may serve others.
+ const ownsSideModules = !options?.sideModules && Boolean(options?.wasmBaseUrl);
const sideModules: SideModuleHost | undefined = options?.sideModules
?? (options?.wasmBaseUrl ? createFetchSideModuleHost(options.wasmBaseUrl) : undefined);
// Spine and DragonBones each fetch their wasm only when asked, so installing
@@ -43,7 +45,7 @@ export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptio
// Ordered, not concatenated: where a plugin came from is not where it goes.
const plugins = [...uiPlugins, ...inBuildOrder([...basePlugins, ...entryPlugins()]),
...(options?.plugins ?? [])];
- return _createWebApp(module, { ...options, sideModules, plugins });
+ return _createWebApp(module, { ...options, sideModules, ownsSideModules, plugins });
}
export interface HeadlessAppOptions {
diff --git a/sdk/src/sideModules/fetchHost.ts b/sdk/src/sideModules/fetchHost.ts
index a6fcda2de..42e716774 100644
--- a/sdk/src/sideModules/fetchHost.ts
+++ b/sdk/src/sideModules/fetchHost.ts
@@ -40,6 +40,8 @@ export function createFetchSideModuleHost(baseUrl: string): SideModuleHost {
// Instantiation may detach the buffer it is given; the kept one stays whole.
return instantiateFromGlueText(glueText, wasmBytes.slice(0), descriptor);
}, { requiresWebAssembly: true });
+ // The bytes go with the host: a worker pool tied to it has made its copies by then.
+ host.onDispose?.(() => fetched.clear());
return {
...host,
async source(id: SideModuleId): Promise<SideModuleSource | null> {
diff --git a/sdk/src/sideModules/host.ts b/sdk/src/sideModules/host.ts
index 6c84f4f18..81ac38c8c 100644
--- a/sdk/src/sideModules/host.ts
+++ b/sdk/src/sideModules/host.ts
@@ -24,6 +24,23 @@ export interface SideModuleHost {
/** The glue and binary `id` is instantiated from, for a worker to instantiate
* its own copy; absent where the realm has none to hand over. */
source?(id: SideModuleId): Promise<SideModuleSource | null>;
+ /**
+ * Tie something to this host's life: a pool of workers that each instantiated
+ * one of its modules. `release` runs once, when the host is disposed — or at
+ * once, if it already has been.
+ */
+ onDispose?(release: () => void): void;
+ /**
+ * Let go of everything the host holds: the instances it cached and whatever
+ * was tied to it. Whoever made the host calls this when the realm it served
+ * is over; an App does it on quit for a host it created itself. Idempotent,
+ * and a disposed host answers every later `acquire` with null.
+ *
+ * Nothing else ends these. A worker is never collected while it runs, and
+ * each one holds a WebAssembly memory, so a host dropped without this leaks
+ * them for as long as the page lives.
+ */
+ dispose?(): void;
}
export interface SideModuleSource {
@@ -68,8 +85,25 @@ export interface SideModuleHostOptions {
export function createSideModuleHost(instantiate: SideModuleInstantiator, options: SideModuleHostOptions = {}): SideModuleHost {
const cache = new Map<SideModuleId, Promise<SideModule | null>>();
+ const releases: Array<() => void> = [];
+ let disposed = false;
+ const run = (release: () => void): void => {
+ try { release(); } catch (e) { log.warn('sidemodule', 'a release tied to the module host failed', e); }
+ };
return {
+ onDispose(release: () => void): void {
+ if (disposed) run(release);
+ else releases.push(release);
+ },
+ dispose(): void {
+ if (disposed) return;
+ disposed = true;
+ // Last tied, first released: what was built on a module goes before the module's own entry.
+ for (const release of releases.splice(0).reverse()) run(release);
+ cache.clear();
+ },
acquire(id: SideModuleId): Promise<SideModule | null> {
+ if (disposed) return Promise.resolve(null);
const cached = cache.get(id);
if (cached) return cached;
const descriptor = sideModuleDescriptor(id);
@@ -88,7 +122,7 @@ export function createSideModuleHost(instantiate: SideModuleInstantiator, option
// Absent BY DESIGN is the answer null already means; only a
// module that was meant to be here is a failure to report.
if (e instanceof SideModuleAbsent) log.info('sidemodule', e.message);
- else log.error('sidemodule', `failed to load "${id}" (${descriptor.file}) — ${howToFix(id)}`, e);
+ else log.error('sidemodule', `failed to load "${id}" (${descriptor.file}) — ${howToFix(id, e)}`, e);
return null;
})
// Unknown ids used to be impossible (the type was closed) and so
@@ -103,6 +137,12 @@ export function createSideModuleHost(instantiate: SideModuleInstantiator, option
};
}
+/** The engine refused the memory: the artifact was found and compiled, so this is not a missing build. */
+export function isOutOfWasmMemory(error: unknown): boolean {
+ const message = error instanceof Error ? error.message : String(error);
+ return /out of memory|cannot allocate wasm memory/i.test(message);
+}
+
/**
* What to do about a module that would not load, which differs by who built it.
*
@@ -110,8 +150,15 @@ export function createSideModuleHost(instantiate: SideModuleInstantiator, option
* the advice is the build command. For a project's own module the engine has no
* idea how it is produced — pointing someone at `pnpm build -t rive` would be a
* command that does not exist — so it says where the export looked instead.
+ *
+ * Neither applies when the process had no WebAssembly memory left to give: the
+ * module is there, and telling someone to rebuild it sends them the wrong way.
*/
-function howToFix(id: SideModuleId): string {
+function howToFix(id: SideModuleId, error: unknown): string {
+ if (isOutOfWasmMemory(error)) {
+ return 'the module is present, but this process has no WebAssembly memory left to start it: '
+ + 'something is holding earlier instances (in the editor, restart it and report this)';
+ }
if (id in SIDE_MODULES) {
return 'likely not built locally: run the matching wasm build (spine 4.2 = '
+ '`pnpm build -t spine`, others match their file name, `-t all` builds '
diff --git a/sdk/tests/basis-workers.test.ts b/sdk/tests/basis-workers.test.ts
index ec0df21d5..91de17fb9 100644
--- a/sdk/tests/basis-workers.test.ts
+++ b/sdk/tests/basis-workers.test.ts
@@ -15,7 +15,7 @@ import { WASM_DIR, hasSideModule, loadSideModule } from './helpers/loadWasm';
import { basisTranscoderFor, createWorkerBasisTranscoder } from '../src/asset/basisWorkers';
import { transcoderFromModule, type BasisWasmModule } from '../src/asset/basisTranscoder';
import { CompressedTextureFormat, type TranscodeResult } from '../src/asset/compressed';
-import type { SideModuleHost, SideModuleSource } from '../src/sideModules/host';
+import { createSideModuleHost, type SideModuleHost, type SideModuleSource } from '../src/sideModules/host';
import { log } from '../src/util/logger';
const ROOT = path.resolve(__dirname, '../..');
@@ -24,6 +24,9 @@ const blobs = new Map<string, string>();
const saved = { Worker: globalThis.Worker, createObjectURL: URL.createObjectURL, revokeObjectURL: URL.revokeObjectURL };
class StandInWorker {
+ /** Workers started and not yet terminated: each one is a thread and a WebAssembly memory the page keeps. */
+ static live = 0;
+ private stopped = false;
onmessage: ((e: { data: unknown }) => void) | null = null;
private readonly scope: { onmessage: ((e: { data: unknown }) => void) | null; postMessage(d: unknown): void } & Record<string, unknown>;
constructor(url: string) {
@@ -49,11 +52,18 @@ class StandInWorker {
)(scope, shadow, importScripts);
};
new Function('self', 'importScripts', text)(scope, importScripts);
+ StandInWorker.live++;
}
postMessage(d: unknown): void {
setTimeout(() => this.scope.onmessage?.({ data: structuredClone(d) }), 0);
}
- terminate(): void {}
+ terminate(): void {
+ if (this.stopped) return;
+ this.stopped = true;
+ StandInWorker.live--;
+ this.onmessage = null;
+ this.scope.onmessage = null;
+ }
}
beforeAll(() => {
@@ -103,10 +113,46 @@ describe.skipIf(!hasSideModule('basis'))('KTX2 transcoding on workers', () => {
same(await workers.transcode(ktx2, CompressedTextureFormat.ASTC_4x4),
await main.transcode(ktx2, CompressedTextureFormat.ASTC_4x4));
same(await workers.transcodeToRgba(ktx2), await main.transcodeToRgba(ktx2));
+ workers.dispose();
+ });
+
+ const realmHost = (): SideModuleHost => ({
+ ...createSideModuleHost(async () => (main as unknown as { mod: unknown }).mod as never),
+ source: async () => source,
+ });
+
+ it('stops its workers with the host that made them, and answers nothing after', async () => {
+ const before = StandInWorker.live;
+ const host = realmHost();
+ const t = (await basisTranscoderFor(host))!;
+ expect(StandInWorker.live).toBeGreaterThan(before);
+ const inFlight = t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4);
+ host.dispose!();
+ expect(StandInWorker.live).toBe(before);
+ // Torn down mid-load: no result and no error, and no fall back to a module that is going away too.
+ const warn = vi.spyOn(log, 'warn');
+ expect(await inFlight).toBeNull();
+ expect(await t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4)).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ warn.mockRestore();
+ });
+
+ // The editor starts a game, stops it and starts it again in one page. Each start made a host and up to four
+ // workers and nothing ended them: a dozen starts later the page had no WebAssembly memory left (#121).
+ it('leaves no worker behind however many times a realm is started and stopped', async () => {
+ const before = StandInWorker.live;
+ for (let play = 0; play < 20; play++) {
+ const host = realmHost();
+ const t = (await basisTranscoderFor(host))!;
+ same(await t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4), await main.transcode(ktx2, CompressedTextureFormat.ASTC_4x4));
+ host.dispose!();
+ }
+ expect(StandInWorker.live).toBe(before);
});
it('goes back to the main thread, once and for good, when the workers fail', async () => {
const warn = vi.spyOn(log, 'warn');
+ const before = StandInWorker.live;
const host: SideModuleHost = {
acquire: async () => (main as unknown as { mod: unknown }).mod as never,
source: async () => ({ ...source, glueText: 'throw new Error("no glue")' }),
@@ -115,6 +161,8 @@ describe.skipIf(!hasSideModule('basis'))('KTX2 transcoding on workers', () => {
same(await t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4), await main.transcode(ktx2, CompressedTextureFormat.ASTC_4x4));
await t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4);
expect(warn.mock.calls.filter((c) => String(c[1]).includes('main thread'))).toHaveLength(1);
+ // Workers that will never answer do not keep their threads.
+ expect(StandInWorker.live).toBe(before);
warn.mockRestore();
});
diff --git a/sdk/tests/sideModuleHost.test.ts b/sdk/tests/sideModuleHost.test.ts
index dcf85cdea..3077577b2 100644
--- a/sdk/tests/sideModuleHost.test.ts
+++ b/sdk/tests/sideModuleHost.test.ts
@@ -6,7 +6,9 @@
* WeChat) is exercised by the per-realm export + runtime paths.
*/
import { describe, it, expect, vi } from 'vitest';
-import { createSideModuleHost, SideModuleAbsent } from '../src/sideModules/host';
+import { createSideModuleHost, isOutOfWasmMemory, SideModuleAbsent } from '../src/sideModules/host';
+import { App } from '../src/app/app';
+import { log } from '../src/util/logger';
import { SIDE_MODULES, SPINE_VERSIONS, spineModuleId } from '../src/sideModules/registry';
describe('side-module registry', () => {
@@ -114,3 +116,63 @@ describe('createSideModuleHost', () => {
});
});
+
+describe('a module host ends', () => {
+ it('releases what was tied to it, newest first and once', () => {
+ const host = createSideModuleHost(vi.fn());
+ const order: string[] = [];
+ host.onDispose!(() => order.push('first'));
+ host.onDispose!(() => { throw new Error('one bad release'); });
+ host.onDispose!(() => order.push('last'));
+ const warn = vi.spyOn(log, 'warn').mockImplementation(() => {});
+ host.dispose!();
+ host.dispose!();
+ warn.mockRestore();
+ // One that throws does not keep the others from running.
+ expect(order).toEqual(['last', 'first']);
+ // Tied too late: there is no later moment to wait for.
+ host.onDispose!(() => order.push('late'));
+ expect(order).toEqual(['last', 'first', 'late']);
+ });
+
+ it('gives nothing once disposed, and does not ask the transport', async () => {
+ const instantiate = vi.fn().mockResolvedValue({});
+ const host = createSideModuleHost(instantiate);
+ await host.acquire('physics');
+ host.dispose!();
+ expect(await host.acquire('physics')).toBeNull();
+ expect(await host.acquire('basis')).toBeNull();
+ expect(instantiate).toHaveBeenCalledTimes(1);
+ });
+
+ it('is disposed by the App it was made for, and left alone by one it was lent to', () => {
+ const owned = createSideModuleHost(vi.fn());
+ const lent = createSideModuleHost(vi.fn());
+ const ended: string[] = [];
+ owned.onDispose!(() => ended.push('owned'));
+ lent.onDispose!(() => ended.push('lent'));
+ const a = App.new();
+ a.setSideModules(owned, { owned: true });
+ const b = App.new();
+ b.setSideModules(lent);
+ a.quit();
+ b.quit();
+ expect(ended).toEqual(['owned']);
+ });
+});
+
+describe('a module that would not load', () => {
+ it('is not called a missing build when the process had no memory for it', async () => {
+ const oom = new RangeError('WebAssembly.instantiate(): Out of memory: Cannot allocate Wasm memory for new instance');
+ expect(isOutOfWasmMemory(oom)).toBe(true);
+ expect(isOutOfWasmMemory(new Error('fetch /wasm/basis.js → 404'))).toBe(false);
+ const error = vi.spyOn(log, 'error').mockImplementation(() => {});
+ expect(await createSideModuleHost(vi.fn().mockRejectedValue(oom)).acquire('basis')).toBeNull();
+ expect(await createSideModuleHost(vi.fn().mockRejectedValue(new Error('404'))).acquire('basis')).toBeNull();
+ const said = error.mock.calls.map((c) => String(c[1]));
+ error.mockRestore();
+ expect(said[0]).toMatch(/no WebAssembly memory left/);
+ expect(said[0]).not.toMatch(/not built locally/);
+ expect(said[1]).toMatch(/not built locally/);
+ });
+});