Multithreading (#322)

* worker pool

* opt

* backup

* worker and worker backend

* worker fallback

* opt

* opt

* remove meta

* opt

* worker export

* testcase fix

* worker js template

* worker pal

* worker opt

* test

* Replace error messages with error codes

* Package size reduction

* Package size reduction

* revert

* Restore editor asset .meta files to the base branch state

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014HAtWwr4dy5azfpccweh1g

* bugfix

* Split into two features: Worker and Worker Pool

* worker option

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
llsansun
2026-10-29 16:35:14 +08:00
committed by GitHub
parent 5e627951a0
commit 2157fd176d
43 changed files with 5164 additions and 23 deletions
+83
View File
@@ -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, <platformGlobal>)`,
* 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 {
+61
View File
@@ -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;
}
+68
View File
@@ -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).
+12
View File
@@ -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",
+6
View File
@@ -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';
+982
View File
@@ -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<TResult = unknown> (args?: unknown[], transfer?: Transferable[]): Promise<TResult> {
return new Promise<TResult>((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<typeof setTimeout> | null = null;
private _timeoutTimer: ReturnType<typeof setTimeout> | 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;
}
+413
View File
@@ -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<TArgs extends any[] = any[], TResult = unknown> = (...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);
}
+229
View File
@@ -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<number>([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 成功。
+100
View File
@@ -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);
};
}
+114
View File
@@ -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<void> {
// 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<number>([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 算法是否同步!');
}
}
}
+20
View File
@@ -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",
+12
View File
@@ -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: {
+12
View File
@@ -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: {
+28
View File
@@ -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';
+55
View File
@@ -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';
+1
View File
@@ -12,6 +12,7 @@ module.exports = {
moduleNameMapper: {
...pathsToModuleNameMapper(compilerOptions.paths, { prefix: `${__dirname}/` }),
'external:(.*)': '<rootDir>/native/external/$1',
'^pal/worker$': '<rootDir>/tests/mocks/pal-worker.js',
},
transformIgnorePatterns: [
// ignore everything in the node_modules EXCEPT for:
+2 -1
View File
@@ -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",
+1
View File
@@ -1,3 +1,4 @@
require('./ensure-pal.cjs')();
const { join } = require('path');
const { ensureDir, emptyDir } = require('fs-extra');
const { magenta } = require('chalk');
+1
View File
@@ -1,3 +1,4 @@
require('./ensure-pal.cjs')();
const { StatsQuery } = require('@cocos/ccbuild');
const { join } = require('path');
const { outputFileSync } = require('fs-extra');
+1
View File
@@ -1,3 +1,4 @@
require('./ensure-pal.cjs')();
const { join } = require('path');
const { emptyDir } = require('fs-extra');
const { dtsBundler } = require('@cocos/ccbuild');
+1
View File
@@ -1,3 +1,4 @@
require('./ensure-pal.cjs')();
const { join } = require('path');
const { ensureDir, emptyDir } = require('fs-extra');
const { magenta } = require('chalk');
+1
View File
@@ -1,3 +1,4 @@
require('./ensure-pal.cjs')();
const { join } = require('path');
const { ensureDir, emptyDir } = require('fs-extra');
const { magenta } = require('chalk');
+1
View File
@@ -1,3 +1,4 @@
require('./ensure-pal.cjs')();
const ccbuild = require('@cocos/ccbuild');
const ps = require('path');
const fs = require('fs-extra');
+192
View File
@@ -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;
+25
View File
@@ -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 }; },
};
}
+18 -22
View File
@@ -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}`);
+55
View File
@@ -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);
});
+193
View File
@@ -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]);
});
+145
View File
@@ -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<typeof WorkerPool>[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();
});
+67
View File
@@ -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();
}
});
});
+216
View File
@@ -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<T> (p: Promise<T>, 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<typeof sentinel>((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<void> {
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<number>([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<number>([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<number>([1]);
const b = pool.run<number>([2]);
const c = pool.run<number>([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<number>([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<number>([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();
});
});
+107
View File
@@ -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<string, PropertyDescriptor | undefined>();
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);
});
});
+372
View File
@@ -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, <platformGlobal>)`, 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<any>((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();
});
});
+99
View File
@@ -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();
});
});
+205
View File
@@ -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();
});
+249
View File
@@ -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<string>((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<string>((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);
});
});
+150
View File
@@ -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<any>((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);
});
});
+369
View File
@@ -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<string, number>;
/** 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<any>((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);
});
});
+14
View File
@@ -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();
};
+36
View File
@@ -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=<path to worker/type.d.ts> 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, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;',
...names.map((n) => `export const ${n}: Same<Engine.${n}, Pal.${n}> = 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, []);
});
+298
View File
@@ -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);
});
+149
View File
@@ -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(); }
});
+1
View File
@@ -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",