mirror of
https://github.com/cocos/cocos4.git
synced 2026-11-19 14:52:40 +08:00
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:
Vendored
+83
@@ -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 {
|
||||
|
||||
Vendored
+61
@@ -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;
|
||||
}
|
||||
@@ -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).
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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';
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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 成功。
|
||||
@@ -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);
|
||||
};
|
||||
}
|
||||
@@ -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 算法是否同步!');
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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",
|
||||
|
||||
@@ -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: {
|
||||
|
||||
@@ -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: {
|
||||
|
||||
@@ -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';
|
||||
@@ -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';
|
||||
@@ -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
@@ -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,3 +1,4 @@
|
||||
require('./ensure-pal.cjs')();
|
||||
const { join } = require('path');
|
||||
const { ensureDir, emptyDir } = require('fs-extra');
|
||||
const { magenta } = require('chalk');
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
require('./ensure-pal.cjs')();
|
||||
const { StatsQuery } = require('@cocos/ccbuild');
|
||||
const { join } = require('path');
|
||||
const { outputFileSync } = require('fs-extra');
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
require('./ensure-pal.cjs')();
|
||||
const { join } = require('path');
|
||||
const { emptyDir } = require('fs-extra');
|
||||
const { dtsBundler } = require('@cocos/ccbuild');
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
require('./ensure-pal.cjs')();
|
||||
const { join } = require('path');
|
||||
const { ensureDir, emptyDir } = require('fs-extra');
|
||||
const { magenta } = require('chalk');
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
require('./ensure-pal.cjs')();
|
||||
const { join } = require('path');
|
||||
const { ensureDir, emptyDir } = require('fs-extra');
|
||||
const { magenta } = require('chalk');
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
require('./ensure-pal.cjs')();
|
||||
const ccbuild = require('@cocos/ccbuild');
|
||||
const ps = require('path');
|
||||
const fs = require('fs-extra');
|
||||
|
||||
@@ -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;
|
||||
@@ -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
@@ -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}`);
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
@@ -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]);
|
||||
});
|
||||
@@ -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();
|
||||
});
|
||||
@@ -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();
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -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();
|
||||
});
|
||||
});
|
||||
@@ -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);
|
||||
});
|
||||
|
||||
});
|
||||
@@ -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();
|
||||
});
|
||||
});
|
||||
@@ -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();
|
||||
});
|
||||
});
|
||||
@@ -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();
|
||||
});
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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();
|
||||
};
|
||||
@@ -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, []);
|
||||
});
|
||||
@@ -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);
|
||||
});
|
||||
@@ -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(); }
|
||||
});
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user