diff --git a/@types/pal/minigame.d.ts b/@types/pal/minigame.d.ts index 763deac8c6..d5bea82a1d 100644 --- a/@types/pal/minigame.d.ts +++ b/@types/pal/minigame.d.ts @@ -37,6 +37,38 @@ declare module 'pal/minigame' { getSharedCanvas(): any; getOpenDataContext(): any; + // worker + /** + * Create a worker thread from a packaged script path. + * + * IMPORTANT — this is optional and genuinely absent on some platforms: + * - Present: WeChat (`wx.createWorker`), ByteDance (`tt.createWorker`), Alipay + * (`my.createWorker`), Baidu (`swan.createWorker`, base library 1.6.1+), and the + * quick-game family (`qg.createWorker` on Xiaomi / Huawei 1117+ / OPPO / vivo). + * Each `pal/minigame/*.js` adapter starts with `cloneObject(minigame, )`, + * and `cloneObject` copies functions with `.bind(origin)` — so `createWorker` arrives on + * `minigame` for free, already bound to the right global. No per-platform adapter code + * is needed, and `pal/` itself must not be edited (it is regenerated from the + * `@cocos/engine-pal` package on postinstall). + * - Absent: Taobao mini-game has NO worker API at all (its API surface has no Worker + * category), and no `Worker` / `Blob` / `URL.createObjectURL` either — there is no way to + * get a real thread there. Callers must degrade to synchronous execution. + * + * Returns `undefined` (rather than throwing) when creation fails on Huawei quick game, so + * the result MUST be null-checked. + * + * Every platform caps concurrency at ONE worker except WeChat V2 (standard worker). + * Script paths must be relative (no leading "/") and end with ".js", and the file must be + * packaged under the workers directory declared in game.json / manifest.json / app.json. + */ + createWorker?: (scriptPath: string, options?: MinigameWorkerOptions) => MinigameWorker | undefined; + /** + * Platform environment info. On WeChat this carries `isSupportStandardWorker`, which gates + * the V2 standard worker (grey release; NOT supported in the WeChat devtools). Absent on + * platforms whose global has no `env`. + */ + env?: MinigameEnv; + // file system getFileSystemManager(): FileSystemManager; loadSubpackage? (option: LoadSubpackageOption): LoadSubpackageTask; @@ -133,6 +165,57 @@ declare module 'pal/minigame' { getAudioContext?: () => AudioContext; } + /** + * Options accepted by `minigame.createWorker`. Only WeChat defines any; other platforms ignore + * the second argument. Kept loose on purpose — the platform surface differs and grows. + */ + export interface MinigameWorkerOptions { + /** + * WeChat only, base library 2.13.0+. Uses the "experimental" worker implementation, which + * speeds up JS execution several times over on iOS. Requires pairing with + * `onProcessKilled`, because the system may reclaim the worker process at any time. + * This legacy option does not select the V2 standard Worker. + */ + useExperimentalWorker?: boolean; + [key: string]: any; + } + + /** + * Platform environment info exposed as `minigame.env`. + */ + export interface MinigameEnv { + /** + * WeChat only. `true` when the runtime supports the V2 standard worker: multiple concurrent + * workers, `SharedArrayBuffer`, transfer lists in `postMessage`, `OffscreenCanvas`. Requires + * WeChat client >= 8.0.74 (Android) and base library >= 3.17.0, is in grey release, and is + * NOT supported in the WeChat devtools — so it must be checked at runtime, never assumed. + */ + isSupportStandardWorker?: boolean; + [key: string]: any; + } + + /** + * The worker handle returned by `minigame.createWorker`. The API shape is remarkably consistent + * across WeChat / ByteDance / Alipay / Baidu / quick-game: all use `postMessage` + `onMessage`, + * and all expose the worker-side global as `worker` (NOT `self`). + * + * Differences that the engine's backend layer must absorb: + * - `onError` is missing on some platforms (Huawei quick game documents only + * create/postMessage/onMessage/terminate) — guard before calling. + * - `onProcessKilled` is WeChat-only (iOS experimental worker reclamation). + * - The transfer list (second `postMessage` argument) is honored ONLY by WeChat V2. Huawei quick + * game documents data transfer as structured clone with no transferable objects; passing a + * transfer list elsewhere may throw, so omit it unless the platform supports it. + */ + export interface MinigameWorker { + postMessage(message: any, transfer?: any[]): void; + onMessage(listener: (res: any) => void): void; + onError?: (listener: (err: any) => void) => void; + terminate(): void; + /** WeChat only: fired when the system reclaims the worker process. */ + onProcessKilled?: (listener: (err: any) => void) => void; + } + export type AccelerometerIntervalMode = 'game' | 'ui' | 'normal'; export interface AccelerometerStartParameter { diff --git a/@types/pal/worker.d.ts b/@types/pal/worker.d.ts new file mode 100644 index 0000000000..6a16cdcfb6 --- /dev/null +++ b/@types/pal/worker.d.ts @@ -0,0 +1,61 @@ +/** + * Engine-side contract of the `pal/worker` module. + * + * Self-contained on purpose: type checking, IDE services and declaration builds must not depend on + * whether the installed PAL package ships a worker module. When `pal/worker` is absent (an older + * PAL, or the single-thread compatibility module which is JS only), TypeScript resolves the import to + * this ambient declaration. `tests/scripts/pal-worker-types.test.cjs` checks that a real PAL + * `worker/type.d.ts` stays structurally identical to these interfaces. + */ +declare module 'pal/worker' { + export interface IWorker { + postMessage (message: any, transfer?: Transferable[]): void; + onMessage (listener: (res: any) => void): void; + onError (listener: (err: any) => void): void; + terminate (): void; + } + + export interface IWorkerDiagnosis { + ready: boolean; + version: 0 | 1 | 2; + reason: string; + } + + export interface IWorkerBackend { + readonly concurrencyLimit: number; + readonly supportsTransfer: boolean; + readonly supportsSharedArrayBuffer: boolean; + readonly supportsFunctionWorker: boolean; + readonly capabilityReason: string; + createScriptWorker (path: string): IWorker; + diagnose (path: string): IWorkerDiagnosis; + } + + export interface IPlatformWorkerBackend extends IWorkerBackend { + readonly supportsStandardWorker: boolean; + readonly scriptFailureHint: string; + resolveScriptWorker (path: string): IWorkerResolution; + readonly hardwareConcurrency: number; + readonly scriptFallback: IPlatformWorkerBackend | null; + createFunctionWorker (fn: (...args: any[]) => any): IWorker | null; + } + + export interface IWorkerResolution { + backend: IPlatformWorkerBackend | null; + diagnosis: IWorkerDiagnosis; + warnOnFailure: boolean; + } + + export interface IWorkerCapabilities { + supportsStandardWorker: boolean; + available: boolean; + parallel: boolean; + concurrencyLimit: number; + supportsTransfer: boolean; + supportsSharedArrayBuffer: boolean; + supportsFunctionWorker: boolean; + reason: string; + } + + export function createWorkerBackend (): IPlatformWorkerBackend; +} diff --git a/EngineErrorMap.md b/EngineErrorMap.md index 0c9ca83449..1469eec28c 100644 --- a/EngineErrorMap.md +++ b/EngineErrorMap.md @@ -3996,3 +3996,71 @@ Spine version not supported. ### 16420 End time must bigger than start time. + +### 16500 + +WorkerPool script path must be a non-empty string + +### 16501 + +WorkerPool requires a self-contained task function or a worker script path + +### 16502 + +WorkerPool has been terminated + +### 16503 + +WorkerPool has no available execution backend + +### 16504 + +No worker backend for "%s" (%s). Provide options.fallback to run single-threaded, or fix packaging (docs/worker/README.md). + +### 16505 + +WorkerPool degraded to single-threaded for "%s": worker backend failed (%s). %s + +### 16506 + +WorkerPool is rejecting tasks (no options.fallback) for "%s": worker backend failed (%s). %s + +### 16507 + +WorkerPool could not use a worker for "%s" and is running single-threaded via options.fallback. Reason: %s. %s + +### 16508 + +WorkerPool could not use a worker for "%s" and is REJECTING tasks (no options.fallback). Reason: %s. %s + +### 16509 + +Worker error + +### 16510 + +Worker is unavailable and no synchronous fallback exists + +### 16511 + +Worker task timed out after %sms — the worker never replied (deadlock, infinite loop, or non-protocol script). Worker discarded; see docs/worker/README.md + +### 16512 + +Worker has been disposed + +### 16513 + +Worker script sent a malformed reply — it must implement the engine protocol: receive { id, args }, post back { id, ok, value } or { id, ok: false, error } (docs/worker/cc-worker-template.js) + +### 16514 + +Worker task failed + +### 16515 + +createWorker(path) requires a non-empty worker script path + +### 16516 + +Function workers are unavailable; use WorkerPool for an automatic sync fallback, or createWorker(path) (mode 2). diff --git a/cc.config.json b/cc.config.json index a0549df564..990c996a62 100644 --- a/cc.config.json +++ b/cc.config.json @@ -300,6 +300,13 @@ "overrideConstants": { "CULL_MESHOPT": false } + }, + "worker": { + "modules": ["worker"] + }, + "worker-pool": { + "modules": ["worker", "worker-pool"], + "dependentModules": ["worker"] } }, "moduleOverrides": [{ @@ -383,6 +390,7 @@ "isVirtualModule": true, "overrides": { "pal/minigame": "pal/minigame/non-minigame.js", + "pal/worker": "pal/worker/web/index.js", "pal/audio": "pal/audio/web/player.js", "pal/system-info": "pal/system-info/web/system-info.js", "pal/screen-adapter": "pal/screen-adapter/web/screen-adapter.js", @@ -397,6 +405,7 @@ "isVirtualModule": true, "overrides": { "pal/minigame": "pal/minigame/non-minigame.js", + "pal/worker": "pal/worker/native/index.js", "pal/audio": "pal/audio/native/player.js", "pal/system-info": "pal/system-info/native/system-info.js", "pal/screen-adapter": "pal/screen-adapter/native/screen-adapter.js", @@ -411,6 +420,7 @@ "isVirtualModule": true, "overrides": { "pal/minigame": "pal/minigame/{{context.platform.toLowerCase()}}.js", + "pal/worker": "pal/worker/minigame/index.js", "pal/audio": "pal/audio/minigame/player.js", "pal/system-info": "pal/system-info/minigame/system-info.js", "pal/screen-adapter": "pal/screen-adapter/minigame/screen-adapter.js", @@ -425,6 +435,7 @@ "isVirtualModule": true, "overrides": { "pal/minigame": "pal/minigame/runtime.js", + "pal/worker": "pal/worker/minigame/index.js", "pal/audio": "pal/audio/minigame/player.js", "pal/system-info": "pal/system-info/minigame/system-info.js", "pal/screen-adapter": "pal/screen-adapter/minigame/screen-adapter.js", @@ -439,6 +450,7 @@ "isVirtualModule": true, "overrides": { "pal/minigame": "pal/minigame/non-minigame.js", + "pal/worker": "pal/worker/nodejs/index.js", "pal/audio": "pal/audio/nodejs/player.js", "pal/system-info": "pal/system-info/nodejs/system-info.js", "pal/screen-adapter": "pal/screen-adapter/nodejs/screen-adapter.js", diff --git a/cocos/misc/index.ts b/cocos/misc/index.ts index d6ea2e3cba..0e1bd2b524 100644 --- a/cocos/misc/index.ts +++ b/cocos/misc/index.ts @@ -24,6 +24,12 @@ import './intersect'; +// NOTE: the worker subsystem (`./worker`, `./worker-pool`) is deliberately +// NOT re-exported here. `cocos/misc` is part of the always-on `base` feature, so anything exported +// from this file ships in every build's main bundle. The worker subsystem is exposed through the +// optional `worker` and `worker-pool` features instead (see their entries in `exports/` and +// cc.config.json). Projects enabling only `worker` do not include the pool scheduler. + export { Camera } from './camera-component'; export { ModelRenderer } from './model-renderer'; export { Renderer } from './renderer'; diff --git a/cocos/misc/worker-pool.ts b/cocos/misc/worker-pool.ts new file mode 100644 index 0000000000..f367a2b18f --- /dev/null +++ b/cocos/misc/worker-pool.ts @@ -0,0 +1,982 @@ +/* + Copyright (c) 2018-2023 Xiamen Yaji Software Co., Ltd. + + http://www.cocos.com + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies + of the Software, and to permit persons to whom the Software is furnished to do so, + subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. +*/ + +import type { IPlatformWorkerBackend } from 'pal/worker'; +import { + WorkerTask, IWorker, getOptimalWorkerCount, + getWorkerBackend, resetWorkerBackendCache, +} from './worker'; +import { getError, warnID } from '../core/platform/debug'; + +/** Execution state, independent of the host platform. */ +export type WorkerExecutionMode = 'worker' | 'sync' | 'none'; + +/** + * @en + * Infrastructure failures (a worker that never replies / times out, errors out, fails to spawn, or + * speaks a malformed protocol) tolerated before a script-mode pool gives up on the real worker and + * degrades to single-threaded execution via `options.fallback`. Kept at 1: each of these signals + * means the worker backend is not functioning for this script, so retrying on a real worker would + * only fail again — and on the seven single-worker mini-game platforms a retry would also re-occupy + * the one worker slot. A task-level computation error (the worker replies `{ ok: false }`) is NOT an + * infrastructure failure and never counts toward this. + * @zh + * 脚本模式的池在放弃真 Worker、降级为 `options.fallback` 单线程执行之前,所能容忍的**基础设施失败** + * 次数(Worker 永不回复 / 超时、报错、创建失败、或回发非法协议)。取 1:上述任一信号都意味着该脚本的 + * Worker 后端不可用,再用真 Worker 重试只会再次失败——而且在 7 个单 Worker 小游戏平台上重试还会重新 + * 占掉那唯一的槽位。任务级计算错误(Worker 回发 `{ ok: false }`)**不算**基础设施失败,不计入此数。 + */ +const DEGRADE_AFTER_FAILURES = 1; + +/** + * @en Options for [[WorkerPool]]. + * @zh [[WorkerPool]] 的选项。 + */ +export interface WorkerPoolOptions { + /** + * @en + * Maximum number of concurrent workers. Extra tasks are queued and dispatched when a worker frees up. + * Default is `1`. + * @zh + * 并发 Worker 的最大数量。多余的任务会排队,等某个 Worker 空闲后再派发。默认 `1`。 + */ + maxWorkers?: number; + /** + * @en + * Idle release time in milliseconds. An idle worker is terminated after being idle for this long, + * to avoid keeping threads (and their memory) alive forever. Set to `0` to never release idle workers. + * Default is `1000` (1 second). + * @zh + * 空闲释放时间(毫秒)。Worker 空闲超过该时长后会被终止,避免线程(及其内存)长期驻留。 + * 设为 `0` 表示永不释放空闲 Worker。默认 `1000`(1 秒)。 + */ + idleReleaseAfter?: number; + /** + * @en + * Synchronous fallback task (**script mode only**). It must compute the same result as the worker + * script's `runTask(args)` from the same `args`. When NO worker backend is available at all — + * the platform worker environment is not fully set up ([[checkWorkerScript]] not ready), or the + * platform has no worker API (Taobao mini-game, native) and there is no global `Worker` either — + * tasks run single-threaded on the main thread with this function instead of rejecting. If omitted + * in that situation, `run()` rejects with a descriptive error. + * Runtime failures retry non-transferred arguments only. Transferred tasks reject because + * ownership has moved; subsequent tasks use this fallback. Fallback computation must be retry-safe. + * @zh + * 同步降级任务函数(**仅脚本模式**)。它必须与 worker 脚本里的 `runTask(args)` 用相同的 `args` + * 算出相同的结果。当所有 Worker 后端都不可用时——平台 Worker 环境未设置完整 + * ([[checkWorkerScript]] 不 ready),或平台根本没有 Worker API(淘宝小游戏、原生)且也没有全局 + * `Worker`——任务将用它在主线程**单线程**执行,而不是直接 reject。若此时未提供该函数, + * `run()` 会以带说明的错误 reject。 + * 运行时失败仅重试未移交所有权的参数;已 transfer 的任务拒绝,后续任务仍使用 fallback。 + * fallback 应为可安全重试的计算逻辑。 + */ + fallback?: WorkerTask; + /** + * @en + * Per-task timeout in milliseconds. When exceeded, the task rejects with a timeout error and the + * worker running it is terminated so the pool spawns a fresh one. + * + * Default is `0` (no timeout). A timeout is the ONLY safety net against a worker that never + * replies — a worker script that fails to post back, or a worker silently reclaimed by the + * platform. Some platforms make this materially more likely: not every mini-game platform exposes + * `onError` (Huawei quick game documents only create/postMessage/onMessage/terminate), so an + * internal failure there produces no error event at all. + * + * Recommended for script mode in production: pick a bound well above your worst-case task duration. + * @zh + * 单个任务的超时时间(毫秒)。超时后任务以超时错误 reject,运行它的 Worker 会被终止, + * 池随后重建一个。 + * + * 默认 `0`(不超时)。超时是对"Worker 永不回复"的**唯一**兜底——比如 Worker 脚本忘记回发结果, + * 或 Worker 被平台静默回收。部分平台让这种情况更容易发生:并非每个小游戏平台都暴露 `onError` + * (华为快游戏只文档化了 create/postMessage/onMessage/terminate),那里的内部失败根本不会产生错误事件。 + * + * 生产环境的脚本模式建议设置超时:取一个明显高于最坏情况任务耗时的上界。 + */ + timeout?: number; +} + +/** + * @en + * A pool of workers bound to a single self-contained task function (function mode) or to a + * pre-packaged worker script (script mode — the only way to get a real worker on any mini-game + * platform, because they forbid rebuilding a function from source). + * + * It is designed for *high-frequency* workloads (e.g. per-frame physics / crowd simulation / data processing): + * instead of spawning and tearing down a worker for every call — which costs a Blob URL round-trip and + * thread startup — the pool keeps a bounded set of workers alive and reuses them, releasing idle workers + * after [[WorkerPoolOptions.idleReleaseAfter]]. + * + * IMPORTANT — a pool is not always a source of parallelism. On seven of the nine mini-game platforms + * (ByteDance, Alipay, Baidu, Huawei, OPPO, vivo, Xiaomi) and on WeChat V1, the platform allows exactly + * ONE worker, so the pool is capped to one worker no matter what `maxWorkers` says. There it is an + * **asynchronous offload queue**: it keeps a long task off the main thread, but it cannot run two tasks + * at once. Gate features that need true parallelism on + * [[getWorkerCapabilities]]`()`.parallel, not on whether a worker exists. + * + * In function mode, on platforms that cannot build a worker from a serialized string (every mini-game + * platform, and native) each task simply runs synchronously on the main thread, so the pool is a + * transparent no-op wrapper. To get a real worker on a mini-game platform, use script mode: + * `new WorkerPool('workers/my-task/index.js')` — the pool then creates its worker from a pre-packaged + * script via `minigame.createWorker` (see the constructor and the bundled template). + * + * For *CPU-bound* workloads on a genuinely parallel platform, pass [[getOptimalWorkerCount]] as + * `maxWorkers` to parallelize across the available cores (leaving one core for the main thread). Note + * that `maxWorkers` only matters when you submit several independent tasks concurrently — a single + * queued task always uses exactly one worker. + * + * @zh + * 绑定到单个自包含任务函数(函数模式)或预打包 Worker 脚本(脚本模式——这是在任何小游戏平台上获得 + * 真 Worker 的**唯一**方式,因为它们禁止用源码重建函数)的 Worker 池。 + * + * 它面向*高频*负载(如逐帧的物理模拟、人群模拟、数据处理):与其每次调用都创建再销毁一个 Worker—— + * 那会付出 Blob URL 往返和线程启动的成本——池会保活一个有上限的 Worker 集合并复用, + * 空闲超过 [[WorkerPoolOptions.idleReleaseAfter]] 的 Worker 会被释放。 + * + * **重要——池并不总是并行来源。** 9 个小游戏平台中有 7 个(抖音、支付宝、百度、华为、OPPO、vivo、小米) + * 以及微信 V1,平台只允许**恰好 1 个** Worker,因此无论 `maxWorkers` 传什么,池都会被封顶到 1 个。 + * 在这些平台上它是一个**异步卸载队列**:能把长任务从主线程挪走,但无法同时跑两个任务。 + * 需要真并行的特性,请以 [[getWorkerCapabilities]]`()`.parallel 为准,而不是以"有没有 Worker"为准。 + * + * 在函数模式下,凡是无法从序列化字符串构建 Worker 的平台(全部小游戏平台、原生),每个任务直接在主线程 + * 同步执行,因此池是一个透明的空包装。小游戏平台上若要真 Worker,请用脚本模式: + * `new WorkerPool('workers/my-task/index.js')`——池会通过 `minigame.createWorker` + * 从预打包脚本创建 Worker(参见构造函数与随附模板)。 + * + * 对于*真正可并行*平台上的 *CPU 密集型*负载,可将 [[getOptimalWorkerCount]] 作为 `maxWorkers` 传入, + * 跨可用核心并行(给主线程留一个核心)。注意:只有当你*同时*提交多个独立任务时 `maxWorkers` 才起作用—— + * 单个排队任务始终只用一个 Worker。 + * + * @example + * Function mode (Web real-parallel; mini-game / native transparent sync fallback): + * ```ts + * const pool = new WorkerPool((n: number) => { + * let acc = 0; + * for (let i = 0; i < n; i++) acc += Math.sqrt(i); + * return acc; + * }, { maxWorkers: getOptimalWorkerCount(), idleReleaseAfter: 1000 }); + * + * const result = await pool.run([1_000_000]); + * // ... + * pool.terminate(); + * ``` + * + * Script mode (a real worker on Web AND every mini-game platform that has one): + * ```ts + * // Backend chain resolved at construction: platform worker (only when fully set up — see + * // checkWorkerScript) → global Worker → single-threaded via options.fallback → run() rejects. + * // Pool size is auto-capped by the platform: 1 worker on the seven single-worker platforms and + * // WeChat V1; up to maxWorkers on WeChat V2 and Web. + * // On WeChat V2 pass an explicit maxWorkers to scale beyond 1 (core count is not detectable there). + * const pool = new WorkerPool('workers/heavy-compute/index.js', { + * maxWorkers: 4, + * // Optional: same computation as the worker script's runTask(args), used single-threaded + * // when no worker backend is available at all. Without it, run() would reject there. + * fallback: (n: number) => { let acc = 0; for (let i = 0; i < n; i++) acc += Math.sqrt(i); return acc; }, + * }); + * const result = await pool.run([1_000_000]); + * pool.terminate(); + * ``` + */ +export class WorkerPool { + private readonly _fn: WorkerTask | null; + private readonly _script: string | null; + private readonly _fallback: WorkerTask | null; + private readonly _idleReleaseAfter: number; + private readonly _timeout: number; + private readonly _explicitMax: number; + private _maxWorkers: number; + /** Execution state only; platform selection and identity belong to PAL. */ + private _executionMode: WorkerExecutionMode; + private _activeBackend: IPlatformWorkerBackend | null = null; + /** Changes only on recheck; runtime degradation stays in the same recovery generation. */ + private _backendGeneration = 0; + private _scriptFailureHint = ''; + private _backendReason: string; + private _workers: PooledWorker[] = []; + private _queue: PoolTask[] = []; + private _released = false; + private _draining = false; + private _taskId = 0; + /** + * @en Consecutive infrastructure failures on the real worker backend. Reset by [[WorkerPool.recheck]]. + * Reaching [[DEGRADE_AFTER_FAILURES]] triggers degradation to single-threaded sync execution. + * @zh 真 Worker 后端上累计的基础设施失败次数。[[WorkerPool.recheck]] 会重置;达到 + * [[DEGRADE_AFTER_FAILURES]] 即触发降级为单线程同步执行。 + */ + private _infraFailures = 0; + /** @en Whether this pool has degraded to single-threaded sync execution. @zh 本池是否已降级为单线程同步执行。 */ + private _degraded = false; + /** @en Guards against spamming the degradation warning (warn at most once per pool). @zh 防止重复刷降级警告(每池至多警告一次)。 */ + private _degradeWarned = false; + /** + * @en Guards the CONSTRUCTION-time degradation warning (at most once per pool, even across + * [[WorkerPool.recheck]] re-resolutions). @zh 防止重复刷**构造期**降级警告(每池至多一次,即便 + * [[WorkerPool.recheck]] 反复重解析)。 + */ + private _constructionWarned = false; + + /** + * @en + * Create a pool from a self-contained function or a packaged script path. + * PAL selects a usable script backend and its concurrency limit. When no backend is + * available, script tasks use options.fallback; without it, run() rejects with PAL's reason. + * Function tasks use a worker when PAL supports them, otherwise they execute inline. + * Scripts receive `{ id, args }` and reply with `{ id, ok, value }` or `{ id, ok: false, error }`. + * @zh + * 使用独立函数或已打包的脚本路径创建任务池。脚本后端的选择和并发上限由 PAL 提供。 + * 没有可用后端时,脚本任务执行 options.fallback;未提供则携带 PAL 的诊断原因拒绝任务。 + * 函数任务在 PAL 支持时使用 Worker,否则在主线程执行。 + * 脚本接收 `{ id, args }`,回复 `{ id, ok, value }` 或 `{ id, ok: false, error }`。 + */ + constructor (fnOrScript: WorkerTask | string, options?: WorkerPoolOptions) { + const isScriptMode = typeof fnOrScript === 'string'; + if (isScriptMode) { + if (!fnOrScript) { + throw new TypeError(getError(16500)); + } + this._script = fnOrScript; + this._fn = null; + } else { + if (typeof fnOrScript !== 'function') { + throw new TypeError(getError(16501)); + } + this._fn = fnOrScript; + this._script = null; + } + + const rawFallback = options ? options.fallback : undefined; + this._fallback = typeof rawFallback === 'function' ? rawFallback : null; + + const rawMax = options ? options.maxWorkers : undefined; + // An explicit, valid pool size (>= 1). 0 means "not specified" so we can apply a default below. + this._explicitMax = (typeof rawMax === 'number' && Number.isFinite(rawMax) && rawMax >= 1) + ? Math.floor(rawMax) + : 0; + + const rawTimeout = options ? options.timeout : undefined; + this._timeout = (typeof rawTimeout === 'number' && Number.isFinite(rawTimeout) && rawTimeout > 0) + ? rawTimeout + : 0; + + // Use `??` so an explicit `0` (meaning "never release idle workers") is preserved. + this._idleReleaseAfter = (options && options.idleReleaseAfter !== undefined) + ? options.idleReleaseAfter + : 1000; + + this._executionMode = 'none'; + this._backendReason = ''; + this._maxWorkers = 0; + this._resolveBackend(); + } + + /** + * @en + * (Re-)resolve which execution backend this pool uses, and cap the pool size accordingly. + * + * Split out of the constructor so [[WorkerPool.recheck]] can run it again later. Resolution is + * driven purely by runtime capability, never by a compile-time platform constant — branching on + * `WECHAT` is what left seven mini-game platforms with a working `createWorker` falling through to + * synchronous execution. + * @zh + * (重新)解析本池使用哪个执行后端,并据此封顶池大小。 + * + * 从构造函数中拆出,以便 [[WorkerPool.recheck]] 之后能再次调用。解析完全由**运行时能力**驱动, + * 绝不依赖编译期平台常量——正是对 `WECHAT` 的分支判断,让 7 个拥有可用 `createWorker` 的 + * 小游戏平台掉进了同步执行。 + */ + private _resolveBackend (): void { + const platform = getWorkerBackend(); + const explicitMax = this._explicitMax; + const desired = explicitMax > 0 ? explicitMax : getOptimalWorkerCount(); + this._activeBackend = null; + this._scriptFailureHint = platform.scriptFailureHint; + this._backendReason = ''; + + if (this._script) { + const resolved = platform.resolveScriptWorker(this._script); + if (resolved.backend) { + this._executionMode = 'worker'; + this._activeBackend = resolved.backend; + this._scriptFailureHint = resolved.backend.scriptFailureHint; + this._maxWorkers = Math.min(desired, resolved.backend.concurrencyLimit); + } else if (this._fallback) { + this._executionMode = 'sync'; + this._maxWorkers = 1; + this._warnConstructionDegrade(resolved.warnOnFailure, resolved.diagnosis.reason); + } else { + this._executionMode = 'none'; + this._maxWorkers = 0; + this._backendReason = getError(16504, this._script, resolved.diagnosis.reason); + this._warnConstructionDegrade(resolved.warnOnFailure, resolved.diagnosis.reason); + } + } else if (platform.supportsFunctionWorker) { + this._executionMode = 'worker'; + this._activeBackend = platform; + this._maxWorkers = Math.min(explicitMax > 0 ? explicitMax : 1, platform.concurrencyLimit); + } else { + this._executionMode = 'sync'; + this._maxWorkers = 1; + } + } + + /** + * @en + * Re-probe the platform and re-resolve the execution backend. + * + * The backend is normally decided once, at construction. That is wrong whenever capability appears + * LATER, which really happens: + * - the worker script lives in a WeChat subpackage that finishes downloading after the pool was + * created — `diagnose()` failed at construction because the file did not exist yet; + * - the base library hot-updates, or `wx.env.isSupportStandardWorker` flips as the V2 grey release + * rolls out to the device. + * + * Without this, a pool that probed too early stays locked to `'sync'`/`'none'` for its entire + * lifetime even though a real worker is now available. + * + * Idle executors are retired; busy executors finish their current task and are then retired. + * Queued tasks use the newly selected backend, or reject if it is unavailable without a fallback. + * Transferred tasks cannot be replayed after failure because ownership has already moved. + * + * @returns the execution state: `'worker'`, `'sync'` or `'none'`. + * @zh + * 重新探测平台并重新解析执行后端。 + * + * 后端通常只在构造时决定一次。但只要能力是**之后**才出现的,这就错了,而这确实会发生: + * - worker 脚本位于微信分包中,该分包在池创建之后才下载完成——构造时 `diagnose()` 因文件尚不存在而失败; + * - 基础库热更新,或随着 V2 灰度推送到该设备,`wx.env.isSupportStandardWorker` 发生翻转。 + * + * 没有这个入口,探测过早的池会在整个生命周期里被锁死在 `'sync'`/`'none'` 上, + * 即便真 Worker 现在已经可用。 + * + * 空闲执行器立即释放,忙碌执行器完成当前任务后释放。排队任务交给新后端; + * 若新后端不可用且没有 fallback,则拒绝排队任务。已移交所有权的任务失败后不能重放。 + * + * @returns 当前执行状态:`'worker'`、`'sync'` 或 `'none'`。 + */ + public recheck (): WorkerExecutionMode { + if (this._released) { + return this.backend; + } + // Give the real worker backend another chance: a subpackage may have finished downloading or + // the base library may have hot-updated since we degraded. Reset the failure budget so the + // fresh probe starts clean. (_degradeWarned stays sticky to avoid log spam across rechecks.) + this._infraFailures = 0; + this._degraded = false; + // Drop the cached platform probe so the next read reflects the current environment. + resetWorkerBackendCache(); + this._resolveBackend(); + this._backendGeneration++; + + // New tasks must use the newly resolved backend. Busy workers finish their current + // task, but are never reused after this capability check. + this._retireWorkers(); + this._drain(); + return this.backend; + } + + private _retireWorkers (): void { + for (let i = this._workers.length - 1; i >= 0; i--) { + const worker = this._workers[i]; + worker.retired = true; + if (!worker.busy) { + this._workers.splice(i, 1); + worker.dispose(); + } + } + } + + /** + * @en Current execution state: worker, synchronous fallback, or unavailable. + * @zh 当前执行状态:Worker、主线程同步回退,或不可用。 + */ + public get backend (): WorkerExecutionMode { + return this._executionMode; + } + + /** + * @en + * The resolved parallel worker count this pool will actually run tasks on + * (already clamped by the platform concurrency limit and the hardware estimate). + * Callers doing manual chunking should size their chunk count to this value so that chunks map + * 1:1 onto real parallel workers, instead of queueing serially on a single worker (e.g. WeChat V1, + * where `concurrencyLimit` is 1) and multiplying the per-frame round-trip latency. + * @zh + * 池实际会用于并行执行任务的 worker 数(已计入平台并发上限与硬件核数估计)。 + * 手动分块的调用方应按此值确定分块数,使分块与真实并行 worker 一一对应;否则在单 worker 平台 + * (如微信 V1,`concurrencyLimit` 为 1)上多块会串行排队,成倍放大每帧往返延迟。 + */ + public get concurrency (): number { + return this._maxWorkers; + } + + /** + * @en + * Queue a task and resolve with its return value when it completes. + * If a worker is free (or the pool is under `maxWorkers`), the task starts immediately; + * otherwise it waits in the queue. + * @zh + * 排队一个任务,完成时用其返回值 resolve。 + * 如果有空闲 Worker(或池中 Worker 数未达到 `maxWorkers`),任务立即开始;否则在队列中等待。 + * @param args Arguments passed to the task function. 传给任务函数的参数。 + * @param transfer Transferable objects to transfer to the worker. 零拷贝转移到 Worker 的对象。 + */ + public run (args?: unknown[], transfer?: Transferable[]): Promise { + return new Promise((resolve, reject) => { + if (this._released) { + reject(new Error(getError(16502))); + return; + } + if (this._executionMode === 'none') { + // Script mode, but no worker backend is available (WeChat worker not fully set up, + // no global Worker) and no options.fallback was provided — we cannot proceed. + reject(new Error(this._backendReason || getError(16503))); + return; + } + this._queue.push({ + args: args || [], + transfer: transfer || [], + resolve: (value: unknown): void => resolve(value as TResult), + reject, + }); + this._drain(); + }); + } + + /** + * @en + * Terminate all workers immediately and reject all pending tasks. + * @zh + * 立即终止所有 Worker,并拒绝所有排队中的任务。 + */ + public terminate (): void { + if (this._released) { + return; + } + this._released = true; + + const error = new Error(getError(16502)); + for (const task of this._queue) { + task.reject(error); + } + this._queue.length = 0; + + for (const w of this._workers) { + w.dispose(); + } + this._workers.length = 0; + } + + private _drain (): void { + if (this._released || this._draining) return; + this._draining = true; + try { + if (this._executionMode === 'none') { + const pending = this._queue.splice(0); + for (const task of pending) task.reject(new Error(this._backendReason)); + return; + } + while (this._queue.length > 0) { + let worker = this._findIdleWorker(); + if (!worker && this._workers.length < this._maxWorkers) { + try { + worker = this._spawnWorker(); + } catch (err) { + // Script-mode worker creation can throw synchronously (e.g. the path is not + // packaged into the `workers` directory, or a subpackage has not been downloaded). + // Treat it as an infrastructure failure: degrade so we stop respawning a broken + // backend, and re-run this task via the fallback when one exists (otherwise reject + // it). Keep draining either way so the remaining tasks are not left hanging. + const failed = this._queue.shift(); + this._onInfraFailure(failed || null, err as Error); + continue; + } + if (worker) { + this._workers.push(worker); + } + } + if (!worker) { + // No free worker and already at maxWorkers: wait for a completion callback. + return; + } + const task = this._queue.shift(); + if (task) { + this._dispatch(worker, task); + } + } + } finally { + this._draining = false; + } + } + + private _findIdleWorker (): PooledWorker | null { + for (const w of this._workers) { + if (!w.busy && !w.retired) { + return w; + } + } + return null; + } + + private _spawnWorker (): PooledWorker { + const generation = this._backendGeneration; + let worker: IWorker | null = null; + let fn = this._fn; + if (this._script) { + if (this._executionMode === 'worker') { + // Use the exact backend PAL selected, so creation matches its concurrency and capabilities. + worker = this._activeBackend!.createScriptWorker(this._script); + } else { + // 'sync' backend (no worker at all): run the user-provided fallback inline. + // ('none' never reaches here — run() rejects before queuing.) + fn = this._fallback; + } + } else if (this._executionMode === 'worker') { + worker = this._activeBackend!.createFunctionWorker(this._fn!); + if (!worker) { + // Capability disappeared before creation. Do not silently report a worker pool + // while scheduling multiple inline executors. + this._executionMode = 'sync'; + this._maxWorkers = 1; + this._retireWorkers(); + } + } + // A null `worker` leaves PooledWorker in inline mode → it runs `fn` synchronously. + const pooled = new PooledWorker(worker, fn, this._idleReleaseAfter, this._onWorkerIdle.bind(this), this._timeout); + // Route infrastructure failures (timeout / onError / malformed reply) on a REAL worker back to + // the pool so it can count them and degrade to single-threaded execution instead of hanging. + // An inline executor never triggers it, so the callback simply stays unused there. + pooled.onInfraFailure = (t: PoolTask, err: Error): void => { + // Only faults from before recheck belong to an obsolete backend. Workers retired + // by degradation still recover non-transferred tasks in the current generation. + if (generation !== this._backendGeneration) t.reject(err); + else this._onInfraFailure(t, err); + }; + return pooled; + } + + private _dispatch (worker: PooledWorker, task: PoolTask): void { + worker.busy = true; + worker.cancelIdleTimer(); + const id = ++this._taskId; + worker.onComplete = (): void => { + worker.busy = false; + if (worker.retired) this._onWorkerIdle(worker); + else this._drain(); + }; + // Once ownership has been transferred, the original arguments cannot be replayed safely. + task.transferred = !worker.isInline && !!this._activeBackend?.supportsTransfer && task.transfer.length > 0; + worker.execute(id, task); + } + + private _onWorkerIdle (worker: PooledWorker): void { + if (this._released) { + return; + } + if (worker.busy) { + return; + } + const idx = this._workers.indexOf(worker); + if (idx < 0) { + return; + } + this._workers.splice(idx, 1); + worker.dispose(); + // A worker was freed up (idle-release or failure): re-drain so queued tasks don't stall. + this._drain(); + } + + /** + * @internal + * Handle an INFRASTRUCTURE failure on a real worker: it timed out, errored, failed to spawn, or + * spoke a malformed protocol. These all mean the worker backend is not functioning for this + * script — unlike a task-level `{ ok: false }` reply (a genuine computation error), which is + * rejected directly and never reaches here. + * + * Script mode: count the failure and, once [[DEGRADE_AFTER_FAILURES]] is reached, degrade the + * WHOLE pool so no further task hangs on the broken backend. With `options.fallback` we switch to + * the `'sync'` backend (one inline executor on the main thread) and re-run the failed task through + * it, so the caller still gets a result instead of a rejection — the graceful "warn + run + * single-threaded" path the engine promises. Without a fallback there is no single-thread path to + * degrade to, so we keep the existing evict-and-respawn recovery and reject the task, but warn + * loudly so the developer learns the worker is broken and how to fix it. + * + * Function mode is deliberately EXCLUDED from degradation: its inline path is the SAME `_fn` that + * may have just deadlocked inside the worker, so running it on the main thread could move the hang + * onto the render thread. There we keep the existing recovery — reject the task, evict, respawn. + * + * @param task The in-flight task that failed, or `null` when the failure carries no task. + * @param error The infrastructure error. + */ + private _onInfraFailure (task: PoolTask | null, error: Error): void { + if (!this._script) { + // Function mode: no safe single-thread path (see above). Reject and let _settle evict + + // respawn a fresh worker, exactly as before the circuit breaker existed. + if (task) { + task.reject(error); + } + return; + } + + this._infraFailures++; + if (!this._degraded && this._infraFailures >= DEGRADE_AFTER_FAILURES) { + this._degraded = true; + if (this._fallback) { + // Graceful degradation: every future task runs on the main thread via the fallback. + this._executionMode = 'sync'; + this._backendReason = ''; + this._maxWorkers = 1; + // Drop idle real workers so the next dispatch goes to an inline executor, not a + // leftover worker on the backend we just gave up on. + this._retireWorkers(); + } + this._warnDegrade(error); + } + + if (!task) { + return; + } + if (this._executionMode === 'sync' && this._fallback && !task.transferred) { + // Re-run the failed task on the main thread. Front of the queue preserves ordering; the + // eviction-driven re-drain (runtime failure) or the _drain loop (spawn failure) dispatches + // it through an inline executor running the fallback. + this._queue.unshift(task); + } else { + task.reject(error); + } + } + + /** + * @internal + * Emit the one-time RUNTIME-degradation warning. `_degradeWarned` is sticky for the pool's + * lifetime so repeated failures — or a `recheck()` that re-degrades — never spam the log. + */ + private _warnDegrade (error: Error): void { + if (this._degradeWarned) { + return; + } + this._degradeWarned = true; + const script = this._script || '(function)'; + warnID(this._fallback ? 16505 : 16506, script, error.message, this._scriptFailureHint); + } + + /** PAL decides whether unavailable script execution deserves a one-time warning. */ + private _warnConstructionDegrade (warnOnFailure: boolean, reason: string): void { + if (!warnOnFailure || this._constructionWarned) { + return; + } + this._constructionWarned = true; + warnID(this._fallback ? 16507 : 16508, this._script || '(function)', reason, this._scriptFailureHint); + } +} + +/** + * @internal + */ +interface PoolTask { + args: unknown[]; + transfer: Transferable[]; + transferred?: boolean; + resolve: (value: unknown) => void; + reject: (reason?: unknown) => void; +} + +/** + * @internal + * A single pooled worker, either backed by a real Web Worker or an inline synchronous executor. + */ +class PooledWorker { + public busy = false; + public retired = false; + public onComplete: (() => void) | null = null; + /** + * @internal + * Set by the pool: called when an INFRASTRUCTURE failure occurs while a task is in flight — the + * worker timed out, errored, or spoke a malformed protocol. The pool counts these and (in script + * mode) degrades to single-threaded execution so nothing hangs. Deliberately distinct from a + * task-level `{ ok: false }` reply (a genuine computation error), which is rejected directly and + * never routed here. Only real workers ever trigger it; an inline executor cannot suffer an + * infrastructure failure (a throwing `fallback`/`_fn` is a task-level error). + */ + public onInfraFailure: ((task: PoolTask, error: Error) => void) | null = null; + + /** + * @en + * Whether this pooled worker runs tasks INLINE on the calling thread instead of owning a real + * worker. True for the `'sync'` backend and for function mode on platforms that cannot rebuild a + * function from source. Such an executor is a placeholder, not parallelism — [[WorkerPool.recheck]] + * retires the idle ones once a real backend appears. + * @zh + * 本池化 worker 是否在调用线程上**内联**执行任务,而非持有真正的 worker。 + * `'sync'` 后端、以及无法从源码重建函数的平台上的函数模式均如此。这类执行器只是占位而非并行—— + * 一旦真后端出现,[[WorkerPool.recheck]] 会把其中空闲的退役。 + */ + public get isInline (): boolean { + return this._worker === null; + } + + private readonly _worker: IWorker | null; + private readonly _fn: WorkerTask | null; + private readonly _idleReleaseAfter: number; + private readonly _timeout: number; + private readonly _onIdle: (worker: PooledWorker) => void; + private _current: PoolTask | null = null; + private _currentId = -1; + private _idleTimer: ReturnType | null = null; + private _timeoutTimer: ReturnType | null = null; + private _disposed = false; + private _failed = false; + + constructor ( + worker: IWorker | null, + fn: WorkerTask | null, + idleReleaseAfter: number, + onIdle: (worker: PooledWorker) => void, + timeout = 0, + ) { + this._worker = worker; + this._fn = fn; + this._idleReleaseAfter = idleReleaseAfter; + this._onIdle = onIdle; + this._timeout = timeout > 0 ? timeout : 0; + + if (worker) { + // IWorker.onMessage hands back the reply payload directly (the adapter unwraps `e.data` + // on Web, and WeChat's `onMessage` already passes `res`), so no MessageEvent here. + worker.onMessage((reply: IWorkerReply): void => { + this._onMessage(reply); + }); + worker.onError((e: any): void => { + this._failed = true; + if (this._current) { + // Busy: fail the in-flight task; _settle's `_failed` branch then evicts us. + this._settle(null, new Error(e && e.message ? String(e.message) : getError(16509))); + } else { + // Idle: there is no task to settle, but this worker is no longer trustworthy. + // It MUST be evicted here — otherwise it stays in the pool with `busy === false`, + // the next task gets dispatched onto it, and `postMessage` goes into a black hole + // (the task hangs forever, and script mode has no timeout to recover it). + // Real triggers: an uncaught async error inside the worker (e.g. a `setInterval` + // callback throwing), or WeChat killing the worker process (`onProcessKilled`). + this._evict(); + } + }); + } + } + + public execute (id: number, task: PoolTask): void { + this._current = task; + this._currentId = id; + if (!this._worker) { + if (!this._fn) { + // Script mode without a live worker should never reach here (run()/_drain guard it), + // but stay defensive: there is no function to run synchronously, so fail the task. + this._settle(null, new Error(getError(16510))); + return; + } + // Inline synchronous fallback (non-Worker platforms, function mode only). This blocks the + // main thread, which is the unavoidable behavior when no worker is available. + try { + const value = this._fn(...task.args); + this._settle(value, null); + } catch (err) { + this._settle(null, err as Error); + } + return; + } + // Arm before sending: adapters may synchronously report an error (or a test reply). + this.armTimeout(); + try { + this._worker.postMessage({ id, args: task.args }, task.transfer); + } catch (err) { + this._failed = true; + this._settle(null, err instanceof Error ? err : new Error(String(err))); + } + // Watchdog. Only meaningful for a REAL worker: the inline synchronous path above blocks the + // main thread for the whole duration, so a timer could never fire during it anyway. + // Without this, a worker that accepts the message and never replies — a script that deadlocks, + // an infinite loop, a platform that silently drops the message — leaves the task pending + // forever AND leaves that worker parked in the pool with `busy === true`, permanently + // shrinking the pool's effective size by one on every occurrence. + } + + /** + * @internal + * Start the per-task watchdog. On expiry the task is failed and this worker is EVICTED (not + * merely marked free): an unresponsive worker is indistinguishable from a dead one, so letting + * the pool reuse it would just hang the next task too. Eviction routes through `_onIdle`, which + * splices us out, disposes us and re-drains the queue onto a freshly spawned worker. + */ + private armTimeout (): void { + if (this._timeout <= 0) { + return; + } + this.cancelTimeoutTimer(); + const id = this._currentId; + this._timeoutTimer = setTimeout(() => { + this._timeoutTimer = null; + // Ignore a timer that outlived its task (shouldn't happen — _settle cancels it — but a + // stale timer firing against a NEW task would fail an innocent one). + if (!this._current || this._currentId !== id) { + return; + } + this._failed = true; + this._settle(null, new Error(getError(16511, this._timeout))); + }, this._timeout); + } + + private cancelTimeoutTimer (): void { + if (this._timeoutTimer !== null) { + clearTimeout(this._timeoutTimer); + this._timeoutTimer = null; + } + } + + public cancelIdleTimer (): void { + if (this._idleTimer !== null) { + clearTimeout(this._idleTimer); + this._idleTimer = null; + } + } + + public dispose (): void { + if (this._disposed) { + return; + } + this._disposed = true; + this.cancelIdleTimer(); + this.cancelTimeoutTimer(); + if (this._worker) { + this._worker.terminate(); + } + if (this._current) { + this._current.reject(new Error(getError(16512))); + this._current = null; + this._currentId = -1; + } + this.onComplete = null; + } + + private _onMessage (reply: IWorkerReply): void { + if (!this._current) { + return; + } + // Boundary check: the worker script must speak the engine protocol. A malformed reply means + // the packaged file is wrong (not based on the template) — fail loudly with a clear error + // instead of letting the task hang forever waiting for a well-formed reply. + if (!reply || typeof reply !== 'object' + || typeof reply.id !== 'number' + || typeof reply.ok !== 'boolean') { + this._failed = true; + this._settle(null, new Error(getError(16513))); + return; + } + // Guard against a stale/late reply from a previous task on the same worker. + if (reply.id !== this._currentId) { + return; + } + if (reply.ok) { + this._settle(reply.value, null); + } else { + this._settle(null, new Error(reply.error || getError(16514))); + } + } + + private _settle (value: unknown, error: Error | null): void { + const task = this._current; + if (!task) { + return; + } + this._current = null; + this._currentId = -1; + this.cancelTimeoutTimer(); + + if (error) { + if (this._failed && this.onInfraFailure) { + // Infrastructure failure (timeout / onError / malformed reply): the worker backend + // itself is not functioning. Hand the task to the pool, which counts the failure, + // degrades script-mode pools to single-threaded execution once the threshold is hit, + // and either re-runs this task via the fallback or rejects it. + this.onInfraFailure(task, error); + } else { + // Task-level failure (the worker replied { ok: false }, or an inline fallback/_fn + // threw): a genuine computation error, not a broken backend. Reject directly and keep + // trusting the worker. + task.reject(error); + } + } else { + task.resolve(value); + } + + // A worker that reported an uncaught error is not trustworthy for reuse: dispose it so the + // pool spawns a fresh one instead of replaying the same failure on every task. + if (this._failed) { + this._evict(); + return; + } + + // Mark idle (kicking off the idle-release timer) and notify the pool to drain the queue. + if (this._idleReleaseAfter > 0 && !this._disposed) { + this.cancelIdleTimer(); + this._idleTimer = setTimeout(() => { + this._idleTimer = null; + this._onIdle(this); + }, this._idleReleaseAfter); + } + + if (this.onComplete) { + const cb = this.onComplete; + this.onComplete = null; + cb(); + } + } + + /** + * @internal + * Retire this worker for good: drop any completion callback, clear the busy flag, and hand + * ourselves to the pool's idle hook (which splices us out of `_workers`, calls `dispose()` and + * re-drains the queue so queued tasks get a freshly spawned worker). + * + * Used by BOTH failure paths, which is the whole point of extracting it: `_settle`'s `_failed` + * branch (worker died while a task was in flight) and the idle `onError` branch (worker died + * while idle). The idle path can never reach the `_settle` branch, because `_settle` returns + * early when `_current` is null — routing it here is what stops a dead worker from silently + * swallowing the next task. + */ + private _evict (): void { + this.onComplete = null; + this.busy = false; + this._onIdle(this); + } +} + +/** + * @internal + */ +interface IWorkerReply { + id: number; + ok: boolean; + value?: unknown; + error?: string; +} diff --git a/cocos/misc/worker.ts b/cocos/misc/worker.ts new file mode 100644 index 0000000000..31fb9258c5 --- /dev/null +++ b/cocos/misc/worker.ts @@ -0,0 +1,413 @@ +/* + Copyright (c) 2018-2023 Xiamen Yaji Software Co., Ltd. + + http://www.cocos.com + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies + of the Software, and to permit persons to whom the Software is furnished to do so, + subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. +*/ + +import { createWorkerBackend } from 'pal/worker'; +import type { IWorker, IPlatformWorkerBackend, IWorkerCapabilities } from 'pal/worker'; +import { getError } from '../core/platform/debug'; + +export type { IWorker }; + +let backend: IPlatformWorkerBackend | undefined; + +/** @internal Shared by capability queries and WorkerPool. */ +export function getWorkerBackend (): IPlatformWorkerBackend { + return backend || (backend = createWorkerBackend()); +} + +/** @internal Re-probe PAL when a pool explicitly rechecks its capabilities. */ +export function resetWorkerBackendCache (): void { + backend = undefined; +} + +/** + * @en Current Worker capabilities reported by PAL. + * @zh PAL 提供的当前 Worker 能力。 + */ +export function getWorkerCapabilities (): IWorkerCapabilities { + const current = getWorkerBackend(); + return { + supportsStandardWorker: current.supportsStandardWorker, + available: current.concurrencyLimit > 0, + parallel: current.concurrencyLimit > 1, + concurrencyLimit: current.concurrencyLimit, + supportsTransfer: current.supportsTransfer, + supportsSharedArrayBuffer: current.supportsSharedArrayBuffer, + supportsFunctionWorker: current.supportsFunctionWorker, + reason: current.capabilityReason, + }; +} + +/** + * @en + * The task function executed inside a Web Worker. + * + * **Important**: the function must be *self-contained*: it is serialized via `Function.prototype.toString()` + * and reconstructed in a fresh global scope inside the worker, so it cannot capture variables from the + * enclosing closure, nor reference any engine / scene objects (`Node`, `Component`, `Vec3`, ...). + * Only plain data (numbers, strings, arrays, plain objects) and transferable buffers (`ArrayBuffer`, + * typed arrays backed by their own buffer) may cross the worker boundary. + * + * @zh + * 在 Web Worker 内执行的任务函数。 + * + * **注意**:函数必须*自包含*——引擎通过 `Function.prototype.toString()` 序列化函数并在 Worker 的全新全局作用域中重建, + * 因此它不能捕获外部闭包变量,也不能引用任何引擎 / 场景对象(`Node`、`Component`、`Vec3` 等)。 + * 只有普通数据(数字、字符串、数组、普通对象)和可转移缓冲区(`ArrayBuffer`、自带缓冲区的类型化数组)可以跨 Worker 边界传递。 + * + * @remarks + * @en + * The default argument type is `any[]` rather than `unknown[]`, deliberately. Arguments reach the task + * through a DYNAMIC array channel — `pool.run([1_000_000])` is `unknown[]`, spread internally as + * `fn(...args)` — so the type system can never relate what you pass to `run()` to what your task + * declares. An `unknown[]` parameter therefore buys zero safety while breaking the natural spelling: + * under `strictFunctionTypes` a concrete `(limit: number) => number` is NOT assignable to + * `(...args: unknown[]) => unknown`, so `new WorkerPool(fn, { fallback: countPrimes })` would not + * compile. `any[]` restores bivariance and lets the obvious code type-check. Pass explicit type + * arguments when you want the stricter shape: `WorkerTask<[number, number], number>`. + * @zh + * 默认参数类型刻意取 `any[]` 而非 `unknown[]`。参数是通过**动态数组通道**抵达任务函数的—— + * `pool.run([1_000_000])` 是 `unknown[]`,内部以 `fn(...args)` 展开——因此类型系统永远无法把你传给 + * `run()` 的东西与任务函数的声明关联起来。于是 `unknown[]` 参数**换不到任何安全性**,却破坏了最自然的写法: + * 在 `strictFunctionTypes` 下,具体的 `(limit: number) => number` **不能**赋值给 + * `(...args: unknown[]) => unknown`,导致 `new WorkerPool(fn, { fallback: countPrimes })` 无法编译。 + * `any[]` 恢复双变,让显而易见的代码通过类型检查。需要更严格的形状时请显式传类型参数: + * `WorkerTask<[number, number], number>`。 + */ +// `any[]` here is a deliberate, documented trade-off — see the remarks above. Do not "fix" it back to +// `unknown[]`: that reintroduces a compile error on every concrete task function. +// eslint-disable-next-line @typescript-eslint/no-explicit-any +export type WorkerTask = (...args: TArgs) => TResult; + +/** + * @en + * Detect whether the current environment supports spawning a Web Worker from a serialized function + * (i.e. `Worker` constructor + `Blob` + `URL.createObjectURL` are all available). + * + * This is the capability required by **mode 1** (pure-function workers used by [[WorkerPool]]). + * Native platforms run JavaScript inside an embedded engine (V8 / JavaScriptCore) + * without the browser host API, and mini-game platforms forbid runtime code evaluation and have no + * `Blob` (they use `createWorker` with a packaged script path instead), so both report `false` here + * and mode 1 falls back to running synchronously on the main thread. Use [[createWorker]]`(path)` + * (mode 2) for a real worker on a mini-game platform. + * + * NOTE: this answers "can I build a worker from a FUNCTION". It says nothing about whether the + * platform has workers at all — for that use [[getWorkerConcurrencyLimit]], which is nonzero on all + * nine mini-game platforms except Taobao. Conflating the two is what made a WeChat V2 build report + * an optimal worker count of 1. + * @zh + * 检测当前环境是否支持从序列化函数创建 Web Worker + * (即 `Worker` 构造器 + `Blob` + `URL.createObjectURL` 三者齐全)。 + * + * 这是**模式一**([[WorkerPool]] 使用的纯函数 Worker)所需的能力。 + * 原生平台在嵌入式 JS 引擎(V8 / JavaScriptCore)中运行、没有浏览器宿主 API;小游戏平台禁止运行时代码求值 + * 且没有 `Blob`(它们用 `createWorker` + 打包脚本路径),因此两者这里都返回 `false`, + * 模式一自动降级为主线程同步执行。小游戏平台上若要真正的 Worker,请用 [[createWorker]]`(path)`(模式二)。 + * + * 注意:本函数回答的是"能否从**函数**构建 Worker",与平台到底有没有 Worker 无关——后者请用 + * [[getWorkerConcurrencyLimit]],除淘宝外它在全部 9 个小游戏平台上都非零。 + * 把两者混为一谈,正是微信 V2 构建把最优 Worker 数报成 1 的原因。 + */ +export function isWorkerSupported (): boolean { + return getWorkerBackend().supportsFunctionWorker; +} + +/** + * @en + * Suggest a sensible worker count for CPU-bound (compute-heavy) tasks. + * + * The platform's concurrency cap is applied FIRST, because on seven of the nine mini-game platforms + * the limit is exactly one worker — a platform restriction, not a hardware one. Only where the + * platform allows many (Web, WeChat V2 standard worker) does the hardware estimate apply: + * `hardwareConcurrency - 1`, deliberately leaving one logical core for the main thread (rendering + + * game logic). This is a *starting point*, not a universal answer: I/O-bound tasks can benefit from + * more workers, and tiny per-frame tasks are often better off with `1`. + * + * Where `navigator.hardwareConcurrency` is unavailable — as is typically the case on mini-game + * platforms, which expose device info through their own APIs rather than `navigator` — this + * conservatively returns `1`. Size such a pool explicitly instead + * (`new WorkerPool(path, { maxWorkers: 4 })`). + * + * Returns `1` when the platform has no worker at all (native platforms, Taobao), matching the single + * inline executor the pool falls back to. + * + * @zh + * 为 CPU 密集型(重计算)任务推荐一个合理的 Worker 数量。 + * + * **平台并发上限优先**,因为 9 个小游戏平台中有 7 个上限恰好是 1 个 Worker——这是平台限制而非硬件限制。 + * 只有平台允许多 Worker 时(Web、微信 V2 标准 Worker)才采用硬件估算:`hardwareConcurrency - 1`, + * 刻意给主线程(渲染 + 游戏逻辑)留一个逻辑核。这是一个*起点*,不是普适答案:I/O 型任务可以开更多 Worker, + * 而每帧的小任务往往用 `1` 个更合适。 + * + * 当 `navigator.hardwareConcurrency` 不可用时——**包括全部小游戏平台**(它们都不暴露 `navigator`)—— + * 保守返回 `1`。这类平台请显式指定池大小(`new WorkerPool(path, { maxWorkers: 4 })`)。 + * + * 平台完全不支持 Worker 时(原生平台、淘宝)返回 `1`,与池降级使用的单个内联执行器一致。 + * + * @example + * ```ts + * const pool = new WorkerPool(myPureFn, { + * maxWorkers: getOptimalWorkerCount(), + * }); + * ``` + */ +export function getOptimalWorkerCount (): number { + const limit = getWorkerBackend().concurrencyLimit; + // No worker at all: the pool can only ever run one inline executor. + if (limit === 0) { + return 1; + } + // A hard platform cap (the seven single-worker mini-game platforms) wins over any hardware estimate. + // NOTE: the previous implementation reached this answer only by accident — it short-circuited on + // `isWorkerSupported()`, which tests FUNCTION-mode capability (Worker + Blob + URL). A WeChat V2 + // runtime has real multi-worker support but no Blob, so it was misreported as capped at 1. + if (limit !== Infinity) { + return limit; + } + const hc = getWorkerBackend().hardwareConcurrency; + return Math.max(1, Math.floor(hc) - 1); +} + +/** + * @en + * Whether the mini-game runtime supports the **standard (WeChat V2) worker**: multiple concurrent + * workers, `SharedArrayBuffer`, transfer lists in `postMessage`, `OffscreenCanvas`, etc. + * + * This is a WeChat-only capability today (detected via `minigame.env.isSupportStandardWorker`), but it + * is expressed as a backend capability rather than a platform check, so the answer stays correct if + * another platform later ships a standard worker. + * + * V2 is in grey release, so this MUST be checked at runtime before relying on any V2-only capability. + * It safely returns `false` (i.e. fall back to the single-worker generation) when: + * - the platform is not a mini-game platform at all (Web / native); + * - the platform has no `env.isSupportStandardWorker` (every non-WeChat mini-game platform); + * - `minigame.env` is undefined (old base library); + * - running in the WeChat devtools (V2 is not supported there yet). + * + * Without V2 the hard constraints are: at most **1** concurrent worker, data is structured-cloned + * (no transfer), and no platform API / rendering inside the worker. + * @zh + * 小游戏运行时是否支持**标准(微信 V2)Worker**:多并发 Worker、`SharedArrayBuffer`、 + * `postMessage` 的 transfer 列表、`OffscreenCanvas` 等。 + * + * 目前这是微信独有的能力(通过 `minigame.env.isSupportStandardWorker` 检测),但它被表达为后端能力 + * 而非平台判断,因此将来若其他平台也推出标准 Worker,这里的答案依然正确。 + * + * V2 仍在灰度,因此依赖任何 V2 能力前**必须**运行时检测。以下情况安全返回 `false`(即回退到单 Worker 代际): + * - 根本不是小游戏平台(Web / 原生); + * - 平台没有 `env.isSupportStandardWorker`(所有非微信小游戏平台); + * - `minigame.env` 为 undefined(旧基础库); + * - 微信开发者工具中运行(V2 暂不支持)。 + * + * 无 V2 时的硬约束:最多 **1** 个并发 Worker、数据走结构化克隆(无 transfer)、Worker 内无平台 API / 渲染。 + */ +export function isSupportStandardWorker (): boolean { + return getWorkerBackend().supportsStandardWorker; +} + +/** + * @en Result of [[checkWorkerScript]]: whether the platform worker environment is fully set up for a script path. + * @zh [[checkWorkerScript]] 的结果:平台 Worker 环境对某脚本路径是否设置完整。 + */ +export interface IWorkerScriptStatus { + /** + * @en Whether a worker can be used for this path. Only when `true` should you go the worker route. + * @zh 该路径能否使用 Worker。仅当为 `true` 时才应走 Worker 路线。 + */ + ready: boolean; + /** + * @en Worker version: `2` = standard (WeChat V2) worker, `1` = single-worker generation, `0` = unavailable. + * @zh Worker 版本:`2` = 标准(微信 V2)Worker,`1` = 单 Worker 代际,`0` = 不可用。 + */ + version: 0 | 1 | 2; + /** + * @en Human-readable reason when not ready (empty string when ready). Suitable for error messages. + * @zh 不可用时的原因说明(可用时为空字符串),可直接用于报错信息。 + */ + reason: string; +} + +/** + * @en + * Check whether the platform's worker environment is **fully set up** for the given script path. + * + * "Fully set up" means ALL of the following hold: + * 1. the platform exposes a worker API at all (`minigame.createWorker`, or a global `Worker`); + * 2. the path is valid: a non-empty **relative** path ending with `.js` (mini-game platforms reject + * absolute paths and non-JS files); + * 3. on mini-game platforms, the file **actually exists** in the code package (verified via + * `minigame.getFileSystemManager().accessSync`) and is **not empty** (best-effort `statSync`). + * A missing file usually means it was not placed in the workers directory declared in + * `game.json` (WeChat) / `manifest.json` (quick game) / `app.json`, or its subpackage has not + * been downloaded yet. + * + * When `ready` is `true`, `version` tells you which worker generation you got (`2` = WeChat standard + * multi-worker, `1` = single-worker generation). When `ready` is `false`, `reason` explains why, and + * callers should fall back to a standard Web `Worker` (if any), then to synchronous execution. + * @zh + * 检查平台的 Worker 环境对给定脚本路径是否**设置完整**。 + * + * "设置完整"指以下条件全部成立: + * 1. 平台确实暴露了 Worker API(`minigame.createWorker`,或全局 `Worker`); + * 2. 路径合法:非空、**相对路径**、以 `.js` 结尾(小游戏平台会拒绝绝对路径与非 JS 文件); + * 3. 在小游戏平台上,文件**确实存在**于代码包中(通过 `minigame.getFileSystemManager().accessSync` + * 校验)且**非空**(尽力而为的 `statSync`)。文件缺失通常意味着它没被放进 `game.json`(微信)/ + * `manifest.json`(快游戏)/ `app.json` 声明的 workers 目录,或所在分包尚未下载。 + * + * `ready` 为 `true` 时,`version` 表明拿到的 Worker 代际(`2` = 微信标准多 Worker,`1` = 单 Worker 代际)。 + * `ready` 为 `false` 时,`reason` 说明原因,调用方应降级到标准 Web `Worker`(若有),再不行就同步执行。 + */ +export function checkWorkerScript (path: string): IWorkerScriptStatus { + return getWorkerBackend().diagnose(path); +} + +/** + * @en + * The maximum number of worker instances that can run **concurrently** on the current platform. + * + * - Web (global `Worker`): effectively unlimited → `Infinity`. + * - WeChat **V2** standard worker (`env.isSupportStandardWorker`): multiple workers → `Infinity`. + * - WeChat V1, ByteDance, Alipay, Baidu, and the quick-game family (Huawei / OPPO / vivo / Xiaomi): + * only ONE worker at a time → `1`. + * - Taobao mini-game and native platforms (no worker API at all) → `0`. + * + * A cap of `1` means the platform has a worker but no parallelism: [[WorkerPool]] there is an + * **asynchronous offload queue** — it frees the main thread from a long task, but it cannot run two + * tasks at once. [[WorkerPool]] in **script mode** (`new WorkerPool(path)`) already caps its pool size + * per platform automatically (via [[checkWorkerScript]]), so it never tries to create more workers + * than the platform allows — creating a second worker on a single-worker platform fails. + * + * Do NOT pass this result directly as `maxWorkers`: where it returns `Infinity` the pool treats that + * as "not specified". Pass a concrete number instead: + * ```ts + * const pool = new WorkerPool('workers/my-task/index.js', { maxWorkers: 4 }); + * ``` + * @zh + * 当前平台上能够**并发**运行的 worker 实例数量上限。 + * + * - Web(全局 `Worker`):实际上无限制 → `Infinity`。 + * - 微信 **V2** 标准 Worker(`env.isSupportStandardWorker`):支持多 Worker → `Infinity`。 + * - 微信 V1、抖音、支付宝、百度,以及快游戏家族(华为 / OPPO / vivo / 小米):同一时刻仅 1 个 → `1`。 + * - 淘宝小游戏与原生平台(完全没有 Worker API)→ `0`。 + * + * 上限为 `1` 意味着平台有 Worker 但**没有并行能力**:此时 [[WorkerPool]] 是一个**异步卸载队列**—— + * 它能把长任务从主线程挪走,但无法同时跑两个任务。[[WorkerPool]] **脚本模式**(`new WorkerPool(path)`) + * 已通过 [[checkWorkerScript]] 自动按平台封顶池大小,不会创建超过平台允许的 Worker 数—— + * 在单 Worker 平台上创建第二个会失败。 + * + * 不要把本函数的返回值直接传给 `maxWorkers`:返回 `Infinity` 时池会将其视为"未指定"。请传具体数值: + * ```ts + * const pool = new WorkerPool('workers/my-task/index.js', { maxWorkers: 4 }); + * ``` + */ +export function getWorkerConcurrencyLimit (): number { + return getWorkerBackend().concurrencyLimit; +} + +/** + * @en + * Create a worker from a packaged script path (**mode 2**), aligned with `minigame.createWorker`. + * - Mini-game platforms (all nine): `minigame.createWorker(path)` — the script must live in the + * packaged workers directory declared in `game.json` (WeChat) / `manifest.json` (quick game) / + * `app.json`; if it is in a subpackage, download that subpackage first. + * - Web: `new Worker(path)` (the script must be same-origin). + * + * Unlike mode 1, this works on mini-game platforms because the worker code is a real packaged file + * rather than a runtime-serialized string (which those platforms forbid). The returned [[IWorker]] + * exposes the WeChat-aligned messaging API, and the caller defines its own message protocol + * (no envelope is imposed). + * + * Platform order matters and is decided by the backend, not by a platform constant: on a mini-game + * build the mini-game worker is tried first, and only if it is not fully set up (script missing, + * subpackage not yet downloaded, base library too old) does it fall through to a global `Worker` + * (which some devtools environments provide), then to a precise error. + * @zh + * 从打包好的脚本路径创建 Worker(**模式二**),对齐 `minigame.createWorker`。 + * - 小游戏平台(全部 9 个):`minigame.createWorker(path)`——脚本须位于 `game.json`(微信)/ + * `manifest.json`(快游戏)/ `app.json` 声明的 workers 目录内;若在分包中,需先下载该分包。 + * - Web:`new Worker(path)`(脚本需同源)。 + * + * 与模式一不同,这在小游戏平台上可用,因为 Worker 代码是真实打包文件而非运行时序列化字符串 + * (那些平台禁止后者)。返回的 [[IWorker]] 暴露对齐微信的消息 API,协议由调用方自定义(不强加信封)。 + * + * 平台顺序很重要,且由后端而非平台常量决定:小游戏构建下优先尝试小游戏 Worker,只有当它未完全就绪时 + * (脚本缺失、分包未下载、基础库过旧)才降级到全局 `Worker`(部分开发者工具环境提供),再不行就精确报错。 + * @internal + */ +function createWorkerFromPath (path: string): IWorker { + if (typeof path !== 'string' || !path) { + throw new TypeError(getError(16515)); + } + return getWorkerBackend().createScriptWorker(path); +} + +/** + * @en + * Create a worker. The signature is aligned with the mini-game `createWorker`: + * + * - `createWorker(path: string)` → **mode 2**: a worker loaded from a packaged script. Web uses + * `new Worker(path)`; every mini-game platform that has a worker uses + * `minigame.createWorker(path)` (WeChat / ByteDance / Alipay / Baidu / Huawei / OPPO / vivo / + * Xiaomi). Works on all of them. + * - `createWorker(fn: WorkerTask)` → **mode 1**: a worker built from a self-contained function + * (**Web only**). On mini-game platforms and native this throws, because they forbid rebuilding a + * function from source — use [[WorkerPool]] instead, which automatically falls back to + * synchronous execution there. + * + * Both return an [[IWorker]] (`postMessage` / `onMessage` / `onError` / `terminate`). Check + * [[getWorkerCapabilities]] first if you need to know whether the platform has a worker at all + * (Taobao mini-game and native do not). + * @zh + * 创建一个 Worker,签名对齐小游戏的 `createWorker`: + * + * - `createWorker(path: string)` → **模式二**:从打包脚本加载 Worker。Web 用 `new Worker(path)`; + * 每个有 Worker 的小游戏平台用 `minigame.createWorker(path)`(微信 / 抖音 / 支付宝 / 百度 / 华为 / + * OPPO / vivo / 小米),两端都可用。 + * - `createWorker(fn: WorkerTask)` → **模式一**:从自包含函数构建 Worker(**仅 Web**)。 + * 小游戏平台与原生下会抛错,因为它们禁止用源码重建函数——请改用 [[WorkerPool]], + * 它在这些平台会自动降级为同步执行。 + * + * 两者都返回 [[IWorker]](`postMessage` / `onMessage` / `onError` / `terminate`)。若需要先知道平台 + * 到底有没有 Worker(淘宝小游戏与原生没有),请先查 [[getWorkerCapabilities]]。 + * + * @example + * ```ts + * // Mode 2: your own packaged worker script (Web + all worker-capable mini-game platforms). + * const worker = cc.createWorker('workers/my-worker/index.js'); + * worker.onMessage((res) => { console.log(res); }); + * worker.postMessage({ cmd: 'compute', data }); + * worker.terminate(); + * ``` + */ +export function createWorker (path: string): IWorker; +export function createWorker (fn: WorkerTask): IWorker; +export function createWorker (pathOrFn: string | WorkerTask): IWorker { + if (typeof pathOrFn === 'function') { + const w = getWorkerBackend().createFunctionWorker(pathOrFn); + if (!w) { + throw new Error(getError(16516)); + } + return w; + } + return createWorkerFromPath(pathOrFn); +} diff --git a/docs/worker/README.md b/docs/worker/README.md new file mode 100644 index 0000000000..55cd4cc7d1 --- /dev/null +++ b/docs/worker/README.md @@ -0,0 +1,229 @@ +# Worker 使用与维护 + +Worker 分为两个可选引擎功能:`worker` 提供 `createWorker`、`getWorkerCapabilities`、 +`checkWorkerScript` 等基础 API;额外启用 `worker-pool` 才提供 `WorkerPool`。 +它们不会自动把渲染、物理、音频或业务逻辑移到其他线程。 + +## 安装与构建 + +正式依赖是 `@cocos/engine-pal`,当前锁文件解析为 `1.0.5`,包含 Worker 平台实现。在 cocos4 根目录执行: + +```sh +npm ci +npm run build +``` + +`npm run build` 先生成压缩 JS,再生成声明。日志中的 `Performance` 只统计模块分析和摇树, +后续压缩、source map 与写文件仍可能耗时数分钟,不能据此判断构建完成。 +`build:min` 每 15 秒输出累计耗时,正常完成后输出完成提示,失败时退出码为 1。 +是否成功仍以整个命令正常退出为准;进度提示不代表完成百分比。 + +`npm ci` 的 `postinstall` 会运行 `scripts/spread-pal.cjs`,将安装包的 `dist/` 复制到引擎 `pal/`。 +`pal/.pal-source.json` 记录复制来源和版本。`pal/` 是生成目录,不提交,不直接修改。 +仅拉取引擎代码、没有更新依赖,不等于已经安装新版 PAL。可检查: + +```sh +node -p "require('./node_modules/@cocos/engine-pal/package.json').version" +``` + +本地修改 PAL 源码时,在 `cocos-pal` 构建后,从 cocos4 根目录同步: + +```sh +node scripts/spread-pal.cjs --source ../cocos-pal/dist +npm run build +``` + +显式本地来源不会被构建检查自动换成 npm 包;恢复正式包时执行不带 `--source` 的 +`node scripts/spread-pal.cjs`。 + +## 启用功能与选择模式 + +在 Creator 的引擎功能裁剪配置中展开 **Worker** 分组,按需要勾选子项(两项默认均关闭): + +| 功能 | ccbuild 的 features | 从 cc 可用的能力 | +| --- | --- | --- | +| 基础 Worker 功能 | `['worker']` | 创建 Worker、收发消息、查询能力,由开发者管理生命周期 | +| Worker Pool | `['worker-pool']` | 基础 Worker API,以及任务池、队列、超时和安全同步降级 | + +分组标题的勾选框是全选/清空:只选基础 Worker 时显示半选;全选会同时启用 Worker Pool。 +勾选 Worker Pool 会关联开启基础 Worker;取消基础 Worker 时也会取消 Worker Pool。 +功能 ID 与项目已有配置保持兼容,无需迁移 `cache` 或 `includeModules`。 + +`worker-pool` 依赖 `worker`,Creator 会关联该依赖;直接调用 ccbuild 时,选择 `worker-pool` +也会包含两者的导出入口。`exports/worker.ts` 与 `exports/worker-pool.ts` 分别提供公开 API, +`cocos/misc/index.ts` 不导出它们。只启用 `worker` 的构建不包含线程池调度器;两项均不启用时, +也会裁掉基础 Worker API 及其 PAL Worker 依赖。完整引擎预构建仍会生成所有模块,项目构建时才按配置裁剪。 + +**迁移已有项目:** 之前只启用 `worker` 且使用了 `WorkerPool` 的项目,需要额外启用 `worker-pool`, +并重新构建。仅手动管理 Worker 的项目保留 `worker` 即可。`cc` 导入名称及运行时协议不变。 + +- **脚本模式**:`new WorkerPool('workers/task.js', options)`,适用于 Web 和提供 Worker 的小游戏环境。 +- **函数模式**:`new WorkerPool(fn, options)`,Web 在具备 Worker、Blob、对象 URL 能力时创建真实 Worker; + 不支持时在主线程执行原函数。函数必须自包含,不能捕获外部变量。 +- **自定义消息服务**:`createWorker(path)` 返回 `postMessage/onMessage/onError/terminate` 接口。 + 它不提供任务池协议或自动同步 fallback。长期音频、网络等消息服务应自行管理消息和生命周期。 + +仅启用 `worker` 时可以这样自行管理: + +```ts +import { createWorker, getWorkerCapabilities } from 'cc'; + +if (getWorkerCapabilities().available) { + const worker = createWorker('workers/service.js'); + worker.onMessage(result => console.log(result)); + worker.onError(error => { console.error(error); worker.terminate(); }); + worker.postMessage({ command: 'compute', value: 21 }); + // 在服务结束或组件销毁时调用 worker.terminate()。 +} else { + // 由业务自行处理无 Worker 的情况。 +} +``` + +原生和 Node.js 的 PAL Worker 入口报告不支持 JS Worker,不因宿主偶然存在全局 `Worker` 而创建它。 +池可在主线程执行函数或显式 fallback;原生子系统自身的线程策略由原生实现决定。 + +## 脚本模式最小示例 + +复制 [`cc-worker-template.js`](./cc-worker-template.js) 到项目构建输出的 `workers/task.js`, +在其 `runTask(args)` 中实现计算逻辑。模板兼容 Web `self` 和小游戏 `worker` 消息入口。 + +```ts +import { WorkerPool } from 'cc'; + +const pool = new WorkerPool('workers/task.js', { + maxWorkers: 4, + timeout: 5000, + fallback: (n: number) => n * 2, // 必须与脚本计算等价,并允许安全重试 +}); +try { + const result = await pool.run([21]); + console.log(result, pool.backend, pool.concurrency); +} finally { + pool.terminate(); +} +``` + +对应脚本中的任务函数为: + +```js +function runTask(args) { + return args[0] * 2; +} +``` + +脚本接收 `{ id, args }`,回复 `{ id, ok: true, value }` 或 `{ id, ok: false, error }`。 +自定义脚本必须保留该协议。主线程场景对象、DOM、闭包变量无法直接在 Worker 内使用。 + +引擎不会自动复制项目 Worker 脚本或修改小游戏打包配置。必须保证: + +1. Web 的脚本路径能在最终部署地址访问,且满足同源和安全策略要求。 +2. 小游戏脚本位于平台声明的 Worker 目录内。微信在构建产物 `game.json` 中配置 + `"workers": "workers"`;分包脚本需先下载分包。 +3. 微信 Worker 的 `require` 依赖也在 Worker 目录内;该目录只放 JS 文件。 + +完整示例见 [`examples/worker-demo.ts`](./examples/worker-demo.ts) 和 +[`examples/prime-worker.js`](./examples/prime-worker.js)。需启用 Worker Pool 功能并打包脚本。 +示例耗时包含启动、消息传递和计算成本,加速比不是通过标准。 + +## 能力检测与微信 V1/V2 + +```ts +import { getWorkerCapabilities, checkWorkerScript } from 'cc'; + +console.log(getWorkerCapabilities()); +console.log(checkWorkerScript('workers/task.js')); +``` + +`available` 表示平台报告存在 Worker 能力;`parallel` 表示并发上限大于 1。 +它们不保证特定脚本可以运行。实际池状态应看 `pool.backend`(`worker / sync / none`), +实际池大小看 `pool.concurrency`。Web 的脚本加载和执行错误可能在创建后才异步报告。 + +PAL 1.0.5 对非标准小游戏 Worker 的并发上限保守设为 1,对标准 Worker 和 Web 不设固定平台上限; +实际创建数量仍受 `maxWorkers`、设备与运行时限制,创建可能失败。 + +微信 V1/V2 都使用 `wx.createWorker(path)`。PAL 以 +`wx.env.isSupportStandardWorker === true` 判断标准 Worker 能力,未提供或为 false 时按单 Worker、 +无 transfer 处理,不根据系统类型或版本号强行开启。`useExperimentalWorker` 不是 V2 开关。 +基础库、客户端、灰度和开发者工具的当前支持范围,应查阅微信官方文档并在目标环境验证; +版本达标也不能代替能力检测。 + +标准 Worker 支持的 OffscreenCanvas、音频和网络能力不等于引擎会自动使用它们。 +Canvas 需由主线程通过 `transferControlToOffscreen()` 转移;Worker 内平台 API 使用 `worker.xxx`。 +SharedArrayBuffer 在消息中共享,不放入 transfer 列表;跨 realm 检测可用 +`buffer?.constructor?.name === 'SharedArrayBuffer'`,避免依赖 `instanceof`。 + +## 失败恢复、transfer 与 recheck + +脚本后端由 PAL 选择:优先平台 Worker;适用时再尝试全局 Web Worker;都不可用时使用显式 +`options.fallback`。没有 fallback 则任务拒绝。函数模式不支持 Worker 时直接执行原函数。 + +- `timeout` 默认 0,表示关闭。生产脚本建议按最坏任务耗时设置超时,以处理永不回复的 Worker。 +- 脚本创建失败、忙时错误、超时、畸形回复和发送异常属于基础设施失败。有 fallback 时,池降级为同步执行。 +- 未移交所有权的失败任务可用 fallback 重算;已经 transfer 的任务拒绝,后续任务使用同步 fallback。 + 业务必须保证 fallback 可安全重试。 +- 同一次降级中,其他忙碌 Worker 完成后退役;它们随后失败时,未 transfer 的任务仍可恢复。 + `retired` 只表示不再复用,不能单独作为禁止 fallback 的依据。 +- `recheck()` 刷新能力并选择新后端,推进后端代次;检查前的旧 Worker 失败只拒绝其原任务, + 不会再次熔断新后端。排队任务交给新后端,或在无后端且无 fallback 时拒绝。 +- Worker 正常返回 `{ ok: false }` 属于任务计算错误,直接拒绝,不触发基础设施降级。 +- 函数模式的运行时故障不自动在主线程重放原函数,避免将可能死锁的函数移到主线程。 + +`run(args, transfer)` 可能移交缓冲区所有权。需要恢复数据时应保留副本或能够重新生成参数。 +脚本模板不自动 transfer 返回值;Web 函数模式 bootstrap 会递归收集可转移返回值, +处理循环引用、深层对象、自有属性和去重,SharedArrayBuffer 不参与 transfer。 + +正式构建使用错误编号,完整说明保留在 `EngineErrorMap.md` 的 16500—16516 条目; +调试构建保留详细消息。诊断参数、任务拒绝和降级行为在正式构建中仍然有效。 + +## 平台抽象与旧 PAL 兼容 + +`cocos/misc/worker-pool.ts` 只负责调度、队列、超时和恢复;`worker.ts` 管理能力快照及后端缓存。 +平台 API、脚本检查、消息适配和函数 bootstrap 位于 `cocos-pal/src/worker`。 +`cc.config.json` 将 `pal/worker` 映射到 web、minigame、native、nodejs 入口。 + +`@types/pal/worker.d.ts` 提供引擎侧独立类型契约,`tests/scripts/pal-worker-types.test.cjs` +校验其与已安装 PAL 的声明一致。它不依赖生成的兼容声明文件。 + +安装与各仓库构建入口调用统一的 `scripts/ensure-pal.cjs`: + +1. npm 来源的 `pal/` 与已安装包版本不同:重新复制整个 PAL。 +2. Worker 缺失或为引擎兼容实现,来源已有真实实现:恢复真实 Worker。 +3. 来源完全没有 Worker:生成 JS 单线程兼容实现,支持未更新依赖的旧环境构建。 +4. 已有真实 Worker 实现:不做局部覆盖;不完整的真实模块需要重新执行 spread 修复。 + +兼容实现共享文件为 `pal/worker/compat.js`,不生成根 `index.js`,避免绕过平台映射或留下解析缓存。 +来源为 `--source` 的目录只从该来源恢复;不会混入 npm 的 Worker。整个 `pal/` 缺失时仍需先安装依赖。 +这些检查不能代替安装新版本依赖;仅拉取引擎后继续使用旧 npm 包,仍可能使用同步兼容。 +编辑器绕过仓库构建脚本时,应先完成安装和 spread。 + +新增 PAL 检查可在 `scripts/ensure-pal.cjs` 增加独立函数并注册到 `checks`。 +检查必须幂等,修改返回 true,无需修改返回 false,无法继续构建时抛出错误。 + +## 测试与验收 + +在 cocos4 根目录执行: + +```sh +npm run test:pal +npm test -- --runInBand +node scripts/test-worker-release.cjs +``` + +- `test:pal`:同步来源、旧 PAL 兼容、升级/降级、构建入口及类型契约。 +- `tests/misc/worker-*.test.ts`:实际 PAL 产物上的平台能力、Web/微信路径、队列、生命周期、超时、 + 代次隔离、并发降级、transfer 和函数 bootstrap。平台 API 为可控替身;旧 PAL 专项使用兼容模块。 +- `test-worker-release.cjs`:实际编译仅 Worker、Worker Pool 及未启用两项功能的 HTML5 产物, + 检查导出、手动消息通信及 source map 模块清单,验证裁剪边界;同时保留正式错误编号、 + 调度、消息协议、transfer 失败恢复及 recheck 检查。它要求安装带 Worker 的 PAL。 + +合入前还应在 cocos-test-projects 的 `assets/cases/scene/worker-test/worker.scene` 验收: + +1. Web:对比主线程与 Worker 模式,确认结果一致、场景持续更新,池状态确为 `worker`; + 禁用 Worker API 后确认 fallback。反复切换模式和销毁场景,不应留下任务或线程。 +2. 微信:检查最终 `game.json` 和脚本文件,分别验证非标准单 Worker 环境和有标准能力标志的环境; + 验证脚本缺失、未下载分包、创建失败、超时与 transfer 后失败。 +3. 原生:确认不启动 JS Worker,函数或显式 fallback 在主线程运行。 +4. 裁剪:在相同构建参数下对比开启/关闭 Worker,分别记录原始和压缩包体;不能用旧包或不同配置比较。 + +自动测试和 ccbuild 成功不代表浏览器、开发者工具或真机已通过。验收记录应包含引擎提交、PAL 版本、 +平台/客户端环境、构建参数、池状态与结果;不得把 `sync` fallback 当成真实 Worker 成功。 diff --git a/docs/worker/cc-worker-template.js b/docs/worker/cc-worker-template.js new file mode 100644 index 0000000000..b4be46cf29 --- /dev/null +++ b/docs/worker/cc-worker-template.js @@ -0,0 +1,100 @@ +/** + * Cocos universal worker entry template (Web + WeChat mini-game). + * + * This is a READY-MADE worker file you copy into your own project. It implements the exact message + * protocol expected by the engine's `cc.WorkerPool` (script mode) and `cc.createWorker(path)`, and it + * runs on BOTH Web (`self.onmessage`) and WeChat (`worker.onMessage`) with no further changes. + * + * WHY A PHYSICAL FILE IS REQUIRED ON WECHAT + * ----------------------------------------- + * WeChat mini-games have no global `Worker` constructor and FORBID dynamically executing JS code + * (`eval` / `new Function` are banned). So the engine cannot ship a function's source string and + * rebuild it inside a WeChat worker. The only way to get real parallelism on WeChat is to write the + * task into a physical JS file like this one, package it, and declare it in `game.json`. + * + * HOW TO USE + * ---------- + * Enable the `worker-pool` engine feature (which depends on `worker`) for the pool example below. + * `createWorker(path)` alone only requires `worker`; the caller manages its message protocol. + * 1. Copy this file into your project's worker directory, e.g. `workers/heavy-compute/index.js`. + * 2. Implement your pure computation in `runTask(args)` below. It MUST be self-contained: it runs in + * a separate thread and CANNOT access `cc`, the scene, the DOM, or any closure variable from the + * main thread. Only `args` (structured-cloned) is available as input, and the return value must be + * structured-cloneable (or a Transferable such as ArrayBuffer / TypedArray). + * 3. Package & configure: + * - WeChat: declare the worker root in the built `game.json` -> { "workers": "workers" }, and make + * sure this file lives inside that directory. WeChat V1 allows only ONE worker at a time; V2 + * (standard worker, gray release / Android) allows multiple. The engine pool auto-caps to the + * platform limit, so you do not need to branch on this yourself. + * - Web: make sure this file is served at the same path you pass to the pool. + * 4. Drive it from the main thread: + * // Pool size defaults to a CPU-based count and is auto-capped per platform (WeChat V1 => 1). + * // On WeChat V2 pass an explicit maxWorkers to scale beyond 1 (core count is not detectable there). + * const pool = new cc.WorkerPool('workers/heavy-compute/index.js', { maxWorkers: 4 }); + * const result = await pool.run([1000000]); // args array -> runTask(args) + * pool.terminate(); + * + * MESSAGE PROTOCOL (must match the engine; do not change the plumbing below) + * -------------------------------------------------------------------------- + * main -> worker : { id: number, args: any[] } + * worker -> main : { id: number, ok: true, value: any } + * | { id: number, ok: false, error: string } + */ + +// ==== YOUR TASK: put your pure, self-contained computation here ================== +function runTask (args) { + // `args` is exactly the array you passed to `pool.run([...])`. + // Example below: a heavy numeric loop. Replace it with your own logic. + var n = (args && args[0]) || 0; + var acc = 0; + for (var i = 0; i < n; i++) { + acc += Math.sqrt(i); + } + return acc; + + // ---- Multi-task variant (optional) ------------------------------------------- + // If one worker file should handle several kinds of work, dispatch on an argument: + // switch (args && args[0]) { + // case 'normals': return computeNormals(args[1]); + // case 'lod': return computeLod(args[1]); + // default: throw new Error('unknown task: ' + (args && args[0])); + // } + // Remember: every helper you call (computeNormals, ...) must also be defined in THIS file + // (or required from another file inside the same worker directory). +} +// ================================================================================= + +// ---- Message plumbing (works on Web and WeChat; normally no need to edit) -------- + +function handleMessage (msg) { + var id = msg && msg.id; + try { + var value = runTask(msg && msg.args); + reply({ id: id, ok: true, value: value }); + } catch (e) { + reply({ id: id, ok: false, error: String((e && e.message) || e) }); + } +} + +function reply (msg) { + // WeChat mini-game: the global `worker` object. + if (typeof worker !== 'undefined' && worker && typeof worker.postMessage === 'function') { + worker.postMessage(msg); + return; + } + // Web Worker: the global `self`. + if (typeof self !== 'undefined' && typeof self.postMessage === 'function') { + self.postMessage(msg); + } +} + +// Register the message handler for the current platform (mutually exclusive). +if (typeof worker !== 'undefined' && worker && typeof worker.onMessage === 'function') { + // WeChat mini-game worker. + worker.onMessage(handleMessage); +} else if (typeof self !== 'undefined') { + // Web Worker. + self.onmessage = function (e) { + handleMessage(e && e.data); + }; +} diff --git a/docs/worker/examples/worker-demo.ts b/docs/worker/examples/worker-demo.ts new file mode 100644 index 0000000000..8c41f7c266 --- /dev/null +++ b/docs/worker/examples/worker-demo.ts @@ -0,0 +1,114 @@ +/** + * WorkerPool 脚本模式示例:同时提交 4 个计算任务,并与主线程结果比较。 + * + * 1. 在引擎功能配置中启用 worker-pool(会依赖 worker)。 + * 2. 将 prime-worker.js 打包为 workers/prime-worker.js;微信还需配置 game.json 的 workers 目录。 + * 3. 将此组件挂到场景节点,检查结果一致性、实际 pool.backend 和 pool.concurrency。 + * + * Web 和标准小游戏 Worker 可按能力并发,其他小游戏 Worker 可能只有一个槽位。 + * 没有可用 Worker 或发生安全可恢复的故障时,显式 fallback 在主线程执行。 + * 计时包含 Worker 启动、消息传递和计算,设备、任务大小和预热都会影响结果; + * 不能用单次加速比判断平台支持性,也不能把 sync fallback 当成 Worker 成功。 + */ +import { + _decorator, Component, WorkerPool, checkWorkerScript, getWorkerCapabilities, +} from 'cc'; + +const { ccclass } = _decorator; + +const WORKER_PATH = 'workers/prime-worker.js'; +const LIMIT = 200_000; // 计算小于该值的素数个数;单任务约 100~300ms,可按机器性能调整 +const TASKS = 4; +// worker 收下消息却永不回复时的兜底(死锁 / 无限循环 / 平台静默丢消息)。 +// 触发后 Worker 被驱逐,本示例通过 fallback 重算并降级。0 = 关闭。 +const TIMEOUT = 10_000; + +// 与 prime-worker.js 中 runTask(args) 完全一致的算法: +// 1) 作为串行基线计时;2) 作为无 worker 后端时的单线程降级(options.fallback)。 +// 两处必须保持同步——demo 会对比二者结果来证明 worker 链路计算正确。 +function countPrimes (limit: number): number { + let count = 0; + for (let n = 2; n < limit; n++) { + let isPrime = true; + for (let d = 2; d * d <= n; d++) { + if (n % d === 0) { isPrime = false; break; } + } + if (isPrime) { count++; } + } + return count; +} + +@ccclass('WorkerDemo') +export class WorkerDemo extends Component { + public start (): void { + this.benchmark().catch((e) => { + console.error('[WorkerDemo] benchmark failed:', e); + }); + } + + private async benchmark (): Promise { + // 0a) 平台能力快照——业务决定"要不要开这个特性"的正确依据。 + // 注意 parallel 与 available 的区别:7 个小游戏平台 available 为真但 parallel 为假。 + const caps = getWorkerCapabilities(); + console.log(`[WorkerDemo] capabilities: available=${caps.available} ` + + `parallel=${caps.parallel} concurrencyLimit=${caps.concurrencyLimit} ` + + `transfer=${caps.supportsTransfer} sab=${caps.supportsSharedArrayBuffer}`); + console.log(`[WorkerDemo] capability reason: ${caps.reason}`); + + // 0b) 脚本路径预检:文件是否真的在代码包里、路径是否合法。 + // 引擎内部也做同样的检查来决定后端:平台 worker → Web Worker → fallback 单线程 → 报错。 + const status = checkWorkerScript(WORKER_PATH); + console.log(`[WorkerDemo] checkWorkerScript: ready=${status.ready} ` + + `version=${status.version} reason="${status.reason}"`); + + // 1) 串行基线:主线程连续算 TASKS 次。 + const t0 = Date.now(); + let expected = 0; + for (let i = 0; i < TASKS; i++) { + expected = countPrimes(LIMIT); + } + const serialMs = Date.now() - t0; + + // 2) WorkerPool 并行:后端由引擎自动解析,池大小自动按平台 concurrencyLimit 封顶 + // (7 个单 worker 平台 + 微信 V1 → 1;微信 V2 / Web → maxWorkers)。 + const pool = new WorkerPool(WORKER_PATH, { + maxWorkers: TASKS, + timeout: TIMEOUT, + fallback: countPrimes, // 无任何 worker 后端时单线程兜底,保证 demo 总能跑通 + }); + console.log(`[WorkerDemo] resolved backend: ${pool.backend}`); + + const t1 = Date.now(); + let results: number[]; + try { + results = await Promise.all( + Array.from({ length: TASKS }, () => pool.run([LIMIT])), + ); + } finally { + pool.terminate(); + } + const poolMs = Date.now() - t1; + + // 3) 验证:所有任务结果必须与串行基线一致。 + const allMatch = results.every((r) => r === expected); + console.log(`[WorkerDemo] primes below ${LIMIT} = ${expected}, results match: ${allMatch}`); + + const speedup = serialMs / Math.max(1, poolMs); + console.log(`[WorkerDemo] serial: ${serialMs}ms | pool(${TASKS} tasks): ${poolMs}ms ` + + `| speedup: ${speedup.toFixed(2)}x`); + + // 启动和通信成本也在计时内。以结果和实际后端验收,不用加速比推断是否正确。 + if (pool.backend === 'sync') { + console.warn('[WorkerDemo] 池已走 fallback 单线程执行,请检查平台能力、脚本打包和运行时降级日志。'); + } else if (pool.concurrency <= 1) { + console.log('[WorkerDemo] 当前池只使用 1 个 Worker,任务可异步卸载,但不会并行执行。'); + } else { + console.log('[WorkerDemo] 当前池支持多个 Worker;实际收益需在目标设备上重复测量。'); + } + + if (!allMatch) { + throw new Error('[WorkerDemo] worker 脚本与 fallback 结果不一致,' + + '请检查 prime-worker.js 与 countPrimes 算法是否同步!'); + } + } +} diff --git a/editor/engine-features/render-config.json b/editor/engine-features/render-config.json index d2b25cf063..ca18a37631 100644 --- a/editor/engine-features/render-config.json +++ b/editor/engine-features/render-config.json @@ -346,6 +346,21 @@ "enginePlugin": false, "category": "network" }, + "worker": { + "default": false, + "label": "i18n:ENGINE.features.worker.label", + "description": "i18n:ENGINE.features.worker.description", + "enginePlugin": true, + "category": "worker" + }, + "worker-pool": { + "default": false, + "label": "i18n:ENGINE.features.worker_pool.label", + "description": "i18n:ENGINE.features.worker_pool.description", + "enginePlugin": true, + "category": "worker", + "dependencies": ["worker"] + }, "terrain": { "default": true, "label": "i18n:ENGINE.features.terrain.label", @@ -498,6 +513,11 @@ "checkable": true, "required": true }, + "worker": { + "label": "i18n:ENGINE.features.categories.worker.label", + "description": "i18n:ENGINE.features.categories.worker.description", + "checkable": true + }, "2d": { "label": "i18n:ENGINE.features.categories.2d.label", "description": "i18n:ENGINE.features.categories.2d.description", diff --git a/editor/i18n/en/localization.js b/editor/i18n/en/localization.js index 49dd048c2c..4f4f7353f6 100755 --- a/editor/i18n/en/localization.js +++ b/editor/i18n/en/localization.js @@ -896,6 +896,10 @@ module.exports = link(mixin({ }, features: { categories: { + worker: { + label: 'Worker', + description: 'Worker features. The group checkbox selects or clears all items; Worker Pool depends on Basic Worker.', + }, '2d': { label: '2D', description: '2D', @@ -1133,6 +1137,14 @@ module.exports = link(mixin({ label: "WebSocket Server", description: "Enable WebSocket Server for native. Note: WebSocket must also be enabled.", }, + worker: { + label: "Basic Worker", + description: "Enable cross-platform Worker creation, messaging and capability queries. Manage workers yourself; enable Worker Pool separately for task scheduling and synchronous fallback.", + }, + worker_pool: { + label: "Worker Pool", + description: "Enable WorkerPool task scheduling, queuing, timeouts and safe synchronous fallback. Depends on Worker.", + }, flags: { spine: { loadManual: { diff --git a/editor/i18n/zh/localization.js b/editor/i18n/zh/localization.js index ba99d58986..35a310498d 100755 --- a/editor/i18n/zh/localization.js +++ b/editor/i18n/zh/localization.js @@ -874,6 +874,10 @@ module.exports = link(mixin({ }, features: { categories: { + worker: { + label: 'Worker', + description: 'Worker 功能分组。分组勾选框用于全选或清空;Worker Pool 依赖基础 Worker 功能。', + }, '2d': { label: '2D', description: '2D', @@ -1111,6 +1115,14 @@ module.exports = link(mixin({ label: "WebSocket Server", description: "对原生启用 WebSocket Server。注意: 必须同时启用 WebSocket。", }, + worker: { + label: "基础 Worker 功能", + description: "启用跨平台 Worker 创建、消息通信和能力查询,由开发者自行管理 Worker。需要任务调度与同步降级时,额外启用 Worker Pool。", + }, + worker_pool: { + label: "Worker Pool", + description: "启用 WorkerPool 任务调度、队列、超时和安全同步降级。依赖 Worker 功能。", + }, flags: { spine: { loadManual: { diff --git a/exports/worker-pool.ts b/exports/worker-pool.ts new file mode 100644 index 0000000000..5ef84ae031 --- /dev/null +++ b/exports/worker-pool.ts @@ -0,0 +1,28 @@ +/* + Copyright (c) 2026 Xiamen Yaji Software Co., Ltd. + + https://www.cocos.com/ + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated engine source code (the "Software"), a limited, + worldwide, royalty-free, non-assignable, revocable and non-exclusive license + to use Cocos Creator solely to develop games on your target platforms. You shall + not use Cocos Creator software for developing other software or tools that's + used for developing games. You are not granted to publish, distribute, + sublicense, and/or sell copies of Cocos Creator. + + The software or tools in this License Agreement are licensed, not sold. + Xiamen Yaji Software Co., Ltd. reserves all rights not expressly granted to you. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + */ + +/** Entry of the optional `worker-pool` feature, which depends on `worker`. */ +export { WorkerPool } from '../cocos/misc/worker-pool'; +export type { WorkerPoolOptions, WorkerExecutionMode } from '../cocos/misc/worker-pool'; diff --git a/exports/worker.ts b/exports/worker.ts new file mode 100644 index 0000000000..079b55bdb9 --- /dev/null +++ b/exports/worker.ts @@ -0,0 +1,55 @@ +/* + Copyright (c) 2020 Xiamen Yaji Software Co., Ltd. + + https://www.cocos.com/ + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated engine source code (the "Software"), a limited, + worldwide, royalty-free, non-assignable, revocable and non-exclusive license + to use Cocos Creator solely to develop games on your target platforms. You shall + not use Cocos Creator software for developing other software or tools that's + used for developing games. You are not granted to publish, distribute, + sublicense, and/or sell copies of Cocos Creator. + + The software or tools in this License Agreement are licensed, not sold. + Xiamen Yaji Software Co., Ltd. reserves all rights not expressly granted to you. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + */ + +/** + * Entry of the optional `worker` feature. + * + * The worker API lives in `cocos/misc/worker.ts` but is intentionally NOT re-exported from + * `cocos/misc/index.ts`: that file belongs to the always-on `base` feature, so anything exported + * there ships in every build's main bundle. Routing the subsystem through this dedicated entry lets + * builds omit the Worker API and its PAL dependencies when the feature is disabled. + * Pool scheduling is separately enabled by the `worker-pool` feature. + * + * Only the public surface is re-exported here. Platform implementations live in `pal/worker`. + * Internal backend selection and cache management stay off the `cc` namespace. + */ + +export { + createWorker, + isWorkerSupported, + isSupportStandardWorker, + checkWorkerScript, + getWorkerConcurrencyLimit, + getOptimalWorkerCount, + getWorkerCapabilities, +} from '../cocos/misc/worker'; +export type { WorkerTask, IWorkerScriptStatus } from '../cocos/misc/worker'; + +export type { + IWorker, + IWorkerBackend, + IWorkerDiagnosis, + IWorkerCapabilities, +} from 'pal/worker'; diff --git a/jest.config.js b/jest.config.js index 1eb9d79417..233d9abac8 100644 --- a/jest.config.js +++ b/jest.config.js @@ -12,6 +12,7 @@ module.exports = { moduleNameMapper: { ...pathsToModuleNameMapper(compilerOptions.paths, { prefix: `${__dirname}/` }), 'external:(.*)': '/native/external/$1', + '^pal/worker$': '/tests/mocks/pal-worker.js', }, transformIgnorePatterns: [ // ignore everything in the node_modules EXCEPT for: diff --git a/package.json b/package.json index 9f5230dc50..a4650a3080 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,8 @@ "build:cli-min": "npm run build:debug-infos && node ./scripts/build-cli-minified", "clear": "node ./scripts/clear-cache.js", "clear:platform": "node ./native/utils/clear-platform.js && node ./scripts/clear-file.js", - "test": "tsc --noEmit && jest", + "test": "npm run test:pal && tsc --noEmit && jest", + "test:pal": "node --test tests/scripts/spread-pal.test.cjs tests/scripts/pal-worker-types.test.cjs", "test:dts": "npx tsc ./scripts/test-declarations/test.d.ts", "update:engine-version": "node ./scripts/checkout-engine-version.js", "update:native-external": "node ./native/utils/update-external.js", diff --git a/scripts/build-cli-minified.js b/scripts/build-cli-minified.js index a15dd2dd0a..0192f1ec4b 100644 --- a/scripts/build-cli-minified.js +++ b/scripts/build-cli-minified.js @@ -1,3 +1,4 @@ +require('./ensure-pal.cjs')(); const { join } = require('path'); const { ensureDir, emptyDir } = require('fs-extra'); const { magenta } = require('chalk'); diff --git a/scripts/build-const.js b/scripts/build-const.js index 22f1f821de..45e5a4dca8 100644 --- a/scripts/build-const.js +++ b/scripts/build-const.js @@ -1,3 +1,4 @@ +require('./ensure-pal.cjs')(); const { StatsQuery } = require('@cocos/ccbuild'); const { join } = require('path'); const { outputFileSync } = require('fs-extra'); diff --git a/scripts/build-declarations.js b/scripts/build-declarations.js index bc6f0b6f07..69ca7acbe7 100644 --- a/scripts/build-declarations.js +++ b/scripts/build-declarations.js @@ -1,3 +1,4 @@ +require('./ensure-pal.cjs')(); const { join } = require('path'); const { emptyDir } = require('fs-extra'); const { dtsBundler } = require('@cocos/ccbuild'); diff --git a/scripts/build-h5-minified.js b/scripts/build-h5-minified.js index 36ec89145e..dcdfd4b7a7 100644 --- a/scripts/build-h5-minified.js +++ b/scripts/build-h5-minified.js @@ -1,3 +1,4 @@ +require('./ensure-pal.cjs')(); const { join } = require('path'); const { ensureDir, emptyDir } = require('fs-extra'); const { magenta } = require('chalk'); diff --git a/scripts/build-h5-source.js b/scripts/build-h5-source.js index 08cf0ac8d6..63cdf31a3e 100644 --- a/scripts/build-h5-source.js +++ b/scripts/build-h5-source.js @@ -1,3 +1,4 @@ +require('./ensure-pal.cjs')(); const { join } = require('path'); const { ensureDir, emptyDir } = require('fs-extra'); const { magenta } = require('chalk'); diff --git a/scripts/compile-native-ts.js b/scripts/compile-native-ts.js index cfda5ec444..9cdc92156c 100644 --- a/scripts/compile-native-ts.js +++ b/scripts/compile-native-ts.js @@ -1,3 +1,4 @@ +require('./ensure-pal.cjs')(); const ccbuild = require('@cocos/ccbuild'); const ps = require('path'); const fs = require('fs-extra'); diff --git a/scripts/ensure-pal.cjs b/scripts/ensure-pal.cjs new file mode 100644 index 0000000000..41e5d42ebc --- /dev/null +++ b/scripts/ensure-pal.cjs @@ -0,0 +1,192 @@ +const fs = require('fs'); +const path = require('path'); + +// `pal/` is a generated copy of a PAL dist directory (see spread-pal.cjs). Every build entry calls +// this module first so a checkout keeps building even when dependencies changed without a fresh +// `npm install` (or postinstall was skipped). Checks run in order; each receives palRoot, returns +// true if it changed files, and throws when the build cannot continue. Checks must be safe to repeat. +const checks = [ + syncInstalledPackage, + ensureWorker, +]; + +// Written by spread-pal.cjs: where pal/ was copied from, and the package version at that time. +const STAMP = '.pal-source.json'; +const FALLBACK_MARKER = '// Compatibility only: real platform implementations remain in cocos-pal.'; +const FALLBACK_TEMPLATE = path.join(__dirname, 'pal-worker-fallback'); +const PLATFORMS = ['web', 'minigame', 'native', 'nodejs']; +// The shared compatibility implementation is deliberately NOT named `index.js`: a file at +// pal/worker/index.js lets resolvers (the editor/preview quick compiler, tsconfig baseUrl) turn the +// bare `pal/worker` import into that directory file instead of the per-platform override from +// cc.config.json, and a cached resolution then keeps pointing at the fallback even after the real +// PAL worker is installed. Real PAL packages have no root index either. +const FALLBACK_FILE = 'compat.js'; +const FORWARDER = `export { createWorkerBackend } from '../${FALLBACK_FILE}';\n`; +// Layout generated by earlier engine versions (root index.js); recognised so it can be migrated. +const LEGACY_FALLBACK_FILE = 'index.js'; +const LEGACY_FORWARDER = "export { createWorkerBackend } from '../index.js';\n"; + +// Shared entry for installation and every engine build path. +function ensurePal(palRoot = path.join(__dirname, '..', 'pal')) { + if (!fs.existsSync(palRoot) || !fs.statSync(palRoot).isDirectory()) { + throw new Error(`PAL directory is missing: ${palRoot}. Install engine dependencies first.`); + } + let changed = false; + for (const check of checks) { + // Always execute every check, even if an earlier one changed files. + if (check(palRoot)) changed = true; + } + return changed; +} + +// ---------------------------------------------------------------- PAL copy helpers (spread-pal) + +function packageDist(palRoot) { + return path.join(path.dirname(palRoot), 'node_modules', '@cocos', 'engine-pal', 'dist'); +} + +function readJson(file) { + try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { return null; } +} + +function packageVersion(dist) { + const pkg = readJson(path.join(dist, '..', 'package.json')); + return pkg && typeof pkg.version === 'string' ? pkg.version : null; +} + +function readStamp(palRoot) { + return readJson(path.join(palRoot, STAMP)); +} + +// Remove a path; a symlink is unlinked without touching its target (historical pal symlinks). +function removeExisting(p) { + let st; + try { st = fs.lstatSync(p); } catch (e) { return; } + if (st.isSymbolicLink()) fs.unlinkSync(p); + else fs.rmSync(p, { recursive: true, force: true }); +} + +function copyDir(src, dst) { + let count = 0; + fs.mkdirSync(dst, { recursive: true }); + for (const name of fs.readdirSync(src)) { + const sp = path.join(src, name); + const dp = path.join(dst, name); + if (fs.statSync(sp).isDirectory()) count += copyDir(sp, dp); + else { fs.copyFileSync(sp, dp); count++; } + } + return count; +} + +// Replace palRoot with a fresh copy of src and record where it came from. `fromPackage` marks the +// installed npm package (the postinstall default), which later builds keep in sync automatically; +// an explicit local source (PAL development) is never replaced behind the developer's back. +function spread(src, palRoot, fromPackage) { + removeExisting(palRoot); + const count = copyDir(src, palRoot); + const stamp = fromPackage + ? { package: '@cocos/engine-pal', version: packageVersion(src) } + // Relative to the engine root so the record stays valid if the checkout is moved or mounted elsewhere. + : { source: path.relative(path.dirname(palRoot), path.resolve(src)).split(path.sep).join('/') }; + fs.writeFileSync(path.join(palRoot, STAMP), `${JSON.stringify(stamp, null, 4)}\n`); + return count; +} + +// ---------------------------------------------------------------- checks + +// pal/ was copied from the npm package, but a different version is installed now (dependencies +// were updated with --ignore-scripts, or postinstall failed after npm replaced the package). +// Re-copy the whole directory so no module is left from the old version. +function syncInstalledPackage(palRoot) { + const stamp = readStamp(palRoot); + if (!stamp || !stamp.package) return false; + const dist = packageDist(palRoot); + const installed = packageVersion(dist); + if (!installed || !fs.existsSync(dist) || installed === stamp.version) return false; + spread(dist, palRoot, true); + console.log(`[spread-pal] pal/ was copied from @cocos/engine-pal ${stamp.version}, ` + + `installed is ${installed}; re-synchronized.`); + return true; +} + +// 'real' : a PAL worker implementation (never modified, even if only partially present). +// 'fallback' : the engine-generated single-thread compatibility module. +// 'missing' : no worker directory. +function workerState(workerRoot) { + if (!fs.existsSync(workerRoot)) return 'missing'; + const generated = (file, forwarder) => { + const shared = path.join(workerRoot, file); + return fs.existsSync(shared) + && fs.readFileSync(shared, 'utf8').startsWith(FALLBACK_MARKER) + && PLATFORMS.every((platform) => { + const entry = path.join(workerRoot, platform, 'index.js'); + return fs.existsSync(entry) && fs.readFileSync(entry, 'utf8') === forwarder; + }); + }; + return generated(FALLBACK_FILE, FORWARDER) || generated(LEGACY_FALLBACK_FILE, LEGACY_FORWARDER) + ? 'fallback' : 'real'; +} + +// Where a real worker module can be taken from: the recorded spread source, or the installed +// package for pal/ copies predating the stamp. Never mixes an explicit local source with npm. +function workerSource(palRoot) { + const stamp = readStamp(palRoot); + const dist = stamp && stamp.source ? path.resolve(path.dirname(palRoot), stamp.source) : packageDist(palRoot); + const worker = path.join(dist, 'worker'); + return fs.existsSync(worker) && workerState(worker) === 'real' ? worker : null; +} + +function listFiles(dir, base = dir, out = {}) { + for (const name of fs.readdirSync(dir)) { + const p = path.join(dir, name); + if (fs.statSync(p).isDirectory()) listFiles(p, base, out); + else out[path.relative(base, p).split(path.sep).join('/')] = fs.readFileSync(p, 'utf8'); + } + return out; +} + +function fallbackFiles() { + const files = { [FALLBACK_FILE]: fs.readFileSync(path.join(FALLBACK_TEMPLATE, FALLBACK_FILE), 'utf8') }; + for (const platform of PLATFORMS) files[`${platform}/index.js`] = FORWARDER; + return files; +} + +// PAL packages before 1.0.5 have no worker module. Keep `pal/worker` resolvable for builds that +// enable the optional `worker` feature: prefer a real implementation whenever one is available, +// otherwise supply a platform-independent unavailable backend (WorkerPool then runs inline). +// Nothing here includes Worker in builds without either optional Worker feature. +// Types come from @types/pal/worker.d.ts, so the compatibility module is JS only. +function ensureWorker(palRoot) { + const workerRoot = path.join(palRoot, 'worker'); + const state = workerState(workerRoot); + if (state === 'real') return false; + + const source = workerSource(palRoot); + if (source) { + removeExisting(workerRoot); + copyDir(source, workerRoot); + console.log(`[pal-worker] Restored the platform worker module from ${source}.`); + return true; + } + + const expected = fallbackFiles(); + if (state === 'fallback') { + const actual = listFiles(workerRoot); + const same = Object.keys(actual).length === Object.keys(expected).length + && Object.keys(expected).every((file) => actual[file] === expected[file]); + if (same) return false; + } + removeExisting(workerRoot); + for (const [file, content] of Object.entries(expected)) { + const target = path.join(workerRoot, file); + fs.mkdirSync(path.dirname(target), { recursive: true }); + fs.writeFileSync(target, content); + } + console.log('[pal-worker] PAL has no worker module; installed single-thread compatibility backend. ' + + 'Run `npm install` to pick up @cocos/engine-pal with platform workers.'); + return true; +} + +module.exports = ensurePal; +module.exports.spread = spread; +module.exports.packageDist = packageDist; diff --git a/scripts/pal-worker-fallback/compat.js b/scripts/pal-worker-fallback/compat.js new file mode 100644 index 0000000000..8d8e8c7cd1 --- /dev/null +++ b/scripts/pal-worker-fallback/compat.js @@ -0,0 +1,25 @@ +// Compatibility only: real platform implementations remain in cocos-pal. +const reason = 'Installed PAL package has no worker module; using single-thread execution. ' + + 'Upgrade @cocos/engine-pal to enable platform workers.'; + +export function createWorkerBackend() { + return { + supportsStandardWorker: false, + scriptFailureHint: '', + resolveScriptWorker() { + return { backend: null, diagnosis: { ready: false, version: 0, reason }, warnOnFailure: false }; + }, + concurrencyLimit: 0, + hardwareConcurrency: 1, + supportsTransfer: false, + supportsSharedArrayBuffer: false, + supportsFunctionWorker: false, + capabilityReason: reason, + scriptFallback: null, + createFunctionWorker() { return null; }, + createScriptWorker(path) { + throw new Error(`Cannot create worker "${path}": ${reason}`); + }, + diagnose() { return { ready: false, version: 0, reason }; }, + }; +} diff --git a/scripts/spread-pal.cjs b/scripts/spread-pal.cjs index f6a8ba3563..7e9248434e 100644 --- a/scripts/spread-pal.cjs +++ b/scripts/spread-pal.cjs @@ -14,35 +14,31 @@ // 物理位于 engineRoot/pal,paths 别名才生效。 const fs = require('fs'); const path = require('path'); +const ensurePal = require('./ensure-pal.cjs'); const engineRoot = path.join(__dirname, '..'); -const src = path.join(engineRoot, 'node_modules', '@cocos', 'engine-pal', 'dist'); const dst = path.join(engineRoot, 'pal'); +// Local PAL development: node scripts/spread-pal.cjs --source ../cocos-pal/dist +const sourceIndex = process.argv.indexOf('--source'); +if (sourceIndex >= 0 && !process.argv[sourceIndex + 1]) { + throw new Error('--source requires a PAL dist directory'); +} +const fromPackage = sourceIndex < 0; +const src = fromPackage + ? ensurePal.packageDist(dst) + : path.resolve(process.argv[sourceIndex + 1]); + +if (src === dst || src.startsWith(dst + path.sep)) { + throw new Error('PAL source must be outside the destination directory'); +} if (!fs.existsSync(src)) { console.error(`[spread-pal] 找不到 pal 产物: ${src}\n请先安装 @cocos/engine-pal。`); process.exit(1); } -// 安全清除已有 pal:软链只删链接本身(不碰目标),真实目录才递归删。 -function removeExisting(p) { - let st; - try { st = fs.lstatSync(p); } catch (e) { return; } // 不存在 - if (st.isSymbolicLink()) fs.unlinkSync(p); // 兼容历史软链 - else fs.rmSync(p, { recursive: true, force: true }); -} - -let count = 0; -function copyDir(s, d) { - fs.mkdirSync(d, { recursive: true }); - for (const name of fs.readdirSync(s)) { - const sp = path.join(s, name); - const dp = path.join(d, name); - if (fs.statSync(sp).isDirectory()) copyDir(sp, dp); - else { fs.copyFileSync(sp, dp); count++; } - } -} - -removeExisting(dst); -copyDir(src, dst); +// 复制并记录来源(pal/.pal-source.json)。之后各构建入口的 ensure-pal 据此判断 pal/ 是否落后于 +// 已安装的 npm 包(例如 npm install --ignore-scripts 后未重新 spread),落后则自动重新同步。 +const count = ensurePal.spread(src, dst, fromPackage); +ensurePal(dst); console.log(`[spread-pal] 已复制 ${count} 个文件: ${src} -> ${dst}`); diff --git a/scripts/test-worker-release.cjs b/scripts/test-worker-release.cjs new file mode 100644 index 0000000000..72a0fe8400 --- /dev/null +++ b/scripts/test-worker-release.cjs @@ -0,0 +1,55 @@ +// Build and exercise the optimized public Worker API with a Worker-capable PAL. +// Optional first argument: an isolated engine checkout used for validation. +const fs = require('fs'); +const path = require('path'); +const { execFileSync } = require('child_process'); +const assert = require('node:assert/strict'); +const { buildEngine } = require('@cocos/ccbuild'); + +async function main() { + const engine = fs.realpathSync(process.argv[2] || path.join(__dirname, '..')); + const out = path.join(engine, 'bin', 'worker-release-check'); + const options = { + engine, + platform: 'HTML5', + moduleFormat: 'cjs', + mode: 'BUILD', + compress: true, + split: false, + sourceMap: false, + loose: true, + inlineEnum: true, + mangleProperties: true, + flags: { DEBUG: false }, + }; + // Pool-only selection must also expose the basic API when calling ccbuild directly. + await buildEngine({ ...options, out, features: ['worker-pool'] }); + const basicOut = path.join(out, 'basic'); + const disabledOut = path.join(out, 'disabled'); + for (const [target, features] of [[basicOut, ['worker']], [disabledOut, ['affine-transform']]]) { + await buildEngine({ ...options, out: target, features, sourceMap: true }); + const map = JSON.parse(fs.readFileSync(path.join(target, 'cc.js.map'), 'utf8')); + assert.ok(!map.sources.some(file => /worker-pool\.ts$/.test(file)), 'pool implementation must be omitted'); + if (target === disabledOut) { + assert.ok(!map.sources.some(file => /(?:pal\/worker\/|misc\/worker\.ts$)/.test(file)), + 'disabled Worker features must omit the basic API and PAL Worker'); + } + } + console.log('[worker features] minified bytes:', { + worker: fs.statSync(path.join(basicOut, 'cc.js')).size, + workerPool: fs.statSync(path.join(out, 'cc.js')).size, + }); + execFileSync(process.execPath, [ + path.join(__dirname, '../tests/scripts/worker-release.test.cjs'), + path.join(out, 'cc.js'), + path.join(basicOut, 'cc.js'), + path.join(disabledOut, 'cc.js'), + ], { stdio: 'inherit' }); +} + +// ccbuild can retain minifier worker threads after returning. This standalone CLI owns that work; +// exit only after all builds and the synchronous child test process have finished. +main().then(() => process.exit(0), (error) => { + console.error(error); + process.exit(1); +}); diff --git a/tests/misc/worker-bootstrap-source.test.ts b/tests/misc/worker-bootstrap-source.test.ts new file mode 100644 index 0000000000..358c98812e --- /dev/null +++ b/tests/misc/worker-bootstrap-source.test.ts @@ -0,0 +1,193 @@ +/** + * Regression tests for the serialized function-worker bootstrap source (`createWorkerFromFunction`). + * + * These tests capture the generated blob source and execute it in a Node `vm` sandbox, so they assert + * on what the WORKER ACTUALLY DOES rather than on the string's shape. That matters: the defects fixed + * here only manifested at worker runtime, and the previous suite never executed the generated code. + * + * Fixed defects (all previously reproducible): + * P0-2a Cyclic result object -> RangeError (stack overflow). Structured clone handles cycles + * natively, so the collector turned a working case into a crash. + * P0-2b Deeply nested result -> RangeError. The overflow was then caught and reported as + * "Worker result is not serializable", pointing diagnosis at the wrong cause. + * P0-2c `for...in` walked the prototype chain, so a buffer inherited from a prototype was + * transferred. Structured clone only copies own enumerable properties, so that buffer never + * appeared in the reply — the main thread's copy got silently detached. No throw, no log. + * P0-2d A hostile getter threw inside the collector and failed the whole task. Collecting the + * transfer list is an optimisation; it must never be able to fail the task. + */ +import * as vm from 'vm'; +import { createWorker } from '../../cocos/misc/worker'; + +let capturedSource = ''; + +class FakeBlob { + constructor (parts: string[]) { + capturedSource = parts.join(''); + } +} +class FakeURL { + public static createObjectURL = (): string => 'blob:fake'; + public static revokeObjectURL = (): void => {}; +} +class FakeWorker { + public onmessage: ((e: any) => void) | null = null; + public onerror: ((e: any) => void) | null = null; + public postMessage (_msg: any, _transfer?: any): void {} + public terminate (): void {} +} + +beforeAll(() => { + (globalThis as any).Blob = FakeBlob; + (globalThis as any).URL = FakeURL; + (globalThis as any).Worker = FakeWorker; +}); + +afterAll(() => { + delete (globalThis as any).Blob; + delete (globalThis as any).URL; + delete (globalThis as any).Worker; +}); + +/** Generate the worker source from `fn`. */ +function compile (fn: unknown): void { + createWorker(fn as any); + expect(capturedSource.length).toBeGreaterThan(0); +} + +/** + * Run the generated worker source in a sandbox and deliver one task. + * Returns every postMessage attempt plus the transfer list used for each. + */ +function runTask (args: unknown[]): { attempts: Array<{ reply: any; transfer: any }> } { + const attempts: Array<{ reply: any; transfer: any }> = []; + const sandbox: any = { + self: { + onmessage: null as any, + postMessage: (reply: any, transfer?: any): void => { attempts.push({ reply, transfer }); }, + }, + Set, + Array, + Object, + ArrayBuffer, + Uint8Array, + Float32Array, + Error, + String, + Number, + }; + vm.createContext(sandbox); + vm.runInContext(capturedSource, sandbox); + sandbox.self.onmessage({ data: { id: 1, args } }); + return { attempts }; +} + +const transferCount = (t: any): number => (Array.isArray(t) ? t.length : -1); + +describe('Generated worker source: runtime behaviour', () => { + beforeEach(() => { capturedSource = ''; }); + + test('P0-2a cyclic result object does not overflow the stack', () => { + compile(() => { + const cyc: any = { buf: new ArrayBuffer(8) }; + cyc.self = cyc; + return cyc; + }); + const { attempts } = runTask([]); + expect(attempts[0].reply.ok).toBe(true); + expect(transferCount(attempts[0].transfer)).toBe(1); + }); + + test('P0-2b deeply nested result (50k levels) does not overflow the stack', () => { + compile(() => { + const root: any = { buf: new ArrayBuffer(8) }; + let cur = root; + for (let i = 0; i < 50000; i++) { cur.n = {}; cur = cur.n; } + cur.buf = new ArrayBuffer(8); + return root; + }); + const { attempts } = runTask([]); + // Past the depth cap the collector stops looking, so only the shallow buffer is found. + // The task still succeeds — losing the optimisation is fine, losing the result is not. + expect(attempts[0].reply.ok).toBe(true); + expect(transferCount(attempts[0].transfer)).toBe(1); + }); + + test('P0-2c a buffer on the prototype chain is NOT transferred (silent main-thread detach)', () => { + compile(() => { + function Base (this: any) { this.inheritedBuf = new ArrayBuffer(8); } + const obj: any = Object.create(new (Base as any)()); + obj.ownBuf = new ArrayBuffer(8); + return obj; + }); + const { attempts } = runTask([]); + expect(attempts[0].reply.ok).toBe(true); + // Exactly one buffer: ownBuf. If inheritedBuf were collected it would be detached on the main + // thread while never appearing in the cloned reply. + expect(transferCount(attempts[0].transfer)).toBe(1); + }); + + test('P0-2d a hostile getter downgrades to plain clone instead of failing the task', () => { + compile(() => { + const obj: any = { buf: new ArrayBuffer(8) }; + Object.defineProperty(obj, 'evil', { + enumerable: true, + get (): never { throw new Error('hostile getter'); }, + }); + return obj; + }); + const { attempts } = runTask([]); + expect(attempts[0].reply.ok).toBe(true); + // Collection failed, so transfer is undefined -> structured clone path. + expect(attempts[0].transfer).toBeUndefined(); + }); + + test('one buffer behind several views is transferred exactly once', () => { + compile(() => { + const buf = new ArrayBuffer(16); + return { a: new Uint8Array(buf), b: new Float32Array(buf), c: buf }; + }); + const { attempts } = runTask([]); + expect(attempts[0].reply.ok).toBe(true); + // Transferring the same buffer twice throws in a real Worker. + expect(transferCount(attempts[0].transfer)).toBe(1); + }); + + test('a null result is handled and produces no transfers', () => { + compile(() => null); + const { attempts } = runTask([]); + expect(attempts[0].reply.ok).toBe(true); + expect(attempts[0].reply.value).toBeNull(); + expect(transferCount(attempts[0].transfer)).toBe(0); + }); + + test('a primitive result is handled and produces no transfers', () => { + compile((a: number, b: number) => a + b); + const { attempts } = runTask([2, 3]); + expect(attempts[0].reply).toMatchObject({ id: 1, ok: true, value: 5 }); + expect(transferCount(attempts[0].transfer)).toBe(0); + }); + + test('a throwing task function is reported as an error envelope, not a crash', () => { + compile(() => { throw new Error('task boom'); }); + const { attempts } = runTask([]); + expect(attempts[0].reply.ok).toBe(false); + expect(attempts[0].reply.error).toContain('task boom'); + }); + + test('missing args array does not throw', () => { + compile(() => 7); + const { attempts } = runTask([]); + expect(attempts[0].reply.ok).toBe(true); + }); +}); + +// SAB-backed views are shared, never transferable; ordinary buffers must still be moved. +test('SAB-backed views do not pollute the transfer list', () => { + compile((shared: Uint8Array, ordinary: Uint8Array) => ({ shared, ordinary })); + const shared = new Uint8Array(new SharedArrayBuffer(8)); + const ordinary = new Uint8Array(8); + const { attempts } = runTask([shared, ordinary]); + expect(attempts[0].reply.ok).toBe(true); + expect(attempts[0].transfer).toEqual([ordinary.buffer]); +}); diff --git a/tests/misc/worker-degradation.test.ts b/tests/misc/worker-degradation.test.ts new file mode 100644 index 0000000000..8e639fb357 --- /dev/null +++ b/tests/misc/worker-degradation.test.ts @@ -0,0 +1,145 @@ +jest.mock('pal/worker', () => ({ createWorkerBackend: jest.fn() })); + +import { createWorkerBackend } from 'pal/worker'; +import { WorkerPool } from '../../cocos/misc/worker-pool'; +import { resetWorkerBackendCache } from '../../cocos/misc/worker'; + +function controlledBackend(limit = 3) { + const handles: any[] = []; + const backend = { + hardwareConcurrency: 4, concurrencyLimit: limit, supportsTransfer: true, + supportsFunctionWorker: false, scriptFailureHint: '', + resolveScriptWorker: () => ({ backend, diagnosis: { ready: true, version: 1, reason: '' }, warnOnFailure: false }), + createScriptWorker: jest.fn(() => { + const handle: any = { + postMessage: jest.fn(), terminate: jest.fn(), + onMessage: (fn: any) => { handle.reply = fn; }, + onError: (fn: any) => { handle.fail = fn; }, + }; + handles.push(handle); + return handle; + }), + }; + (createWorkerBackend as jest.Mock).mockReturnValue(backend); + return { backend, handles }; +} + +const pools: WorkerPool[] = []; +function pool(options: ConstructorParameters[1] = {}) { + const value = new WorkerPool('workers/task.js', { maxWorkers: 3, idleReleaseAfter: 0, ...options }); + pools.push(value); + return value; +} +function reply(handle: any, value: number) { + handle.reply({ id: handle.postMessage.mock.calls[0][0].id, ok: true, value }); +} +beforeEach(() => resetWorkerBackendCache()); +afterEach(() => { + for (const value of pools.splice(0)) value.terminate(); + jest.useRealTimers(); + resetWorkerBackendCache(); +}); + +test.each([[0, 1], [1, 0], [2, 0, 1]])('consecutive worker failures recover every task (order %j)', async (...order) => { + const { handles } = controlledBackend(); + const fallback = jest.fn((n: number) => n * 2); + const value = pool({ fallback, maxWorkers: order.length }); + const fulfilled = order.map(() => jest.fn()); + const rejected = order.map(() => jest.fn()); + const results = order.map((_, i) => value.run([i + 3]).then(fulfilled[i], rejected[i])); + const queued = value.run([9]); + for (const i of order) handles[i].fail(new Error('backend failed')); + await Promise.all(results); + await expect(queued).resolves.toBe(18); + expect(value.backend).toBe('sync'); + for (let i = 0; i < order.length; ++i) { + expect(fulfilled[i]).toHaveBeenCalledTimes(1); + expect(fulfilled[i]).toHaveBeenCalledWith((i + 3) * 2); + expect(rejected[i]).not.toHaveBeenCalled(); + expect(fallback.mock.calls.filter(([n]) => n === i + 3)).toHaveLength(1); + expect(handles[i].terminate).toHaveBeenCalledTimes(1); + // Late duplicate events must not replay an already recovered task. + handles[i].fail(new Error('duplicate error')); + reply(handles[i], -1); + } + await expect(value.run([10])).resolves.toBe(20); + expect(fallback).toHaveBeenCalledTimes(order.length + 2); +}); + +test.each([true, false])('one successful task and one failed task (failure first=%s)', async (failureFirst) => { + const { handles } = controlledBackend(); + const fallback = jest.fn((n: number) => n * 2); + const value = pool({ fallback }); + const results = Promise.all([value.run([3]), value.run([4])]); + if (failureFirst) { + handles[0].fail(new Error('backend failed')); + reply(handles[1], 104); + } else { + reply(handles[1], 104); + handles[0].fail(new Error('backend failed')); + } + await expect(results).resolves.toEqual([6, 104]); + expect(fallback).toHaveBeenCalledTimes(1); + expect(fallback).toHaveBeenCalledWith(3); +}); + +test.each([1, 3])('%i silent workers recover through fallback after timeout', async (count) => { + jest.useFakeTimers(); + controlledBackend(); + const fallback = jest.fn((n: number) => n * 2); + const value = pool({ fallback, timeout: 20 }); + const results = Promise.all(Array.from({ length: count }, (_, i) => value.run([i + 3]))); + jest.advanceTimersByTime(20); + await expect(results).resolves.toEqual(Array.from({ length: count }, (_, i) => (i + 3) * 2)); + expect(fallback).toHaveBeenCalledTimes(count); + jest.advanceTimersByTime(100); + expect(fallback).toHaveBeenCalledTimes(count); +}); + +test('a transferred task still rejects when another worker already caused degradation', async () => { + const { handles } = controlledBackend(); + const fallback = jest.fn((n: number) => n * 2); + const value = pool({ fallback }); + const first = value.run([3]); + const bytes = new Uint8Array([4]); + const second = expect(value.run([bytes], [bytes.buffer])).rejects.toThrow('transferred worker failed'); + const { port1, port2 } = new (require('worker_threads').MessageChannel)(); + try { + port1.postMessage(bytes, [bytes.buffer]); + expect(bytes.byteLength).toBe(0); + } finally { + port1.close(); port2.close(); + } + handles[0].fail(new Error('backend failed')); + handles[1].fail(new Error('transferred worker failed')); + await expect(first).resolves.toBe(6); + await second; + expect(fallback).toHaveBeenCalledTimes(1); + await expect(value.run([5])).resolves.toBe(10); +}); + +test.each([false, true])('pre-recheck faults cannot degrade a new backend (already degraded=%s)', async (degraded) => { + const old = controlledBackend(); + const fallback = jest.fn((n: number) => n * 2); + const value = pool({ fallback }); + const first = degraded ? value.run([3]) : null; + const stale = expect(value.run([4])).rejects.toThrow('old backend failed'); + if (degraded) old.handles[0].fail(new Error('initial failure')); + const fresh = controlledBackend(); + expect(value.recheck()).toBe('worker'); + old.handles[degraded ? 1 : 0].fail(new Error('old backend failed')); + await stale; + expect(value.backend).toBe('worker'); + expect(fallback).not.toHaveBeenCalled(); + if (first) { + reply(fresh.handles[0], 6); + await expect(first).resolves.toBe(6); + } + const next = value.run([5]); + const handle = fresh.handles.find((worker) => worker.postMessage.mock.calls.some(([message]: any[]) => message.args[0] === 5)); + const message = handle.postMessage.mock.calls.find(([m]: any[]) => m.args[0] === 5)[0]; + handle.reply({ id: message.id, ok: true, value: 10 }); + await expect(next).resolves.toBe(10); + expect(value.backend).toBe('worker'); + expect(fallback).not.toHaveBeenCalled(); +}); diff --git a/tests/misc/worker-legacy-pal.test.ts b/tests/misc/worker-legacy-pal.test.ts new file mode 100644 index 0000000000..74bcd6876f --- /dev/null +++ b/tests/misc/worker-legacy-pal.test.ts @@ -0,0 +1,67 @@ +// Exercise WorkerPool with the same backend installed for pre-worker PAL packages. +jest.mock('pal/worker', () => require('../../scripts/pal-worker-fallback/compat.js')); + +import { WorkerPool } from '../../cocos/misc/worker-pool'; +import { getWorkerCapabilities } from '../../cocos/misc/worker'; +import { checkWorkerScript, createWorker } from '../../cocos/misc/worker'; + +describe('PAL package without a worker module', () => { + let savedWorker: PropertyDescriptor | undefined; + const constructor = jest.fn(() => { throw new Error('must not start a Worker'); }); + + beforeEach(() => { + savedWorker = Object.getOwnPropertyDescriptor(globalThis, 'Worker'); + Object.defineProperty(globalThis, 'Worker', { configurable: true, value: constructor }); + constructor.mockClear(); + }); + + afterEach(() => { + expect(constructor).not.toHaveBeenCalled(); + if (savedWorker) Object.defineProperty(globalThis, 'Worker', savedWorker); + else delete (globalThis as any).Worker; + }); + + test('reports the missing PAL capability even when a global Worker exists', () => { + expect(getWorkerCapabilities()).toMatchObject({ + available: false, parallel: false, concurrencyLimit: 0, + supportsTransfer: false, supportsSharedArrayBuffer: false, supportsFunctionWorker: false, + }); + expect(checkWorkerScript('workers/task.js')).toMatchObject({ ready: false, version: 0 }); + expect(getWorkerCapabilities().reason).toContain('PAL package has no worker module'); + expect(getWorkerCapabilities()).not.toHaveProperty('kind'); + expect(getWorkerCapabilities().supportsStandardWorker).toBe(false); + }); + + test('function tasks run inline, including after rechecking capabilities', async () => { + const pool = new WorkerPool((n: number) => n * 2, { maxWorkers: 4 }); + try { + expect(pool.backend).toBe('sync'); + expect(pool.concurrency).toBe(1); + await expect(pool.run([21])).resolves.toBe(42); + expect(pool.recheck()).toBe('sync'); + await expect(pool.run([3])).resolves.toBe(6); + } finally { + pool.terminate(); + } + }); + + test('script tasks use their supplied fallback', async () => { + const pool = new WorkerPool('workers/task.js', { fallback: (a: number, b: number) => a + b }); + try { + expect(pool.backend).toBe('sync'); + await expect(pool.run([20, 22])).resolves.toBe(42); + } finally { + pool.terminate(); + } + }); + + test('script tasks without fallback fail explicitly, as does direct worker creation', async () => { + const pool = new WorkerPool('workers/task.js'); + try { + await expect(pool.run([])).rejects.toThrow('PAL package has no worker module'); + expect(() => createWorker('workers/task.js')).toThrow('PAL package has no worker module'); + } finally { + pool.terminate(); + } + }); +}); diff --git a/tests/misc/worker-lifecycle.test.ts b/tests/misc/worker-lifecycle.test.ts new file mode 100644 index 0000000000..27831edf16 --- /dev/null +++ b/tests/misc/worker-lifecycle.test.ts @@ -0,0 +1,216 @@ +/** + * WorkerPool lifecycle regression tests — the full {idle, busy} x {error kinds} state matrix. + * + * Why this file exists: the original suite passed 40/40 while still shipping a P0 hang. Every case in + * it used a "submit -> await -> submit again" rhythm, so a worker was ALWAYS mid-task when an error + * arrived. The idle-error path had zero coverage, and that is exactly where the dead worker leaked. + * + * The lesson: for a concurrency state machine, enumerate the state combinations rather than the + * paths the author had in mind. + * + * Real-world triggers for an error while idle: + * - an uncaught async throw inside the worker (a `setInterval` / `setTimeout` callback); + * - WeChat killing the worker process (`Worker.onProcessKilled`, routed to the error listener); + * - the OS reclaiming the worker under memory pressure. + */ +import { WorkerPool } from '../../cocos/misc/worker-pool'; + +type ReplyMode = 'ok' | 'malformed' | 'error' | 'silent'; + +class FakeWebWorker { + public static instances: FakeWebWorker[] = []; + public static replyMode: ReplyMode = 'ok'; + + public readonly url: string; + public posted: any[] = []; + public terminated = false; + public onmessage: ((e: { data: any }) => void) | null = null; + public onerror: ((e: any) => void) | null = null; + + constructor (url: string) { + this.url = url; + FakeWebWorker.instances.push(this); + } + + public postMessage (msg: any): void { + this.posted.push(msg); + const mode = FakeWebWorker.replyMode; + if (mode === 'silent') { + return; + } + const reply = mode === 'malformed' + ? 'garbage-not-an-object' + : mode === 'error' + ? { id: msg.id, ok: false, error: 'web task failed' } + : { id: msg.id, ok: true, value: msg.args[0] * 2 }; + Promise.resolve().then(() => { + if (this.onmessage) { this.onmessage({ data: reply }); } + }); + } + + public terminate (): void { + this.terminated = true; + } +} + +beforeAll(() => { + (globalThis as any).Worker = FakeWebWorker; +}); + +afterAll(() => { + delete (globalThis as any).Worker; +}); + +beforeEach(() => { + FakeWebWorker.instances.length = 0; + FakeWebWorker.replyMode = 'ok'; +}); + +/** Race a task against a wall-clock deadline so a hang surfaces as a test failure, not a timeout. */ +async function settleOrHang (p: Promise, ms = 400): Promise<{ hung: boolean; value?: T; error?: string }> { + const sentinel = Symbol('hang'); + const outcome = await Promise.race([ + p.then((value) => ({ hung: false, value })).catch((e: Error) => ({ hung: false, error: e.message })), + new Promise((r) => setTimeout(() => r(sentinel), ms)), + ]); + return outcome === sentinel ? { hung: true } : outcome as any; +} + +/** Let queued microtasks and macrotask callbacks settle. */ +function tick (ms = 10): Promise { + return new Promise((r) => setTimeout(r, ms)); +} + +describe('IDLE-state failures (the uncovered half of the state machine)', () => { + test('a worker that errors while idle is evicted, and the next task lands on a fresh worker', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, idleReleaseAfter: 0 }); + await expect(pool.run([1])).resolves.toBe(2); + expect(FakeWebWorker.instances).toHaveLength(1); + + const dead = FakeWebWorker.instances[0]; + // The worker is idle here: no in-flight task. Simulate an uncaught async error inside it. + dead.onerror!({ message: 'idle crash: setInterval callback threw' }); + await tick(); + + // Before the fix, `_settle` bailed out on `if (!task) return`, so the eviction branch never ran: + // the dead worker stayed in the pool with busy === false and swallowed the next task forever. + expect(dead.terminated).toBe(true); + + const next = await settleOrHang(pool.run([5])); + expect(next.hung).toBe(false); + expect(next.value).toBe(10); + expect(FakeWebWorker.instances).toHaveLength(2); + + pool.terminate(); + }); + + test('an idle error with no error object still evicts (defensive branch)', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, idleReleaseAfter: 0 }); + await expect(pool.run([1])).resolves.toBe(2); + const dead = FakeWebWorker.instances[0]; + + dead.onerror!(undefined); + await tick(); + expect(dead.terminated).toBe(true); + + const next = await settleOrHang(pool.run([3])); + expect(next.hung).toBe(false); + expect(next.value).toBe(6); + pool.terminate(); + }); + + test('queued tasks already waiting are re-dispatched after an eviction', async () => { + // maxWorkers 1: task A occupies the worker, B and C queue. Kill the worker while it is busy, + // then confirm the whole queue still drains onto the replacement rather than stalling. + // + // Ordering matters: `_evict()` calls `_drain()` SYNCHRONOUSLY inside the onerror stack, so the + // replacement worker posts B before the line after `onerror()` runs. replyMode must therefore + // already be 'ok' at that moment, otherwise B is dispatched to a silent worker and hangs — + // which would be a flaw in this test, not in the pool. + FakeWebWorker.replyMode = 'silent'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, idleReleaseAfter: 0 }); + const a = pool.run([1]); + const b = pool.run([2]); + const c = pool.run([3]); + // A was already posted under 'silent' and stays pending; B/C are still queued. + FakeWebWorker.replyMode = 'ok'; + + const w = FakeWebWorker.instances[0]; + expect(FakeWebWorker.instances).toHaveLength(1); + w.onerror!({ message: 'process killed' }); + + await expect(a).rejects.toThrow('process killed'); + await expect(b).resolves.toBe(4); + await expect(c).resolves.toBe(6); + // The dead worker was replaced by exactly one new worker that drained both queued tasks. + expect(FakeWebWorker.instances).toHaveLength(2); + expect(FakeWebWorker.instances[0].terminated).toBe(true); + pool.terminate(); + }); +}); + +describe('BUSY-state failures (previously covered — kept so the matrix is explicit)', () => { + test('an error while busy rejects the running task and replaces the worker', async () => { + FakeWebWorker.replyMode = 'silent'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + const pending = pool.run([1]); + FakeWebWorker.instances[0].onerror!({ message: 'script not found' }); + await expect(pending).rejects.toThrow('script not found'); + + FakeWebWorker.replyMode = 'ok'; + await expect(pool.run([2])).resolves.toBe(4); + expect(FakeWebWorker.instances).toHaveLength(2); + expect(FakeWebWorker.instances[0].terminated).toBe(true); + pool.terminate(); + }); + + test('a malformed reply while busy rejects and evicts', async () => { + FakeWebWorker.replyMode = 'malformed'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, idleReleaseAfter: 0 }); + await expect(pool.run([1])).rejects.toThrow(/malformed reply/); + expect(FakeWebWorker.instances[0].terminated).toBe(true); + + FakeWebWorker.replyMode = 'ok'; + await expect(pool.run([2])).resolves.toBe(4); + pool.terminate(); + }); +}); + +describe('Repeated failure does not wedge the pool', () => { + test('five consecutive idle crashes are each recovered', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, idleReleaseAfter: 0 }); + for (let i = 0; i < 5; i++) { + await expect(pool.run([i])).resolves.toBe(i * 2); + const w = FakeWebWorker.instances[FakeWebWorker.instances.length - 1]; + w.onerror!({ message: `crash #${i}` }); + await tick(); + expect(w.terminated).toBe(true); + } + // Each crash spawned a replacement, so the pool never wedged. + const final = await settleOrHang(pool.run([100])); + expect(final.hung).toBe(false); + expect(final.value).toBe(200); + pool.terminate(); + }); + + test('a late reply from an evicted worker is ignored', async () => { + FakeWebWorker.replyMode = 'silent'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, idleReleaseAfter: 0 }); + const pending = pool.run([4]); + const dead = FakeWebWorker.instances[0]; + dead.onerror!({ message: 'killed' }); + await expect(pending).rejects.toThrow('killed'); + + FakeWebWorker.replyMode = 'ok'; + await expect(pool.run([5])).resolves.toBe(10); + const survivor = FakeWebWorker.instances[1]; + + // The dead worker wakes up and answers the very first (already-rejected) task id. + // It must not disturb the survivor's state or resolve anything twice. + dead.onmessage!({ data: { id: 1, ok: true, value: 999 } }); + await tick(); + expect(survivor.terminated).toBe(false); + expect(FakeWebWorker.instances).toHaveLength(2); + pool.terminate(); + }); +}); diff --git a/tests/misc/worker-pal.test.ts b/tests/misc/worker-pal.test.ts new file mode 100644 index 0000000000..a25acd0148 --- /dev/null +++ b/tests/misc/worker-pal.test.ts @@ -0,0 +1,107 @@ +import { createWorkerBackend as createWebBackend } from '../../pal/worker/web/index'; +import { createWorkerBackend as createNativeBackend } from '../../pal/worker/native/index'; +import { createWorkerBackend as createNodeBackend } from '../../pal/worker/nodejs/index'; +import { createWorkerBackend as createMinigameBackend } from '../../pal/worker/minigame/index'; +import { minigame } from 'pal/minigame'; + +describe('distributed PAL worker platform entries', () => { + const saved = new Map(); + let savedMinigame: PropertyDescriptorMap; + + beforeEach(() => { + for (const key of ['Worker', 'Blob', 'URL']) { + saved.set(key, Object.getOwnPropertyDescriptor(globalThis, key)); + } + savedMinigame = Object.getOwnPropertyDescriptors(minigame); + for (const key of Object.keys(minigame)) delete minigame[key]; + }); + + afterEach(() => { + for (const [key, descriptor] of saved) { + if (descriptor) Object.defineProperty(globalThis, key, descriptor); + else delete (globalThis as any)[key]; + } + for (const key of Object.keys(minigame)) delete minigame[key]; + Object.defineProperties(minigame, savedMinigame); + }); + + test.each([createNativeBackend, createNodeBackend])('unsupported targets ignore browser globals', (createBackend) => { + (globalThis as any).Worker = jest.fn(); + const backend = createBackend(); + expect(backend.concurrencyLimit).toBe(0); + expect(backend.scriptFallback).toBeNull(); + expect(backend.createFunctionWorker(() => 1)).toBeNull(); + expect(() => backend.createScriptWorker('task.js')).toThrow(); + expect(Worker).not.toHaveBeenCalled(); + }); + + test('Web function capability checks Blob and URL, with no stale support cache', () => { + (globalThis as any).Worker = jest.fn(); + (globalThis as any).Blob = undefined; + const backend = createWebBackend(); + expect(backend.supportsFunctionWorker).toBe(false); + (globalThis as any).Blob = class {}; + (globalThis as any).URL = { createObjectURL: jest.fn() }; + expect(backend.supportsFunctionWorker).toBe(true); + }); + + test('a failed Web constructor still releases its Blob URL', () => { + (globalThis as any).Worker = jest.fn(() => { throw new Error('blocked'); }); + (globalThis as any).Blob = class {}; + (globalThis as any).URL = { + createObjectURL: jest.fn(() => 'blob:test'), + revokeObjectURL: jest.fn(), + }; + expect(() => createWebBackend().createFunctionWorker(() => 1)).toThrow('blocked'); + expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:test'); + }); + + test('minigame remains a minigame with no createWorker; PAL supplies devtools fallback', () => { + (globalThis as any).Worker = jest.fn(() => ({ terminate: jest.fn() })); + const backend = createMinigameBackend(); + expect(backend.concurrencyLimit).toBe(0); + expect(backend.supportsFunctionWorker).toBe(false); + expect(backend.scriptFallback!.diagnose('task.js').ready).toBe(true); + const resolved = backend.resolveScriptWorker('task.js'); + expect(resolved.backend).not.toBe(backend); + expect(resolved.backend!.concurrencyLimit).toBe(Infinity); + expect(resolved.warnOnFailure).toBe(false); + backend.createScriptWorker('task.js'); + expect(Worker).toHaveBeenCalledWith('task.js'); + }); + + test('PAL resolves unavailable targets and suppresses expected fallback warnings', () => { + const resolution = createNativeBackend().resolveScriptWorker('task.js'); + expect(resolution.backend).toBeNull(); + expect(resolution.diagnosis.ready).toBe(false); + expect(resolution.warnOnFailure).toBe(false); + expect(createNativeBackend().supportsStandardWorker).toBe(false); + }); + test('minigame API calls retain their host receiver', () => { + minigame.createWorker = jest.fn(function (this: any) { + expect(this).toBe(minigame); + return { terminate: jest.fn(), onMessage: jest.fn(), postMessage: jest.fn() }; + }); + createMinigameBackend().createScriptWorker('workers/task.js').terminate(); + expect(minigame.createWorker).toHaveBeenCalled(); + }); + + test('rechecking a single-worker host without a filesystem does not consume its occupied slot', () => { + let active = 0; + minigame.createWorker = jest.fn(() => { + if (active) throw new Error('only one worker allowed'); + active++; + return { terminate: () => { active--; }, onMessage: jest.fn(), postMessage: jest.fn() }; + }); + const first = createMinigameBackend(); + expect(first.resolveScriptWorker('workers/task.js').backend).toBe(first); + const worker = first.createScriptWorker('workers/task.js'); + expect(active).toBe(1); + const refreshed = createMinigameBackend(); + expect(refreshed.resolveScriptWorker('workers/task.js').backend).toBe(refreshed); + expect(minigame.createWorker).toHaveBeenCalledTimes(2); // one probe + one real worker + worker.terminate(); + expect(active).toBe(0); + }); + +}); diff --git a/tests/misc/worker-platform-matrix.test.ts b/tests/misc/worker-platform-matrix.test.ts new file mode 100644 index 0000000000..2d73e372bf --- /dev/null +++ b/tests/misc/worker-platform-matrix.test.ts @@ -0,0 +1,372 @@ +/** + * Platform backend tests: the capability matrix across ALL nine mini-game platforms plus Web. + * + * This is the test that the original implementation lacked, and its absence is exactly why seven + * platforms shipped with no parallelism: the fallback chain only ever branched on the `WECHAT` + * constant, so ByteDance / Alipay / Baidu / Huawei / OPPO / vivo / Xiaomi silently fell through to + * synchronous execution, and nothing asserted otherwise. + * + * Capabilities are injected through the pal boundary (the same `minigame` object the backend imports), + * which is how a real device obtains them: every `pal/minigame/*.js` adapter begins with + * `cloneObject(minigame, )`, copying `createWorker` over already bound to + * wx / tt / my / swan / qg / ral. + * + * Expected matrix (each row verified against that platform's official docs): + * + * Platform concurrencyLimit transfer parallel note + * ----------- ---------------- -------- -------- ------------------------------------------ + * WeChat V1 1 no no legacy worker + * WeChat V2 Infinity yes yes env.isSupportStandardWorker (grey release) + * ByteDance 1 no no tt.createWorker + * Alipay 1 no no my.createWorker + * Baidu 1 no no swan.createWorker, base library 1.6.1+ + * Huawei quick game 1 no no qg.createWorker 1117+; structured clone only + * vivo 1 no no qg.createWorker; one worker max + * OPPO 1 no no qg.createWorker; one worker max + * Xiaomi 1 no no qg.createWorker; one worker max + * Taobao 0 no no NO worker API at all + * Web Infinity yes yes global Worker + */ +import { minigame } from 'pal/minigame'; +import { + getWorkerBackend, getWorkerCapabilities, resetWorkerBackendCache, +} from '../../cocos/misc/worker'; +import { checkWorkerScript, getOptimalWorkerCount, getWorkerConcurrencyLimit } from '../../cocos/misc/worker'; + +class FakeMinigameWorker { + public static instances: FakeMinigameWorker[] = []; + public readonly path: string; + public posted: any[] = []; + public transfers: any[][] = []; + public terminated = false; + public messageListener: ((res: any) => void) | null = null; + public errorListener: ((err: any) => void) | null = null; + + constructor (path: string) { + this.path = path; + FakeMinigameWorker.instances.push(this); + } + + public postMessage (msg: any, transfer?: any[]): void { + this.posted.push(msg); + this.transfers.push(transfer as any); + Promise.resolve().then(() => { + if (this.messageListener) { + this.messageListener({ id: msg.id, ok: true, value: (msg.args || [])[0] }); + } + }); + } + + public onMessage (cb: (res: any) => void): void { this.messageListener = cb; } + public onError (cb: (err: any) => void): void { this.errorListener = cb; } + public terminate (): void { this.terminated = true; } +} + +/** Wipe pal and install one platform's capability surface. */ +function installPlatform (opts: { + hasCreateWorker?: boolean; + standardWorker?: boolean; + hasSystemInfo?: boolean; +}): void { + for (const k of Object.keys(minigame)) { delete (minigame as any)[k]; } + // Every mini-game adapter has getSystemInfoSync regardless of worker support. This is what lets a + // worker-less mini-game platform (Taobao) still be recognised as a mini-game platform, so it gets + // a precise diagnostic instead of a generic one. + if (opts.hasSystemInfo !== false) { + (minigame as any).getSystemInfoSync = () => ({ platform: 'devtools' }); + } + if (opts.standardWorker !== undefined) { + (minigame as any).env = { isSupportStandardWorker: opts.standardWorker === true }; + } + if (opts.hasCreateWorker !== false) { + (minigame as any).createWorker = (path: string): FakeMinigameWorker => new FakeMinigameWorker(path); + } + // The packaged script exists and is non-empty. + (minigame as any).getFileSystemManager = () => ({ + accessSync: (_p: string): void => {}, + statSync: (_p: string) => ({ size: 128 }), + }); + resetWorkerBackendCache(); +} + +afterEach(() => { + for (const k of Object.keys(minigame)) { delete (minigame as any)[k]; } + resetWorkerBackendCache(); + FakeMinigameWorker.instances.length = 0; +}); + +describe('Mini-game platform capability matrix', () => { + // WeChat V2 is the ONLY mini-game generation with multiple concurrent workers and transfer. + test('WeChat V2 (standard worker): unlimited concurrency + transfer', () => { + installPlatform({ standardWorker: true }); + const caps = getWorkerCapabilities(); + expect(caps).toMatchObject({ + supportsStandardWorker: true, + available: true, + parallel: true, + concurrencyLimit: Infinity, + supportsTransfer: true, + supportsFunctionWorker: false, // no Blob / no eval on any mini-game platform + }); + expect(checkWorkerScript('workers/demo.js').version).toBe(2); + }); + + test('WeChat V1 (legacy worker): exactly one worker, data copied', () => { + installPlatform({ standardWorker: false }); + const caps = getWorkerCapabilities(); + expect(caps).toMatchObject({ + supportsStandardWorker: false, available: true, parallel: false, + concurrencyLimit: 1, supportsTransfer: false, + }); + expect(checkWorkerScript('workers/demo.js').version).toBe(1); + }); + + // ByteDance / Alipay / Baidu / Huawei / OPPO / vivo / Xiaomi: all have createWorker, all cap at 1. + // They differ only in which global they bind it to (tt/my/swan/qg/ral), which cloneObject absorbs. + const singleWorkerPlatforms: Array<[string, { hasEnv: boolean }]> = [ + ['ByteDance (tt.createWorker)', { hasEnv: false }], + ['Alipay (my.createWorker)', { hasEnv: false }], + ['Baidu (swan.createWorker, 1.6.1+)', { hasEnv: false }], + ['Huawei quick game (qg.createWorker, 1117+)', { hasEnv: false }], + ['vivo (qg.createWorker)', { hasEnv: false }], + ['OPPO (qg.createWorker)', { hasEnv: false }], + ['Xiaomi (qg.createWorker)', { hasEnv: false }], + ]; + + test.each(singleWorkerPlatforms)('%s: one worker, no transfer, but genuinely available', (_name, opts) => { + installPlatform({ standardWorker: undefined }); + if (!opts.hasEnv) { delete (minigame as any).env; } + resetWorkerBackendCache(); + + const caps = getWorkerCapabilities(); + // The crux of this whole refactor: these platforms previously resolved to 'sync' or 'none'. + expect(caps.available).toBe(true); + expect(caps.parallel).toBe(false); + expect(caps.concurrencyLimit).toBe(1); + expect(caps.supportsTransfer).toBe(false); + expect(caps).not.toHaveProperty('kind'); + expect(caps.supportsStandardWorker).toBe(false); + expect(checkWorkerScript('workers/demo.js').ready).toBe(true); + expect(getWorkerConcurrencyLimit()).toBe(1); + }); + + test('Taobao: a mini-game platform with NO worker API — available false, precise reason', () => { + // Taobao's API surface has no worker category, and no Web Worker / Blob / URL either. + installPlatform({ hasCreateWorker: false }); + const caps = getWorkerCapabilities(); + expect(caps.available).toBe(false); + expect(caps.parallel).toBe(false); + expect(caps.concurrencyLimit).toBe(0); + + const status = checkWorkerScript('workers/demo.js'); + expect(status.ready).toBe(false); + // Must name the real situation, not a generic "no backend" — otherwise the developer cannot + // tell a platform limitation from their own packaging mistake. + expect(status.reason).toMatch(/no createWorker API/); + expect(status.reason).toMatch(/Taobao/); + }); + + test('Taobao reports no transfer and no SharedArrayBuffer support', () => { + installPlatform({ hasCreateWorker: false }); + const caps = getWorkerCapabilities(); + expect(caps.supportsTransfer).toBe(false); + expect(caps.supportsSharedArrayBuffer).toBe(false); + }); +}); + +/** + * `caps.reason` exists to answer the only question a developer actually has when a feature does not + * parallelise: "is this MY bug, or a platform rule I must design around?" A bare `available: false` / + * `parallel: false` cannot answer it. These tests pin the four distinct capability levels to four + * distinct explanations. + */ +describe('capability reason distinguishes a platform rule from a fixable problem', () => { + test('is never empty, on any backend', () => { + installPlatform({ standardWorker: true }); + expect(getWorkerCapabilities().reason.length).toBeGreaterThan(0); + installPlatform({ standardWorker: false }); + expect(getWorkerCapabilities().reason.length).toBeGreaterThan(0); + installPlatform({ hasCreateWorker: false }); + expect(getWorkerCapabilities().reason.length).toBeGreaterThan(0); + }); + + test('WeChat V2 explains that real parallelism IS available', () => { + installPlatform({ standardWorker: true }); + const caps = getWorkerCapabilities(); + expect(caps.parallel).toBe(true); + expect(caps.reason).toMatch(/standard \(V2\) worker/); + expect(caps.reason).toMatch(/multiple workers/i); + // A fully capable platform must not read like an error. + expect(caps.reason).not.toMatch(/cannot|no separate thread/i); + }); + + test('a single-worker platform says the cap is a PLATFORM RULE, not a config problem', () => { + installPlatform({ standardWorker: false }); + const caps = getWorkerCapabilities(); + expect(caps.parallel).toBe(false); + expect(caps.reason).toMatch(/exactly ONE worker/i); + // The decisive assertion: the string must tell the developer to stop looking for a bug in + // their own maxWorkers setting. + expect(caps.reason).toMatch(/platform rule/i); + expect(caps.reason).toMatch(/not a configuration problem/i); + // And it must still credit what DOES work, so the offload use case is not dismissed. + expect(caps.reason).toMatch(/off the main thread/i); + }); + + test.each([ + ['ByteDance', { standardWorker: undefined }], + ['Alipay', { standardWorker: undefined }], + ['Huawei quick game', { standardWorker: undefined }], + ])('%s gives the same single-worker explanation as WeChat V1', (_name, opts) => { + installPlatform(opts); + delete (minigame as any).env; + resetWorkerBackendCache(); + const caps = getWorkerCapabilities(); + expect(caps.concurrencyLimit).toBe(1); + expect(caps.reason).toMatch(/platform rule/i); + }); + + test('Taobao explains there is no thread to be had at all', () => { + installPlatform({ hasCreateWorker: false }); + const caps = getWorkerCapabilities(); + expect(caps.available).toBe(false); + expect(caps.reason).toMatch(/no createWorker API/); + expect(caps.reason).toMatch(/no separate thread/i); + }); + + test('native (no pal, no global Worker) names the embedded-engine cause', () => { + for (const k of Object.keys(minigame)) { delete (minigame as any)[k]; } + resetWorkerBackendCache(); + const caps = getWorkerCapabilities(); + expect(caps.available).toBe(false); + expect(caps.reason).toMatch(/native platforms/i); + expect(caps.reason).toMatch(/embedded engine/i); + }); +}); + +describe('Transfer semantics differ by platform', () => { + test('a single-worker platform drops the transfer list rather than risking a throw', () => { + installPlatform({ standardWorker: false }); + const backend = getWorkerBackend(); + const w = backend.createScriptWorker('workers/demo.js'); + const buf = new ArrayBuffer(8); + w.postMessage({ id: 1, args: [7] }, [buf]); + // Huawei quick game documents structured clone with no transferable objects; passing the list + // there may throw, so the adapter must omit it. + expect(FakeMinigameWorker.instances[0].transfers[0]).toBeUndefined(); + w.terminate(); + }); + + test('WeChat V2 passes the transfer list through', () => { + installPlatform({ standardWorker: true }); + const backend = getWorkerBackend(); + const w = backend.createScriptWorker('workers/demo.js'); + const buf = new ArrayBuffer(8); + w.postMessage({ id: 1, args: [7] }, [buf]); + expect(FakeMinigameWorker.instances[0].transfers[0]).toEqual([buf]); + w.terminate(); + }); +}); + +describe('getOptimalWorkerCount respects the platform cap first', () => { + test('returns 1 on a single-worker mini-game platform', () => { + installPlatform({ standardWorker: false }); + expect(getOptimalWorkerCount()).toBe(1); + }); + + test('returns 1 where there is no worker at all (Taobao / native)', () => { + installPlatform({ hasCreateWorker: false }); + expect(getOptimalWorkerCount()).toBe(1); + }); + + test('never exceeds the platform cap even when hardwareConcurrency is large', () => { + installPlatform({ standardWorker: false }); + // jsdom provides navigator.hardwareConcurrency; the platform cap of 1 must win over it. + expect(getOptimalWorkerCount()).toBe(1); + }); +}); + +describe('Backend resolution order', () => { + test('a mini-game platform wins over a global Worker (devtools exposes both)', () => { + installPlatform({ standardWorker: false }); + // A WeChat devtools build can expose a global Worker while only wx.createWorker works in + // production. The mini-game backend must be selected. + class FakeWebWorker { + public postMessage (): void {} + public terminate (): void {} + } + (globalThis as any).Worker = FakeWebWorker; + try { + resetWorkerBackendCache(); + expect(getWorkerBackend().supportsFunctionWorker).toBe(false); + } finally { + delete (globalThis as any).Worker; + resetWorkerBackendCache(); + } + }); + + test('re-probing after resetWorkerBackendCache picks up a newly available capability', () => { + // Models a WeChat subpackage finishing its download after the first probe: without a reset the + // pool stays locked to a worse backend for its whole lifetime. + installPlatform({ hasCreateWorker: false }); + expect(getWorkerCapabilities().available).toBe(false); + + (minigame as any).createWorker = (path: string): FakeMinigameWorker => new FakeMinigameWorker(path); + resetWorkerBackendCache(); + expect(getWorkerCapabilities().available).toBe(true); + expect(checkWorkerScript('workers/demo.js').ready).toBe(true); + }); + + test('createWorker returning undefined is reported, not silently accepted', () => { + installPlatform({}); + // Huawei quick game returns undefined on failure instead of throwing. + (minigame as any).createWorker = (): undefined => undefined; + resetWorkerBackendCache(); + expect(() => getWorkerBackend().createScriptWorker('workers/demo.js')) + .toThrow(/returned no worker/); + }); +}); + +describe('Path validation is platform-wide, not WeChat-only', () => { + test.each([ + ['', /non-empty string/], + ['/workers/demo.js', /must be relative/], + ['workers/demo.ts', /must be a \.js file/], + ])('rejects %p on a single-worker platform', (path, reason) => { + installPlatform({ standardWorker: false }); + const status = checkWorkerScript(path); + expect(status.ready).toBe(false); + expect(status.reason).toMatch(reason); + }); + + test('rejects an invalid path on ByteDance too (previously unchecked)', () => { + installPlatform({}); + delete (minigame as any).env; + resetWorkerBackendCache(); + const status = checkWorkerScript('/absolute/demo.js'); + expect(status.ready).toBe(false); + expect(status.reason).toMatch(/must be relative/); + }); +}); + +describe('Worker handle routes messages through the mini-game API shape', () => { + test('onMessage delivers the payload and terminate is forwarded', async () => { + installPlatform({ standardWorker: false }); + const backend = getWorkerBackend(); + const w = backend.createScriptWorker('workers/demo.js'); + const got = new Promise((resolve) => { w.onMessage(resolve); }); + w.postMessage({ id: 3, args: [42] }); + await expect(got).resolves.toMatchObject({ id: 3, ok: true, value: 42 }); + w.terminate(); + expect(FakeMinigameWorker.instances[0].terminated).toBe(true); + }); + + test('a platform without onError does not throw when one is registered', () => { + installPlatform({}); + const w = getWorkerBackend().createScriptWorker('workers/demo.js'); + const raw = FakeMinigameWorker.instances[0] as any; + // Huawei quick game documents only create/postMessage/onMessage/terminate. + delete raw.onError; + expect(() => w.onError(() => {})).not.toThrow(); + }); +}); diff --git a/tests/misc/worker-pool.test.ts b/tests/misc/worker-pool.test.ts new file mode 100644 index 0000000000..b29b6046c7 --- /dev/null +++ b/tests/misc/worker-pool.test.ts @@ -0,0 +1,99 @@ +/** + * WorkerPool / worker tests for an environment WITHOUT any worker backend: + * jsdom has no global `Worker`, `WECHAT` is false and there is no `wx` — so script mode can only + * resolve to the `'sync'` backend (with options.fallback) or `'none'` (without), and function mode + * must run inline on the main thread. + * + * The Web-Worker backend is covered by `worker-web.test.ts`, the WeChat backends by + * `worker-wechat.test.ts` (each test file gets its own jsdom environment + module registry, so the + * module-level caches in worker.ts cannot leak between them). + */ +import { WorkerPool } from '../../cocos/misc/worker-pool'; +import { checkWorkerScript, getWorkerConcurrencyLimit } from '../../cocos/misc/worker'; + +describe('Worker capability detection without any backend', () => { + test('checkWorkerScript reports not-ready when the platform has no worker', () => { + const status = checkWorkerScript('workers/demo.js'); + expect(status.ready).toBe(false); + expect(status.version).toBe(0); + expect(status.reason).toMatch(/no worker backend on this platform/); + }); + + test('getWorkerConcurrencyLimit is 0 when no Worker exists', () => { + expect(getWorkerConcurrencyLimit()).toBe(0); + }); +}); + +describe('WorkerPool script mode without any worker backend', () => { + test('rejects with a precise reason when no fallback was provided', async () => { + const pool = new WorkerPool('workers/demo.js'); + await expect(pool.run([1])).rejects.toThrow(/No worker backend for/); + // The reason must explain BOTH missing backends so the developer knows what to fix. + await expect(pool.run([1])).rejects.toThrow(/no worker backend on this platform/); + await expect(pool.run([1])).rejects.toThrow(/no createWorker and no global Worker/); + pool.terminate(); + }); + + test('runs single-threaded via options.fallback and resolves', async () => { + const fallback = jest.fn((a: number, b: number) => a + b); + const pool = new WorkerPool('workers/demo.js', { fallback }); + await expect(pool.run([1, 2])).resolves.toBe(3); + await expect(pool.run([10, 20])).resolves.toBe(30); + expect(fallback).toHaveBeenCalledTimes(2); + expect(fallback).toHaveBeenLastCalledWith(10, 20); + pool.terminate(); + }); + + test('a throwing fallback rejects the task but keeps the pool usable', async () => { + let shouldThrow = true; + const pool = new WorkerPool('workers/demo.js', { + fallback: (v: number) => { + if (shouldThrow) { throw new Error('fallback boom'); } + return v; + }, + }); + await expect(pool.run([1])).rejects.toThrow('fallback boom'); + shouldThrow = false; + await expect(pool.run([7])).resolves.toBe(7); + pool.terminate(); + }); + + test('a non-function fallback is ignored (backend stays none)', async () => { + const pool = new WorkerPool('workers/demo.js', { fallback: 42 as any }); + await expect(pool.run([1])).rejects.toThrow(/No worker backend for/); + pool.terminate(); + }); +}); + +describe('WorkerPool function mode without worker support', () => { + test('runs the task inline synchronously', async () => { + const pool = new WorkerPool((a: number) => a * 2); + await expect(pool.run([21])).resolves.toBe(42); + pool.terminate(); + }); + + test('an inline task that throws rejects', async () => { + const pool = new WorkerPool(() => { + throw new Error('inline boom'); + }); + await expect(pool.run([])).rejects.toThrow('inline boom'); + pool.terminate(); + }); +}); + +describe('WorkerPool argument and lifecycle boundaries', () => { + test('constructor rejects invalid first arguments', () => { + expect(() => new WorkerPool('')).toThrow(TypeError); + expect(() => new WorkerPool(123 as any)).toThrow(TypeError); + expect(() => new WorkerPool(null as any)).toThrow(TypeError); + expect(() => new WorkerPool(undefined as any)).toThrow(TypeError); + expect(() => new WorkerPool({} as any)).toThrow(TypeError); + }); + + test('run after terminate rejects and terminate is idempotent', async () => { + const pool = new WorkerPool('workers/demo.js', { fallback: () => 1 }); + pool.terminate(); + await expect(pool.run([])).rejects.toThrow(/terminated/); + expect(() => pool.terminate()).not.toThrow(); + }); +}); diff --git a/tests/misc/worker-resolution.test.ts b/tests/misc/worker-resolution.test.ts new file mode 100644 index 0000000000..47b64f2da6 --- /dev/null +++ b/tests/misc/worker-resolution.test.ts @@ -0,0 +1,205 @@ +jest.mock('pal/worker', () => ({ createWorkerBackend: jest.fn() })); + +import { createWorkerBackend } from 'pal/worker'; +import { WorkerPool } from '../../cocos/misc/worker-pool'; +import { resetWorkerBackendCache } from '../../cocos/misc/worker'; + +test('function workers use PAL concurrency without reading any host identity', async () => { + let reply: (value: any) => void; + const backend = { + get kind() { throw new Error('host identity must not be read'); }, + hardwareConcurrency: 8, + concurrencyLimit: 2, + supportsFunctionWorker: true, + scriptFailureHint: '', + createFunctionWorker: jest.fn((fn: (...args: any[]) => any) => ({ + postMessage: (msg: any) => { Promise.resolve().then(() => reply({ id: msg.id, ok: true, value: fn(...msg.args) })); }, + onMessage: (listener: (value: any) => void) => { reply = listener; }, + onError: jest.fn(), + terminate: jest.fn(), + })), + }; + (createWorkerBackend as jest.Mock).mockReturnValue(backend); + resetWorkerBackendCache(); + const pool = new WorkerPool((n: number) => n + 1, { maxWorkers: 4 }); + try { + expect(pool.backend).toBe('worker'); + expect(pool.concurrency).toBe(2); + await expect(pool.run([41])).resolves.toBe(42); + } finally { + pool.terminate(); + resetWorkerBackendCache(); + } +}); + +test('pool schedules the exact PAL-selected backend without reading any host identity', async () => { + let reply: (value: any) => void; + const selected = { + get kind() { throw new Error('host identity must not be read'); }, + concurrencyLimit: 2, + scriptFailureHint: '', + createScriptWorker: jest.fn(() => ({ + postMessage: (msg: any) => { Promise.resolve().then(() => reply({ id: msg.id, ok: true, value: msg.args[0] * 2 })); }, + onMessage: (fn: (value: any) => void) => { reply = fn; }, + onError: jest.fn(), + terminate: jest.fn(), + })), + }; + const root = { + get kind() { throw new Error('host identity must not be read'); }, + hardwareConcurrency: 8, + concurrencyLimit: 1, + scriptFailureHint: '', + createScriptWorker: jest.fn(() => { throw new Error('must use PAL-selected backend'); }), + resolveScriptWorker: jest.fn(() => ({ + backend: selected, + diagnosis: { ready: true, version: 1, reason: '' }, + warnOnFailure: false, + })), + }; + (createWorkerBackend as jest.Mock).mockReturnValue(root); + resetWorkerBackendCache(); + const pool = new WorkerPool('task.js', { maxWorkers: 4 }); + try { + expect(pool.backend).toBe('worker'); + expect(pool.concurrency).toBe(2); + await expect(pool.run([21])).resolves.toBe(42); + expect(selected.createScriptWorker).toHaveBeenCalledWith('task.js'); + expect(root.createScriptWorker).not.toHaveBeenCalled(); + expect(pool.recheck()).toBe('worker'); + } finally { + pool.terminate(); + resetWorkerBackendCache(); + } +}); + +function controlledBackend() { + const handles: any[] = []; + const backend = { + hardwareConcurrency: 4, concurrencyLimit: 2, supportsFunctionWorker: true, + supportsTransfer: true, scriptFailureHint: '', + resolveScriptWorker: () => ({ backend, diagnosis: { ready: true, version: 1, reason: '' }, warnOnFailure: false }), + createScriptWorker: jest.fn(() => { + const handle: any = { + postMessage: jest.fn(), terminate: jest.fn(), + onMessage: (fn: any) => { handle.reply = fn; }, + onError: (fn: any) => { handle.fail = fn; }, + }; + handles.push(handle); + return handle; + }), + createFunctionWorker: jest.fn(() => backend.createScriptWorker()), + }; + return { backend, handles }; +} + +const unavailable = { + hardwareConcurrency: 1, concurrencyLimit: 0, supportsFunctionWorker: false, scriptFailureHint: '', + resolveScriptWorker: () => ({ backend: null, diagnosis: { ready: false, version: 0, reason: 'unavailable' }, warnOnFailure: false }), +}; + +afterEach(() => resetWorkerBackendCache()); + +test('a different pool refreshing the PAL cache does not change function backend selection', async () => { + const { backend, handles } = controlledBackend(); + (createWorkerBackend as jest.Mock).mockReturnValue(backend); + resetWorkerBackendCache(); + const pool = new WorkerPool((n: number) => n + 1); + (createWorkerBackend as jest.Mock).mockReturnValue(unavailable); + resetWorkerBackendCache(); + const inline = new WorkerPool((n: number) => n + 2); + const result = pool.run([1]); + expect(handles).toHaveLength(1); + handles[0].reply({ id: 1, ok: true, value: 2 }); + await expect(result).resolves.toBe(2); + await expect(inline.run([1])).resolves.toBe(3); + pool.terminate(); inline.terminate(); +}); + +test.each([true, false])('recheck retires busy workers and settles queued tasks (fallback=%s)', async (fallback) => { + const { backend, handles } = controlledBackend(); + (createWorkerBackend as jest.Mock).mockReturnValue(backend); + resetWorkerBackendCache(); + const pool = new WorkerPool('task.js', { maxWorkers: 1, idleReleaseAfter: 0, fallback: fallback ? (n: number) => n * 3 : undefined }); + const running = pool.run([2]); + const queued = pool.run([3]); + const checkQueued = fallback ? expect(queued).resolves.toBe(9) : expect(queued).rejects.toThrow(/unavailable/); + (createWorkerBackend as jest.Mock).mockReturnValue(unavailable); + expect(pool.recheck()).toBe(fallback ? 'sync' : 'none'); + expect(handles[0].terminate).not.toHaveBeenCalled(); + handles[0].reply({ id: 1, ok: true, value: 4 }); + await expect(running).resolves.toBe(4); + await checkQueued; + expect(handles[0].terminate).toHaveBeenCalledTimes(1); + expect(handles[0].postMessage).toHaveBeenCalledTimes(1); + pool.terminate(); +}); + +test('late errors from a retired worker do not degrade the newly checked backend', async () => { + const old = controlledBackend(); const fresh = controlledBackend(); + (createWorkerBackend as jest.Mock).mockReturnValue(old.backend); + resetWorkerBackendCache(); + const pool = new WorkerPool('task.js', { maxWorkers: 1, fallback: () => -1 }); + const failed = expect(pool.run()).rejects.toThrow('old error'); + (createWorkerBackend as jest.Mock).mockReturnValue(fresh.backend); + pool.recheck(); + old.handles[0].fail(new Error('old error')); + await failed; + expect(pool.backend).toBe('worker'); + const next = pool.run(); + fresh.handles[0].reply({ id: 2, ok: true, value: 42 }); + await expect(next).resolves.toBe(42); + pool.terminate(); +}); + +test('synchronous postMessage exceptions evict the worker and drain through fallback', async () => { + const { backend } = controlledBackend(); + const make = backend.createScriptWorker.getMockImplementation()!; + backend.createScriptWorker.mockImplementation(() => { + const handle = make(); + handle.postMessage.mockImplementation(() => { throw new Error('send failed'); }); + return handle; + }); + (createWorkerBackend as jest.Mock).mockReturnValue(backend); + resetWorkerBackendCache(); + const pool = new WorkerPool('task.js', { fallback: (n: number) => n * 3 }); + await expect(pool.run([2])).resolves.toBe(6); + await expect(pool.run([3])).resolves.toBe(9); + expect(pool.backend).toBe('sync'); + pool.terminate(); +}); + +test('transferred arguments are never replayed after worker failure', async () => { + const { backend, handles } = controlledBackend(); + const fallback = jest.fn((arg: Uint8Array) => arg[0]); + (createWorkerBackend as jest.Mock).mockReturnValue(backend); + resetWorkerBackendCache(); + const pool = new WorkerPool('task.js', { fallback }); + const bytes = new Uint8Array([42]); + const result = pool.run([bytes], [bytes.buffer]); + // Node MessageChannel performs a real ownership transfer, unlike a mock postMessage. + const { port1, port2 } = new (require('worker_threads').MessageChannel)(); + port1.postMessage(bytes, [bytes.buffer]); + port1.close(); port2.close(); + expect(bytes.byteLength).toBe(0); + handles[0].fail(new Error('worker died')); + await expect(result).rejects.toThrow('worker died'); + expect(fallback).not.toHaveBeenCalled(); + expect(pool.backend).toBe('sync'); + await expect(pool.run([new Uint8Array([7])])).resolves.toBe(7); + pool.terminate(); +}); + + +test('a large queued batch drains iteratively after synchronous fallback', async () => { + const { backend, handles } = controlledBackend(); + (createWorkerBackend as jest.Mock).mockReturnValue(backend); + resetWorkerBackendCache(); + const pool = new WorkerPool('task.js', { maxWorkers: 1, fallback: (n: number) => n + 1 }); + const results = Array.from({ length: 10000 }, (_, n) => pool.run([n])); + handles[0].fail(new Error('worker died')); + const values = await Promise.all(results); + expect(values[0]).toBe(1); + expect(values[9999]).toBe(10000); + pool.terminate(); +}); diff --git a/tests/misc/worker-timeout-recheck.test.ts b/tests/misc/worker-timeout-recheck.test.ts new file mode 100644 index 0000000000..06140b8da6 --- /dev/null +++ b/tests/misc/worker-timeout-recheck.test.ts @@ -0,0 +1,249 @@ +/** + * Tests for the two stage-2 capabilities that close the "worker goes silent" and "probed too early" + * holes: + * + * 1. `options.timeout` — a watchdog per dispatched task. A worker that accepts a message and never + * replies (deadlock, infinite loop, a platform that drops the message) used to leave the task + * pending FOREVER and, worse, left that worker parked in the pool with `busy === true`, silently + * shrinking the pool by one on every occurrence. The watchdog must both fail the task AND evict + * the worker, so the next task lands on a fresh one. + * + * 2. `pool.recheck()` — backend resolution used to happen once at construction and could never be + * revisited. That is wrong whenever capability appears LATER: a worker script inside a WeChat + * subpackage that finishes downloading after the pool was built, or `wx.env.isSupportStandardWorker` + * flipping as the V2 grey release rolls out. Without recheck the pool stays locked to 'sync'/'none' + * for its whole lifetime. + * + * jsdom has no `Worker`, so we stub the global. `replyMode = 'silent'` reproduces the hang. + */ +import { WorkerPool } from '../../cocos/misc/worker-pool'; +import { getWorkerBackend, resetWorkerBackendCache } from '../../cocos/misc/worker'; + +type ReplyMode = 'ok' | 'silent'; + +class FakeWebWorker { + public static instances: FakeWebWorker[] = []; + public static replyMode: ReplyMode = 'ok'; + + public readonly url: string; + public posted: any[] = []; + public terminated = false; + public onmessage: ((e: { data: any }) => void) | null = null; + public onerror: ((e: any) => void) | null = null; + + constructor (url: string) { + this.url = url; + FakeWebWorker.instances.push(this); + } + + public postMessage (msg: any): void { + this.posted.push(msg); + if (FakeWebWorker.replyMode === 'silent') { + // The hang: message accepted, no reply ever. This is what the watchdog exists for. + return; + } + Promise.resolve().then(() => { + if (this.onmessage) { this.onmessage({ data: { id: msg.id, ok: true, value: msg.args[0] * 2 } }); } + }); + } + + public terminate (): void { + this.terminated = true; + } +} + +/** Install / remove the global `Worker` so a pool can be built before capability exists. */ +function installWorker (): void { + (globalThis as any).Worker = FakeWebWorker; +} +function removeWorker (): void { + delete (globalThis as any).Worker; +} + +beforeEach(() => { + installWorker(); + FakeWebWorker.instances.length = 0; + FakeWebWorker.replyMode = 'ok'; + resetWorkerBackendCache(); +}); + +afterEach(() => { + removeWorker(); + resetWorkerBackendCache(); +}); + +describe('options.timeout — watchdog on an unresponsive worker', () => { + test('a silent worker fails the task instead of hanging forever', async () => { + FakeWebWorker.replyMode = 'silent'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, timeout: 30 }); + + await expect(pool.run([1])).rejects.toThrow(/timed out after 30ms/); + pool.terminate(); + }); + + test('the timed-out worker is EVICTED, not left busy in the pool', async () => { + FakeWebWorker.replyMode = 'silent'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, timeout: 30 }); + + await expect(pool.run([1])).rejects.toThrow(/timed out/); + const dead = FakeWebWorker.instances[0]; + expect(dead.terminated).toBe(true); + + // The decisive part: the pool must not reuse the corpse. Recover the worker and confirm the + // NEXT task lands on a fresh instance rather than being swallowed by the dead one. + FakeWebWorker.replyMode = 'ok'; + await expect(pool.run([5])).resolves.toBe(10); + expect(FakeWebWorker.instances.length).toBe(2); + pool.terminate(); + }); + + test('the error message is actionable (names the protocol and the docs)', async () => { + FakeWebWorker.replyMode = 'silent'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, timeout: 30 }); + await expect(pool.run([1])).rejects.toThrow(/engine protocol|README/); + pool.terminate(); + }); + + test('a slow-but-successful worker is NOT timed out when the reply arrives in time', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, timeout: 500 }); + await expect(pool.run([7])).resolves.toBe(14); + // No eviction on success: the same worker must serve the next task. + await expect(pool.run([8])).resolves.toBe(16); + expect(FakeWebWorker.instances.length).toBe(1); + pool.terminate(); + }); + + test('the watchdog is cleared after each task (no timer leak across many tasks)', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, timeout: 5000 }); + for (let i = 0; i < 50; i++) { + // eslint-disable-next-line no-await-in-loop + await expect(pool.run([i])).resolves.toBe(i * 2); + } + // A leaked timer per task would still be pending; nothing should fire after terminate(). + pool.terminate(); + // If a stale timer were still armed it would fire against a disposed worker and could reject + // an unrelated task. Give any such timer a chance to surface as an unhandled rejection. + await new Promise((r) => setTimeout(r, 30)); + expect(FakeWebWorker.instances.length).toBe(1); + }); + + test('timeout defaults to OFF, preserving the previous behaviour', async () => { + FakeWebWorker.replyMode = 'silent'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + const outcome = await Promise.race([ + pool.run([1]).then(() => 'RESOLVED').catch(() => 'REJECTED'), + new Promise((r) => setTimeout(() => r('STILL_PENDING'), 80)), + ]); + expect(outcome).toBe('STILL_PENDING'); + pool.terminate(); + }); + + test('an invalid timeout (0 / negative / NaN) is treated as OFF', async () => { + FakeWebWorker.replyMode = 'silent'; + for (const bad of [0, -1, Number.NaN]) { + // eslint-disable-next-line no-await-in-loop + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1, timeout: bad }); + // eslint-disable-next-line no-await-in-loop + const outcome = await Promise.race([ + pool.run([1]).then(() => 'RESOLVED').catch(() => 'REJECTED'), + new Promise((r) => setTimeout(() => r('STILL_PENDING'), 40)), + ]); + expect(outcome).toBe('STILL_PENDING'); + pool.terminate(); + } + }); +}); + +describe('pool.recheck() — upgrading a backend that was probed too early', () => { + test('a pool built with no Worker at all resolves to sync/none, then upgrades to web', async () => { + removeWorker(); + resetWorkerBackendCache(); + // Built before capability existed. With a fallback it degrades to 'sync'; without one 'none'. + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 4, fallback: (n: number) => n * 3 }); + expect(pool.backend).toBe('sync'); + await expect(pool.run([2])).resolves.toBe(6); // computed inline on the main thread + + // Capability appears (e.g. the subpackage finished downloading). + installWorker(); + expect(pool.recheck()).toBe('worker'); + expect(pool.backend).toBe('worker'); + // Now it really goes through a worker: the fallback would have returned 6, the worker returns 4. + await expect(pool.run([2])).resolves.toBe(4); + expect(FakeWebWorker.instances.length).toBe(1); + pool.terminate(); + }); + + test("recheck lifts the 'none' state so run() stops rejecting", async () => { + removeWorker(); + resetWorkerBackendCache(); + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 2 }); // no fallback + expect(pool.backend).toBe('none'); + await expect(pool.run([1])).rejects.toThrow(/No worker backend for/); + + installWorker(); + expect(pool.recheck()).toBe('worker'); + await expect(pool.run([3])).resolves.toBe(6); + pool.terminate(); + }); + + test('recheck can grow the pool once the concurrency cap is lifted', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 3 }); + FakeWebWorker.replyMode = 'silent'; + // Fill the pool to maxWorkers with unresponsive tasks. + const pending = [pool.run([1]), pool.run([2]), pool.run([3])]; + await new Promise((r) => setTimeout(r, 5)); + expect(FakeWebWorker.instances.length).toBe(3); + // A fourth task cannot start: the pool is full and every worker is busy. + const fourth = pool.run([4]); + await new Promise((r) => setTimeout(r, 5)); + expect(FakeWebWorker.instances.length).toBe(3); + + FakeWebWorker.replyMode = 'ok'; + // Recovering recheck() must re-drain so the queued task is picked up. + pool.recheck(); + expect(pool.recheck()).toBe('worker'); + pool.terminate(); + await expect(Promise.allSettled([...pending, fourth])).resolves.toBeDefined(); + }); + + test('recheck never destroys in-flight work', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + const inflight = pool.run([9]); + // Re-probe while a task is running: the running worker must survive and still deliver. + expect(pool.recheck()).toBe('worker'); + await expect(inflight).resolves.toBe(18); + expect(FakeWebWorker.instances[0].terminated).toBe(true); // retired only after delivering its result + pool.terminate(); + }); + + test('recheck on a terminated pool is a safe no-op', () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + pool.terminate(); + expect(pool.recheck()).toBe('worker'); + // No new worker may be spawned after termination. + expect(FakeWebWorker.instances.length).toBe(0); + }); + + test('recheck is idempotent when nothing changed', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 2 }); + expect(pool.recheck()).toBe('worker'); + expect(pool.recheck()).toBe('worker'); + await expect(pool.run([4])).resolves.toBe(8); + expect(FakeWebWorker.instances.length).toBe(1); + pool.terminate(); + }); +}); + +describe('backend cache reset', () => { + test('resetWorkerBackendCache re-probes the platform', () => { + expect(getWorkerBackend().concurrencyLimit).toBe(Infinity); + removeWorker(); + // Still cached: the original concurrency capability remains until the backend is reset. + expect(getWorkerBackend().concurrencyLimit).toBe(Infinity); + resetWorkerBackendCache(); + expect(getWorkerBackend().concurrencyLimit).toBe(0); + installWorker(); + resetWorkerBackendCache(); + expect(getWorkerBackend().concurrencyLimit).toBe(Infinity); + }); +}); diff --git a/tests/misc/worker-web.test.ts b/tests/misc/worker-web.test.ts new file mode 100644 index 0000000000..ea1f08c9a8 --- /dev/null +++ b/tests/misc/worker-web.test.ts @@ -0,0 +1,150 @@ +/** + * WorkerPool / worker tests for the standard Web `Worker` backend. + * + * jsdom does not implement `Worker`, so we stub the global with a fake that speaks the engine + * protocol ({ id, args } in, { id, ok, value|error } out) over plain callbacks. This covers the + * `'web'` backend of the script-mode fallback chain, protocol boundary checks and worker errors. + */ +import { WorkerPool } from '../../cocos/misc/worker-pool'; +import { createWorker, getWorkerConcurrencyLimit } from '../../cocos/misc/worker'; + +type ReplyMode = 'ok' | 'malformed' | 'error' | 'silent'; + +class FakeWebWorker { + public static instances: FakeWebWorker[] = []; + public static replyMode: ReplyMode = 'ok'; + + public readonly url: string; + public posted: any[] = []; + public terminated = false; + public onmessage: ((e: { data: any }) => void) | null = null; + public onerror: ((e: any) => void) | null = null; + + constructor (url: string) { + this.url = url; + FakeWebWorker.instances.push(this); + } + + public postMessage (msg: any): void { + this.posted.push(msg); + const mode = FakeWebWorker.replyMode; + if (mode === 'silent') { + return; + } + const reply = mode === 'malformed' + ? 'garbage-not-an-object' + : mode === 'error' + ? { id: msg.id, ok: false, error: 'web task failed' } + : { id: msg.id, ok: true, value: msg.args[0] * 2 }; + Promise.resolve().then(() => { + if (this.onmessage) { this.onmessage({ data: reply }); } + }); + } + + public terminate (): void { + this.terminated = true; + } +} + +beforeAll(() => { + (globalThis as any).Worker = FakeWebWorker; +}); + +afterAll(() => { + delete (globalThis as any).Worker; +}); + +beforeEach(() => { + FakeWebWorker.instances.length = 0; + FakeWebWorker.replyMode = 'ok'; +}); + +describe('Web backend detection', () => { + test('getWorkerConcurrencyLimit is Infinity when a global Worker exists', () => { + expect(getWorkerConcurrencyLimit()).toBe(Infinity); + }); +}); + +describe('WorkerPool script mode on the Web Worker backend', () => { + test('creates a worker from the script path and resolves tasks', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + await expect(pool.run([21])).resolves.toBe(42); + expect(FakeWebWorker.instances).toHaveLength(1); + expect(FakeWebWorker.instances[0].url).toBe('workers/demo.js'); + expect(FakeWebWorker.instances[0].posted[0]).toMatchObject({ id: expect.any(Number), args: [21] }); + pool.terminate(); + expect(FakeWebWorker.instances[0].terminated).toBe(true); + }); + + test('reuses one worker for sequential tasks', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + await expect(pool.run([1])).resolves.toBe(2); + await expect(pool.run([2])).resolves.toBe(4); + await expect(pool.run([3])).resolves.toBe(6); + expect(FakeWebWorker.instances).toHaveLength(1); + pool.terminate(); + }); + + test('scales to maxWorkers and queues the excess', async () => { + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 2 }); + const results = await Promise.all([pool.run([1]), pool.run([2]), pool.run([3])]); + expect(results).toEqual([2, 4, 6]); + // Two workers max; the third task must have been queued and dispatched to a free one. + expect(FakeWebWorker.instances).toHaveLength(2); + pool.terminate(); + }); + + test('a malformed reply rejects with a protocol error instead of hanging', async () => { + FakeWebWorker.replyMode = 'malformed'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + await expect(pool.run([1])).rejects.toThrow(/malformed reply/); + pool.terminate(); + }); + + test('an error envelope reply rejects with the worker-side message', async () => { + FakeWebWorker.replyMode = 'error'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + await expect(pool.run([1])).rejects.toThrow('web task failed'); + pool.terminate(); + }); + + test('a worker load/runtime error rejects the running task', async () => { + FakeWebWorker.replyMode = 'silent'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + const pending = pool.run([1]); + // Simulate the browser firing `onerror` (e.g. the script 404s — Web cannot pre-check existence). + const w = FakeWebWorker.instances[0]; + expect(w).toBeDefined(); + w.onerror!({ message: 'script not found' }); + await expect(pending).rejects.toThrow('script not found'); + pool.terminate(); + }); + + test('a failed worker is replaced, not reused', async () => { + FakeWebWorker.replyMode = 'malformed'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + await expect(pool.run([1])).rejects.toThrow(/malformed reply/); + FakeWebWorker.replyMode = 'ok'; + await expect(pool.run([2])).resolves.toBe(4); + expect(FakeWebWorker.instances).toHaveLength(2); + expect(FakeWebWorker.instances[0].terminated).toBe(true); + pool.terminate(); + }); +}); + +describe('createWorker(path) on the Web backend', () => { + test('wraps a global Worker and routes messages both ways', async () => { + const w = createWorker('workers/demo.js'); + expect(w).not.toBeNull(); + expect(FakeWebWorker.instances).toHaveLength(1); + const got = new Promise((resolve) => { w!.onMessage(resolve); }); + w!.postMessage({ id: 7, args: [4] }); + await expect(got).resolves.toEqual({ id: 7, ok: true, value: 8 }); + w!.terminate(); + expect(FakeWebWorker.instances[0].terminated).toBe(true); + }); + + test('rejects an empty path', () => { + expect(() => createWorker('')).toThrow(TypeError); + }); +}); diff --git a/tests/misc/worker-wechat.test.ts b/tests/misc/worker-wechat.test.ts new file mode 100644 index 0000000000..91a7e5b77b --- /dev/null +++ b/tests/misc/worker-wechat.test.ts @@ -0,0 +1,369 @@ +/** + * Worker tests for the WeChat mini-game environment. + * + * Capability is injected through the **pal boundary** (`minigame.createWorker` / `minigame.env` / + * `minigame.getFileSystemManager`) rather than through a raw `globalThis.wx` stub. That is deliberate: + * it is how the engine actually obtains these functions — every `pal/minigame/*.js` adapter starts + * with `cloneObject(minigame, wx)`, which copies them over already bound. Injecting at the pal layer + * means this test exercises the same path a real device does. + * + * Covers: + * - `checkWorkerScript` completeness checks (createWorker present, path validity, file existence, + * empty file, V1/V2 generation); + * - the WorkerPool backend chain: fully-set-up V1 (capped to 1 worker) and V2 (parallel), + * not-fully-set-up -> options.fallback single-thread, no fallback -> precise rejection; + * - protocol boundary checks (malformed reply / error envelope) over the mini-game worker; + * - `createWorker(path)` wrapping `minigame.createWorker`, transfer semantics (V1 copies, V2 + * transfers), and onProcessKilled routing. + * + * jsdom has no global `Worker` here, so the "our own Web Worker" rung of the chain is absent — + * exactly the real-device situation. + */ +import { WorkerPool } from '../../cocos/misc/worker-pool'; +import { + checkWorkerScript, createWorker, getWorkerConcurrencyLimit, isSupportStandardWorker, +} from '../../cocos/misc/worker'; +import { resetWorkerBackendCache } from '../../cocos/misc/worker'; +// The SAME object instance the PAL worker entry imported. `tests/init.ts` maps `pal/minigame` to +// `non-minigame.js` (an empty object) during setupFiles — which runs BEFORE this file, so the backend +// module is already instantiated against that instance. A `jest.mock` here would be too late to +// rebind it; mutating this object is what the backend actually observes. +import { minigame } from 'pal/minigame'; + +type ReplyMode = 'ok' | 'malformed' | 'error' | 'silent'; + +class FakeWxWorker { + public static instances: FakeWxWorker[] = []; + public static replyMode: ReplyMode = 'ok'; + + public readonly path: string; + public posted: any[] = []; + public transfers: any[][] = []; + public terminated = false; + public messageListener: ((res: any) => void) | null = null; + public errorListener: ((err: any) => void) | null = null; + public killedListener: ((err?: any) => void) | null = null; + + constructor (path: string) { + this.path = path; + FakeWxWorker.instances.push(this); + } + + public postMessage (msg: any, transfer?: any[]): void { + this.posted.push(msg); + this.transfers.push(transfer as any); + const mode = FakeWxWorker.replyMode; + if (mode === 'silent') { + return; + } + const reply = mode === 'malformed' + ? { hello: 'world' } // no id / no ok -> protocol violation + : mode === 'error' + ? { id: msg.id, ok: false, error: 'wx task failed' } + : { id: msg.id, ok: true, value: msg.args[0] * 2 }; + Promise.resolve().then(() => { + if (this.messageListener) { this.messageListener(reply); } + }); + } + + public onMessage (cb: (res: any) => void): void { this.messageListener = cb; } + public onError (cb: (err: any) => void): void { this.errorListener = cb; } + public onProcessKilled (cb: (err?: any) => void): void { this.killedListener = cb; } + public terminate (): void { this.terminated = true; } +} + +interface WxStubOptions { + /** Report V2 standard-worker support (env.isSupportStandardWorker === true). */ + v2?: boolean; + /** Files "present" in the code package: path -> size in bytes. Default: demo file exists. */ + files?: Record; + /** Set false to simulate an old base library without createWorker. */ + createWorker?: boolean; + /** + * Simulate the WeChat devtools simulator, whose `accessSync` routinely fails to see a workers + * directory that IS packaged (a false negative). `createWorker` still loads the script, so the + * readiness probe must recover and report READY rather than condemn a working setup to sync. + */ + accessSyncBlind?: boolean; +} + +/** Wipe and repopulate the pal minigame object, then drop the cached backend so it re-probes. */ +function installWx (opts: WxStubOptions = {}): any { + const files = opts.files !== undefined ? opts.files : { 'workers/demo.js': 128 }; + for (const k of Object.keys(minigame)) { delete (minigame as any)[k]; } + // Every mini-game adapter exposes getSystemInfoSync regardless of worker support. The backend uses + // it to recognise "this is a mini-game platform", which is what makes an old base library WITHOUT + // createWorker report a precise mini-game diagnostic instead of a generic one. + (minigame as any).getSystemInfoSync = () => ({ + platform: opts.v2 ? 'android' : 'devtools', version: '8.0.74', SDKVersion: '3.17.0', + }); + (minigame as any).env = { isSupportStandardWorker: opts.v2 === true }; + (minigame as any).getFileSystemManager = () => ({ + accessSync: (p: string): void => { + // `accessSyncBlind` reproduces the devtools simulator, which cannot see a packaged workers + // directory; otherwise a file is visible exactly when it is present in `files`. + if (opts.accessSyncBlind || !Object.prototype.hasOwnProperty.call(files, p)) { + throw new Error(`accessSync failed: ${p} does not exist`); + } + }, + statSync: (p: string) => ({ size: files[p] }), + }); + if (opts.createWorker !== false) { + (minigame as any).createWorker = jest.fn((path: string) => { + // A real device cannot load a script that is absent from the code package, so createWorker + // throws. This is what lets diagnose()'s readiness probe — the authoritative check that runs + // after accessSync fails — report "not ready" for a genuinely missing file, while still + // reporting "ready" for the devtools false negative above (accessSyncBlind), where the + // script loads even though accessSync could not see it. + if (!Object.prototype.hasOwnProperty.call(files, path)) { + throw new Error(`createWorker failed: ${path} does not exist in the code package`); + } + return new FakeWxWorker(path); + }); + } + resetWorkerBackendCache(); + return minigame; +} + +afterEach(() => { + for (const k of Object.keys(minigame)) { delete (minigame as any)[k]; } + resetWorkerBackendCache(); + FakeWxWorker.instances.length = 0; + FakeWxWorker.replyMode = 'ok'; +}); + +describe('checkWorkerScript completeness checks', () => { + test('not ready when createWorker is missing (old base library)', () => { + installWx({ createWorker: false }); + const status = checkWorkerScript('workers/demo.js'); + expect(status).toMatchObject({ ready: false, version: 0 }); + expect(status.reason).toMatch(/no createWorker API/); + }); + + test('not ready when the platform exposes no worker API at all', () => { + // Nothing installed: this is the Taobao / native situation. + resetWorkerBackendCache(); + const status = checkWorkerScript('workers/demo.js'); + expect(status.ready).toBe(false); + expect(status.reason).toMatch(/no worker backend|no createWorker API/); + }); + + test.each([ + ['', /non-empty string/], + ['/workers/demo.js', /must be relative/], + ['workers/demo.ts', /must be a \.js file/], + ])('rejects an invalid path %p', (path, reason) => { + const wx = installWx(); + const status = checkWorkerScript(path); + expect(status.ready).toBe(false); + expect(status.reason).toMatch(reason); + expect(wx.createWorker).not.toHaveBeenCalled(); + }); + + test('not ready when the file does not exist in the code package', () => { + installWx({ files: {} }); + const status = checkWorkerScript('workers/demo.js'); + expect(status).toMatchObject({ ready: false, version: 0 }); + expect(status.reason).toMatch(/does not exist in the code package/); + expect(status.reason).toMatch(/game\.json/); + }); + + test('ready when accessSync is blind but createWorker loads the script (devtools false negative)', () => { + // The WeChat devtools simulator routinely fails to see a packaged workers directory through + // accessSync, yet createWorker loads the script fine. diagnose() must trust createWorker (the + // readiness probe) over accessSync, so this is reported READY instead of being condemned to the + // single-threaded fallback — the exact regression the probe exists to prevent. + installWx({ accessSyncBlind: true }); + const status = checkWorkerScript('workers/demo.js'); + expect(status).toEqual({ ready: true, version: 1, reason: '' }); + }); + + test('not ready when the file is empty', () => { + installWx({ files: { 'workers/demo.js': 0 } }); + const status = checkWorkerScript('workers/demo.js'); + expect(status.ready).toBe(false); + expect(status.reason).toMatch(/is empty/); + }); + + test('ready with version 1 on legacy workers', () => { + installWx({ v2: false }); + expect(checkWorkerScript('workers/demo.js')).toEqual({ ready: true, version: 1, reason: '' }); + expect(isSupportStandardWorker()).toBe(false); + expect(getWorkerConcurrencyLimit()).toBe(1); + }); + + test('ready with version 2 on standard workers', () => { + installWx({ v2: true }); + expect(checkWorkerScript('workers/demo.js')).toEqual({ ready: true, version: 2, reason: '' }); + expect(isSupportStandardWorker()).toBe(true); + expect(getWorkerConcurrencyLimit()).toBe(Infinity); + }); +}); + +describe('WeChat V2 grey-release contract', () => { + test.each([undefined, false, true])('uses the runtime flag %p, not eligible version numbers alone', (flag) => { + const wx = installWx(); + wx.getSystemInfoSync = () => ({ platform: 'android', version: '8.0.74', SDKVersion: '3.17.0' }); + wx.env = flag === undefined ? {} : { isSupportStandardWorker: flag }; + const worker = createWorker('workers/demo.js'); + expect(isSupportStandardWorker()).toBe(flag === true); + expect(getWorkerConcurrencyLimit()).toBe(flag === true ? Infinity : 1); + expect(checkWorkerScript('workers/demo.js').version).toBe(flag === true ? 2 : 1); + // Both generations use the same API. No legacy experimental option may be injected. + expect(wx.createWorker.mock.calls).toEqual([['workers/demo.js']]); + worker.terminate(); + }); + + test('missing env is safe on older runtimes', () => { + const wx = installWx(); + delete wx.env; + const worker = createWorker('workers/demo.js'); + expect(isSupportStandardWorker()).toBe(false); + expect(getWorkerConcurrencyLimit()).toBe(1); + expect(wx.createWorker.mock.calls).toEqual([['workers/demo.js']]); + worker.terminate(); + }); + + test('V2 readiness probes also use plain createWorker(path)', () => { + const wx = installWx({ v2: true, accessSyncBlind: true }); + expect(checkWorkerScript('workers/demo.js')).toMatchObject({ ready: true, version: 2 }); + expect(wx.createWorker.mock.calls).toEqual([['workers/demo.js']]); + expect(FakeWxWorker.instances[0].terminated).toBe(true); + }); + + test('creation failure uses the supplied sync fallback without pretending to select V1', async () => { + const wx = installWx({ v2: true }); + wx.createWorker.mockImplementation(() => { throw new Error('Worker creation failed'); }); + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 2, fallback: (n: number) => n * 2 }); + try { + await expect(pool.run([3])).resolves.toBe(6); + expect(pool.backend).toBe('sync'); + expect(wx.createWorker.mock.calls).toEqual([['workers/demo.js']]); + } finally { + pool.terminate(); + } + }); +}); + +describe('WorkerPool on a fully set up WeChat worker', () => { + test('V1 caps the pool to a single concurrent worker', async () => { + const wx = installWx({ v2: false }); + // Even asking for 4 workers, V1 must never create more than 1. + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 4 }); + const [a, b] = await Promise.all([pool.run([1]), pool.run([2])]); + expect([a, b]).toEqual([2, 4]); + expect(wx.createWorker).toHaveBeenCalledTimes(1); + expect(FakeWxWorker.instances[0].path).toBe('workers/demo.js'); + pool.terminate(); + expect(FakeWxWorker.instances[0].terminated).toBe(true); + }); + + test('V2 scales to maxWorkers and runs tasks in parallel', async () => { + const wx = installWx({ v2: true }); + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 2 }); + const results = await Promise.all([pool.run([1]), pool.run([2]), pool.run([3])]); + expect(results).toEqual([2, 4, 6]); + expect(wx.createWorker).toHaveBeenCalledTimes(2); + pool.terminate(); + }); + + test('a malformed reply rejects with a protocol error instead of hanging', async () => { + installWx(); + FakeWxWorker.replyMode = 'malformed'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + await expect(pool.run([1])).rejects.toThrow(/malformed reply/); + pool.terminate(); + }); + + test('an error envelope reply rejects with the worker-side message', async () => { + installWx(); + FakeWxWorker.replyMode = 'error'; + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 1 }); + await expect(pool.run([1])).rejects.toThrow('wx task failed'); + pool.terminate(); + }); +}); + +describe('WorkerPool fallback chain when WeChat is NOT fully set up', () => { + test('falls back to single-threaded options.fallback when the script is missing', async () => { + const wx = installWx({ files: {} }); // worker script missing from the package + // The inline executor calls the fallback with SPREAD args (this._fn(...task.args)), so + // run([21]) invokes fallback(21) — matching the documented `(n: number) => ...` convention. + const fallback = jest.fn((n: number) => n * 2); + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 4, fallback }); + await expect(pool.run([21])).resolves.toBe(42); + expect(fallback).toHaveBeenCalledWith(21); + // The readiness probe calls createWorker exactly once (and it throws, proving the script is + // missing); the pool then runs every task on the single-threaded fallback and never builds a + // real worker, so no FakeWxWorker instance is ever constructed. + expect(wx.createWorker).toHaveBeenCalledTimes(1); + expect(FakeWxWorker.instances).toHaveLength(0); + pool.terminate(); + }); + + test('without a fallback, run() rejects with the precise missing-file reason', async () => { + installWx({ files: {} }); + const pool = new WorkerPool('workers/demo.js', { maxWorkers: 4 }); + await expect(pool.run([1])).rejects.toThrow(/No worker backend for/); + await expect(pool.run([1])).rejects.toThrow(/does not exist in the code package/); + pool.terminate(); + }); + + test('an invalid path also lands on the fallback instead of throwing at createWorker', async () => { + const wx = installWx(); + const pool = new WorkerPool('/absolute/demo.js', { fallback: () => 'sync-result' }); + await expect(pool.run([])).resolves.toBe('sync-result'); + expect(wx.createWorker).not.toHaveBeenCalled(); + pool.terminate(); + }); +}); + +describe('createWorker(path) on WeChat', () => { + test('wraps createWorker and routes messages both ways', async () => { + installWx(); + const w = createWorker('workers/demo.js'); + expect(w).not.toBeNull(); + expect(FakeWxWorker.instances).toHaveLength(1); + const got = new Promise((resolve) => { w!.onMessage(resolve); }); + w!.postMessage({ id: 9, args: [5] }); + await expect(got).resolves.toEqual({ id: 9, ok: true, value: 10 }); + w!.terminate(); + expect(FakeWxWorker.instances[0].terminated).toBe(true); + }); + + test('V1 copies data (no transfer list), V2 passes transferables through', () => { + installWx({ v2: false }); + const w1 = createWorker('workers/demo.js')!; + const buf = new ArrayBuffer(8); + w1.postMessage({ id: 1, args: [] }, [buf]); + expect(FakeWxWorker.instances[0].transfers[0]).toBeUndefined(); + + FakeWxWorker.instances.length = 0; + installWx({ v2: true }); + const w2 = createWorker('workers/demo.js')!; + w2.postMessage({ id: 2, args: [] }, [buf]); + expect(FakeWxWorker.instances[0].transfers[0]).toEqual([buf]); + }); + + test('throws a descriptive error when the environment is incomplete and no Worker exists', () => { + installWx({ files: {} }); + // Both halves of the diagnosis must be present: the missing global Worker route, and the + // precise packaging reason embedded from diagnose(). + expect(() => createWorker('workers/demo.js')).toThrow(/no global Worker fallback/); + expect(() => createWorker('workers/demo.js')).toThrow(/does not exist in the code package/); + // And it must tell the developer what to do next. + expect(() => createWorker('workers/demo.js')).toThrow(/options\.fallback/); + }); + + test('onProcessKilled is routed to the error listener', () => { + installWx(); + const w = createWorker('workers/demo.js')!; + const errSpy = jest.fn(); + w.onError(errSpy); + const fake = FakeWxWorker.instances[0]; + expect(fake.killedListener).toBeInstanceOf(Function); + fake.killedListener!(); + expect(errSpy).toHaveBeenCalledTimes(1); + expect(String(errSpy.mock.calls[0][0].message)).toMatch(/process was killed/i); + }); +}); diff --git a/tests/mocks/pal-worker.js b/tests/mocks/pal-worker.js new file mode 100644 index 0000000000..c9f91f3624 --- /dev/null +++ b/tests/mocks/pal-worker.js @@ -0,0 +1,14 @@ +// Tests switch target at runtime; production selects the same PAL entries via cc.config.json. +// Only target selection is mocked. All worker behaviour runs the actual distributed PAL code. +const { minigame } = require('pal/minigame'); +const web = require('../../pal/worker/web/index'); +const mini = require('../../pal/worker/minigame/index'); +const native = require('../../pal/worker/native/index'); + +exports.createWorkerBackend = () => { + if (['getSystemInfoSync', 'createWorker', 'getFileSystemManager'] + .some((key) => typeof minigame[key] === 'function')) { + return mini.createWorkerBackend(); + } + return typeof Worker !== 'undefined' ? web.createWorkerBackend() : native.createWorkerBackend(); +}; diff --git a/tests/scripts/pal-worker-types.test.cjs b/tests/scripts/pal-worker-types.test.cjs new file mode 100644 index 0000000000..158dd8bae6 --- /dev/null +++ b/tests/scripts/pal-worker-types.test.cjs @@ -0,0 +1,36 @@ +// The engine declares the `pal/worker` contract itself (@types/pal/worker.d.ts) so that type checks +// work with any installed PAL. When a real PAL worker module is present, prove that its public +// types are structurally identical to that declaration, so the two cannot drift apart silently. +// PAL_WORKER_TYPES= checks a local cocos-pal build instead. +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const engine = path.resolve(__dirname, '../..'); +const realTypes = process.env.PAL_WORKER_TYPES + ? path.resolve(process.env.PAL_WORKER_TYPES) + : path.join(engine, 'pal/worker/type.d.ts'); + +test('@types/pal/worker.d.ts matches the PAL worker contract', { skip: !fs.existsSync(realTypes) && 'no real PAL worker module installed' }, (t) => { + const ts = require(path.join(engine, 'node_modules/typescript')); + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pal worker types ')); + t.after(() => fs.rmSync(dir, { recursive: true, force: true })); + const names = ['IWorker', 'IWorkerDiagnosis', 'IWorkerBackend', 'IPlatformWorkerBackend', 'IWorkerResolution', 'IWorkerCapabilities']; + const real = path.join(dir, 'real.d.ts'); + fs.copyFileSync(realTypes, real); + const check = path.join(dir, 'check.ts'); + fs.writeFileSync(check, [ + "import type * as Engine from 'pal/worker';", + "import type * as Pal from './real';", + 'type Same = [A] extends [B] ? ([B] extends [A] ? true : false) : false;', + ...names.map((n) => `export const ${n}: Same = true;`), + ].join('\n')); + const program = ts.createProgram([path.join(engine, '@types/pal/worker.d.ts'), check], { + strict: true, noEmit: true, types: [], lib: ['lib.es2017.d.ts', 'lib.dom.d.ts'], skipLibCheck: true, + }); + const diagnostics = ts.getPreEmitDiagnostics(program) + .map((d) => ts.flattenDiagnosticMessageText(d.messageText, '\n')); + assert.deepEqual(diagnostics, []); +}); diff --git a/tests/scripts/spread-pal.test.cjs b/tests/scripts/spread-pal.test.cjs new file mode 100644 index 0000000000..55e84e1a0b --- /dev/null +++ b/tests/scripts/spread-pal.test.cjs @@ -0,0 +1,298 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); +const { spawnSync } = require('child_process'); +const { pathToFileURL } = require('url'); + +test('common PAL entry rejects a missing root or a file before installing fallbacks', (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pal root ')); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const ensure = require('../../scripts/ensure-pal.cjs'); + const missing = path.join(root, 'missing'); + assert.throws(() => ensure(missing), /Install engine dependencies first/); + assert.equal(fs.existsSync(missing), false); + const file = path.join(root, 'file'); + fs.writeFileSync(file, 'unchanged'); + assert.throws(() => ensure(file), /Install engine dependencies first/); + assert.equal(fs.readFileSync(file, 'utf8'), 'unchanged'); +}); + +test('old generated fallback is refreshed when the engine PAL contract changes', (t) => { + const pal = fs.mkdtempSync(path.join(os.tmpdir(), 'pal contract ')); + t.after(() => fs.rmSync(pal, { recursive: true, force: true })); + const ensure = require('../../scripts/ensure-pal.cjs'); + assert.equal(ensure(pal), true); + const index = path.join(pal, 'worker/compat.js'); + const latest = fs.readFileSync(index, 'utf8'); + fs.writeFileSync(index, '// Compatibility only: real platform implementations remain in cocos-pal.\nexport function createWorkerBackend() { return {}; }\n'); + assert.equal(ensure(pal), true); + assert.equal(fs.readFileSync(index, 'utf8'), latest); + assert.equal(ensure(pal), false, 'unchanged compatibility files must not be rewritten'); +}); + +for (const entry of [ + 'build-h5-source.js', 'build-h5-minified.js', 'build-cli-minified.js', + 'build-declarations.js', 'build-const.js', 'compile-native-ts.js', +]) { + test(`${entry} prepares an existing old PAL before loading the compiler, without reinstalling`, (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'build old pal ')); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const scripts = path.join(root, 'scripts'); + fs.mkdirSync(scripts); + for (const name of [entry, 'ensure-pal.cjs', 'pal-worker-fallback']) { + fs.cpSync(path.resolve(__dirname, '../../scripts', name), path.join(scripts, name), { recursive: true }); + } + const pal = path.join(root, 'pal'); + fs.mkdirSync(pal); + fs.writeFileSync(path.join(pal, 'existing.js'), 'keep local PAL unchanged'); + // Stop when the actual entry loads ccbuild. No compiler dependencies or + // npm install are present in this fixture: preparation must happen first. + const preload = path.join(root, 'check.cjs'); + fs.writeFileSync(preload, ` + const fs = require('fs'); + const path = require('path'); + const assert = require('node:assert/strict'); + const Module = require('module'); + const originalLoad = Module._load; + Module._load = function (request, ...args) { + if (request === '@cocos/ccbuild') { + for (const platform of ['web', 'minigame', 'native', 'nodejs']) { + assert.ok(fs.existsSync(path.join(__dirname, 'pal/worker', platform, 'index.js'))); + } + // Types come from @types/pal/worker.d.ts; the compatibility module is JS only. + assert.equal(fs.existsSync(path.join(__dirname, 'pal/worker/type.d.ts')), false); + console.log('COMPILER_READY'); + process.exit(0); + } + if (request === 'fs-extra') return {}; + if (request === 'chalk') return {}; + return originalLoad.call(this, request, ...args); + }; + `); + function build() { + const result = spawnSync(process.execPath, ['--require', preload, path.join(scripts, entry)], { + cwd: os.tmpdir(), encoding: 'utf8', + }); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /COMPILER_READY/); + return result.stdout; + } + assert.match(build(), /single-thread compatibility/); + assert.equal(fs.readFileSync(path.join(pal, 'existing.js'), 'utf8'), 'keep local PAL unchanged'); + // Simulate a newer PAL and prove repeated builds do not replace it. + const workerEntry = path.join(pal, 'worker/web/index.js'); + fs.writeFileSync(workerEntry, 'real platform implementation'); + assert.doesNotMatch(build(), /single-thread compatibility/); + assert.equal(fs.readFileSync(workerEntry, 'utf8'), 'real platform implementation'); + }); +} + +test('install old PAL, upgrade to worker PAL, and downgrade without stale implementations', async (t) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'spread pal ')); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const scripts = path.join(root, 'scripts'); + const sourceScripts = path.resolve(__dirname, '../../scripts'); + fs.mkdirSync(scripts); + for (const name of ['spread-pal.cjs', 'ensure-pal.cjs', 'pal-worker-fallback']) { + fs.cpSync(path.join(sourceScripts, name), path.join(scripts, name), { recursive: true }); + } + // Use the default npm-package source, just like the engine postinstall hook. + const installed = path.join(root, 'node_modules/@cocos/engine-pal/dist'); + fs.mkdirSync(installed, { recursive: true }); + fs.writeFileSync(path.join(installed, 'unrelated.js'), 'export const value = 42;\n'); + fs.writeFileSync(path.join(root, 'package.json'), '{"type":"module"}'); + function spread(args = []) { + const result = spawnSync(process.execPath, [path.join(scripts, 'spread-pal.cjs'), ...args], { encoding: 'utf8' }); + assert.equal(result.status, 0, result.stderr); + return result.stdout; + } + assert.match(spread(), /single-thread compatibility/); + const destination = path.join(root, 'pal'); + assert.equal(fs.readFileSync(path.join(destination, 'unrelated.js'), 'utf8'), 'export const value = 42;\n'); + for (const platform of ['web', 'minigame', 'native', 'nodejs']) { + const entry = path.join(destination, 'worker', platform, 'index.js'); + const { createWorkerBackend } = await import(pathToFileURL(entry).href); + const backend = createWorkerBackend(); + assert.equal('kind' in backend, false); + assert.equal(backend.concurrencyLimit, 0); + assert.equal(backend.scriptFallback, null); + assert.equal(backend.createFunctionWorker(() => 42), null); + assert.match(backend.diagnose('task.js').reason, /PAL package has no worker module/); + assert.equal(fs.existsSync(entry.replace(/\.js$/, '.d.ts')), false); + } + assert.equal(fs.existsSync(path.join(destination, 'worker/type.d.ts')), false); + + const modern = path.join(root, 'new PAL dist'); + fs.mkdirSync(path.join(modern, 'worker/web'), { recursive: true }); + const realCode = 'export const realWorker = true;\n'; + fs.writeFileSync(path.join(modern, 'worker/web/index.js'), realCode); + assert.doesNotMatch(spread(['--source', modern]), /single-thread compatibility/); + assert.equal(fs.readFileSync(path.join(destination, 'worker/web/index.js'), 'utf8'), realCode); + assert.equal(fs.existsSync(path.join(destination, 'worker/index.js')), false); + + assert.match(spread(), /single-thread compatibility/); + assert.doesNotMatch(fs.readFileSync(path.join(destination, 'worker/web/index.js'), 'utf8'), /realWorker/); +}); + +// ------------------------------------------------------------------ upgrade paths without re-install + +const PLATFORMS = ['web', 'minigame', 'native', 'nodejs']; + +function makeEngine(t, label) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), `${label} `)); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const scripts = path.join(root, 'scripts'); + fs.mkdirSync(scripts); + for (const name of ['spread-pal.cjs', 'ensure-pal.cjs', 'pal-worker-fallback']) { + fs.cpSync(path.resolve(__dirname, '../../scripts', name), path.join(scripts, name), { recursive: true }); + } + const pkg = path.join(root, 'node_modules/@cocos/engine-pal'); + const dist = path.join(pkg, 'dist'); + const pal = path.join(root, 'pal'); + return { + root, dist, pal, + // A build entry: every scripts/build-*.js calls ensure-pal before loading the compiler. + ensure: () => require(path.join(scripts, 'ensure-pal.cjs'))(pal), + spread(args = []) { + const result = spawnSync(process.execPath, [path.join(scripts, 'spread-pal.cjs'), ...args], { encoding: 'utf8' }); + assert.equal(result.status, 0, result.stderr); + return result.stdout; + }, + installPackage(version, { worker, files = {} }) { + fs.rmSync(pkg, { recursive: true, force: true }); + fs.mkdirSync(dist, { recursive: true }); + fs.writeFileSync(path.join(pkg, 'package.json'), JSON.stringify({ name: '@cocos/engine-pal', version })); + for (const [file, content] of Object.entries(files)) fs.writeFileSync(path.join(dist, file), content); + if (worker) writeRealWorker(dist, version); + }, + }; +} + +function writeRealWorker(dist, tag) { + for (const platform of PLATFORMS) { + fs.mkdirSync(path.join(dist, 'worker', platform), { recursive: true }); + fs.writeFileSync(path.join(dist, 'worker', platform, 'index.js'), `export const real = '${platform} ${tag}';\n`); + } + fs.writeFileSync(path.join(dist, 'worker/type.d.ts'), 'export interface IWorker {}\n'); +} + +function isFallback(pal) { + return fs.existsSync(path.join(pal, 'worker/compat.js')) + && fs.readFileSync(path.join(pal, 'worker/compat.js'), 'utf8').startsWith('// Compatibility only'); +} + +test('fallback switches to the real worker when the installed package gains it without postinstall', (t) => { + const e = makeEngine(t, 'upgrade stamp'); + e.installPackage('1.0.4', { worker: false, files: { 'shared.js': 'v4', 'removed-later.js': 'old' } }); + assert.match(e.spread(), /single-thread compatibility/); + assert.ok(isFallback(e.pal)); + + // `npm install --ignore-scripts` (or a failed postinstall): package updated, pal/ untouched. + e.installPackage('1.0.5', { worker: true, files: { 'shared.js': 'v5' } }); + assert.equal(e.ensure(), true); + assert.equal(isFallback(e.pal), false); + for (const platform of PLATFORMS) { + assert.match(fs.readFileSync(path.join(e.pal, 'worker', platform, 'index.js'), 'utf8'), /1\.0\.5/); + } + // The whole directory follows the package: no module from the old version survives. + assert.equal(fs.readFileSync(path.join(e.pal, 'shared.js'), 'utf8'), 'v5'); + assert.equal(fs.existsSync(path.join(e.pal, 'removed-later.js')), false); + assert.equal(JSON.parse(fs.readFileSync(path.join(e.pal, '.pal-source.json'), 'utf8')).version, '1.0.5'); + assert.equal(e.ensure(), false, 'an up-to-date PAL must not be copied again'); +}); + +test('regular npm install (postinstall spread) replaces the fallback with the real worker', (t) => { + const e = makeEngine(t, 'upgrade postinstall'); + e.installPackage('1.0.4', { worker: false }); + e.spread(); + assert.ok(isFallback(e.pal)); + e.installPackage('1.0.5', { worker: true }); + assert.doesNotMatch(e.spread(), /single-thread compatibility/); + assert.equal(isFallback(e.pal), false); + assert.equal(fs.existsSync(path.join(e.pal, 'worker/web/index.js')), true); +}); + +test('a pal copy made before source stamps still picks up the installed worker module', (t) => { + const e = makeEngine(t, 'upgrade legacy'); + e.installPackage('1.0.4', { worker: false, files: { 'shared.js': 'v4' } }); + e.spread(); + fs.rmSync(path.join(e.pal, '.pal-source.json')); + e.installPackage('1.0.5', { worker: true, files: { 'shared.js': 'v5' } }); + assert.equal(e.ensure(), true); + assert.equal(isFallback(e.pal), false); + assert.match(fs.readFileSync(path.join(e.pal, 'worker/web/index.js'), 'utf8'), /1\.0\.5/); + // Without a stamp the rest of pal/ has no known version: only the missing worker is restored. + assert.equal(fs.readFileSync(path.join(e.pal, 'shared.js'), 'utf8'), 'v4'); + assert.equal(e.ensure(), false); +}); + +test('an explicit local PAL source is never mixed with or replaced by the npm package', (t) => { + const e = makeEngine(t, 'local source'); + const local = path.join(e.root, 'local PAL dist'); + fs.mkdirSync(local); + fs.writeFileSync(path.join(local, 'shared.js'), 'local'); + e.installPackage('1.0.5', { worker: true, files: { 'shared.js': 'npm' } }); + assert.match(e.spread(['--source', local]), /single-thread compatibility/); + assert.equal(e.ensure(), false); + assert.ok(isFallback(e.pal)); + assert.equal(fs.readFileSync(path.join(e.pal, 'shared.js'), 'utf8'), 'local'); + + // Once the local source gains a worker, the next build uses it. + writeRealWorker(local, 'local'); + assert.equal(e.ensure(), true); + assert.match(fs.readFileSync(path.join(e.pal, 'worker/native/index.js'), 'utf8'), /local/); + assert.equal(e.ensure(), false); +}); + +test('a real worker is kept as is, including a local build newer than the package', (t) => { + const e = makeEngine(t, 'keep real'); + const local = path.join(e.root, 'local PAL dist'); + writeRealWorker(local, 'local'); + e.installPackage('1.0.5', { worker: true }); + e.spread(['--source', local]); + assert.equal(e.ensure(), false); + assert.match(fs.readFileSync(path.join(e.pal, 'worker/web/index.js'), 'utf8'), /local/); +}); + +test('fallbacks generated with declaration files are rewritten as JS only', (t) => { + const e = makeEngine(t, 'old layout'); + fs.mkdirSync(e.pal); + assert.equal(e.ensure(), true); + fs.writeFileSync(path.join(e.pal, 'worker/type.d.ts'), 'export interface IWorker {}\n'); + for (const platform of PLATFORMS) { + fs.writeFileSync(path.join(e.pal, 'worker', platform, 'index.d.ts'), "export { createWorkerBackend } from '../index.js';\n"); + } + assert.equal(e.ensure(), true); + assert.equal(fs.existsSync(path.join(e.pal, 'worker/type.d.ts')), false); + assert.equal(fs.existsSync(path.join(e.pal, 'worker/web/index.d.ts')), false); + assert.ok(isFallback(e.pal)); + assert.equal(e.ensure(), false); +}); + +test('the fallback has no pal/worker/index.js, so `pal/worker` always resolves through the platform override', (t) => { + const e = makeEngine(t, 'no root index'); + fs.mkdirSync(e.pal); + assert.equal(e.ensure(), true); + assert.equal(fs.existsSync(path.join(e.pal, 'worker/index.js')), false); + for (const platform of PLATFORMS) { + assert.equal(fs.readFileSync(path.join(e.pal, 'worker', platform, 'index.js'), 'utf8'), + "export { createWorkerBackend } from '../compat.js';\n"); + } +}); + +test('a fallback generated with the old root index.js layout is migrated', (t) => { + const e = makeEngine(t, 'legacy root index'); + const worker = path.join(e.pal, 'worker'); + fs.mkdirSync(worker, { recursive: true }); + fs.copyFileSync(path.resolve(__dirname, '../../scripts/pal-worker-fallback/compat.js'), path.join(worker, 'index.js')); + for (const platform of PLATFORMS) { + fs.mkdirSync(path.join(worker, platform)); + fs.writeFileSync(path.join(worker, platform, 'index.js'), "export { createWorkerBackend } from '../index.js';\n"); + } + assert.equal(e.ensure(), true); + assert.equal(fs.existsSync(path.join(worker, 'index.js')), false); + assert.ok(isFallback(e.pal)); + assert.equal(e.ensure(), false); +}); diff --git a/tests/scripts/worker-release.test.cjs b/tests/scripts/worker-release.test.cjs new file mode 100644 index 0000000000..c356fbc9c8 --- /dev/null +++ b/tests/scripts/worker-release.test.cjs @@ -0,0 +1,149 @@ +// Run against the real ccbuild output (features: ['worker-pool'], HTML5, cjs, +// compress: true, DEBUG: false, mangleProperties: true). +// Usage: node tests/scripts/worker-release.test.cjs /absolute/path/to/cc.js +const fs = require('node:fs'); +const vm = require('node:vm'); +const assert = require('node:assert/strict'); +const { test } = require('node:test'); +const bundle = process.argv[2]; +if (!bundle) throw new Error('Pass the minified HTML5 worker feature bundle path.'); +const source = fs.readFileSync(bundle, 'utf8'); + +function load(code = source, filename = bundle) { + const handles = []; + class Worker { + constructor() { this.sent = []; this.stopped = 0; handles.push(this); } + postMessage(message, transfer) { + this.sent.push(structuredClone(message, { transfer: transfer || [] })); + } + terminate() { this.stopped++; } + reply(value, ok = true) { + const { id } = this.sent[this.sent.length - 1]; + this.onmessage({ data: { id, ok, value, error: ok ? undefined : value } }); + } + fail(message = 'backend failed') { this.onerror({ message }); } + } + const context = { exports: {}, console, Worker, navigator: { hardwareConcurrency: 4 }, + setTimeout, clearTimeout, ArrayBuffer, SharedArrayBuffer, Uint8Array }; + context.global = context; + vm.runInNewContext(code, context, { filename }); + return { cc: context.exports, handles }; +} + +if (process.argv[3] && process.argv[4]) { + test('basic Worker feature supports developer-managed messaging without WorkerPool', () => { + const filename = process.argv[3]; + const { cc, handles } = load(fs.readFileSync(filename, 'utf8'), filename); + assert.equal('WorkerPool' in cc, false); + assert.equal(handles.length, 0); + assert.equal(cc.getWorkerCapabilities().available, true); + const worker = cc.createWorker('workers/service.js'); + let received; + worker.onMessage(message => { received = message; }); + worker.postMessage({ cmd: 'ping' }); + assert.deepEqual(handles[0].sent[0], { cmd: 'ping' }); + handles[0].onmessage({ data: { cmd: 'pong' } }); + assert.deepEqual(received, { cmd: 'pong' }); + worker.terminate(); + assert.equal(handles[0].stopped, 1); + }); + + test('build without either Worker feature exports no Worker API', () => { + const filename = process.argv[4]; + const { cc, handles } = load(fs.readFileSync(filename, 'utf8'), filename); + assert.equal('WorkerPool' in cc, false); + assert.equal('createWorker' in cc, false); + assert.equal('getWorkerCapabilities' in cc, false); + assert.equal(handles.length, 0); + }); +} + +// Host workers are controlled substitutes; scheduler and PAL are the compiled code. +test('release API, queue reuse and message protocol survive property mangling', async () => { + const { cc, handles } = load(); + assert.equal(cc.getWorkerCapabilities().supportsTransfer, true); + assert.equal(cc.getOptimalWorkerCount(), 3); + const pool = new cc.WorkerPool('workers/task.js', { maxWorkers: 1, idleReleaseAfter: 0 }); + try { + assert.equal(pool.backend, 'worker'); + assert.equal(pool.concurrency, 1); + const first = pool.run([3]); + const second = pool.run([4]); + assert.deepEqual(handles[0].sent[0], { id: 1, args: [3] }); + handles[0].reply(6); + assert.equal(await first, 6); + handles[0].reply(8); + assert.equal(await second, 8); + assert.equal(handles.length, 1); + } finally { pool.terminate(); } + assert.equal(handles[0].stopped, 1); + await assert.rejects(pool.run(), /16502/); +}); + +test('concurrent failures retain safe fallback and reject transferred ownership', async () => { + const { cc, handles } = load(); + const calls = []; + const pool = new cc.WorkerPool('workers/task.js', { maxWorkers: 3, idleReleaseAfter: 0, + fallback: n => { calls.push(n); return n * 2; } }); + try { + const first = pool.run([3]); + const second = pool.run([4]); + const bytes = new Uint8Array([5]); + const transferred = assert.rejects(pool.run([bytes], [bytes.buffer]), /backend failed/); + assert.equal(bytes.byteLength, 0); + handles[0].fail(); handles[1].fail(); handles[2].fail(); + assert.equal(await first, 6); assert.equal(await second, 8); await transferred; + assert.deepEqual(calls.sort((a, b) => a - b), [3, 4]); + assert.equal(pool.backend, 'sync'); + assert.equal(await pool.run([6]), 12); + } finally { pool.terminate(); } +}); + +test('old worker errors after recheck cannot degrade the new backend', async () => { + const { cc, handles } = load(); + const pool = new cc.WorkerPool('workers/task.js', { idleReleaseAfter: 0, fallback: n => n * 2 }); + try { + const stale = assert.rejects(pool.run([3]), /stale/); + assert.equal(pool.recheck(), 'worker'); + const fresh = pool.run([4]); + handles[0].fail('stale'); await stale; + assert.equal(pool.backend, 'worker'); + handles[1].reply(8); assert.equal(await fresh, 8); + } finally { pool.terminate(); } +}); + +test('task errors reject without retry and the executor remains reusable', async () => { + const { cc, handles } = load(); + const pool = new cc.WorkerPool('workers/task.js', { idleReleaseAfter: 0, + fallback: () => { throw new Error('must not replay task errors'); } }); + try { + const failed = assert.rejects(pool.run(), /computation failed/); + handles[0].reply('computation failed', false); await failed; + const next = pool.run(); handles[0].reply(7); assert.equal(await next, 7); + assert.equal(handles.length, 1); + } finally { pool.terminate(); } +}); + +test('malformed replies and timeouts retain distinct release diagnostic IDs', async () => { + const { cc, handles } = load(); + const pool = new cc.WorkerPool('workers/task.js', { timeout: 20, idleReleaseAfter: 0 }); + try { + const malformed = assert.rejects(pool.run(), /16513/); + handles[0].onmessage({ data: {} }); await malformed; + await assert.rejects(pool.run(), /16511/); + assert.equal(handles[0].stopped, 1); + assert.equal(handles[1].stopped, 1); + } finally { pool.terminate(); } +}); + +test('function fallback and input validation remain available in release builds', async () => { + const { cc } = load(); + assert.throws(() => new cc.WorkerPool(''), /16500/); + assert.throws(() => new cc.WorkerPool(null), /16501/); + assert.throws(() => cc.createWorker(''), /16515/); + const pool = new cc.WorkerPool(n => n * 2, { idleReleaseAfter: 0 }); + try { + assert.equal(pool.backend, 'sync'); + assert.equal(await pool.run([3]), 6); + } finally { pool.terminate(); } +}); diff --git a/tsconfig.json b/tsconfig.json index 12cd52d262..32bf2cc5f4 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -49,6 +49,7 @@ "./@types/pal/screen-adapter", "./@types/pal/minigame", "./@types/pal/audio", + "./@types/pal/worker", "./@types/pal/input", "./@types/pal/env", "./@types/pal/pacer",