Files
cocos4/cocos/misc/worker.ts
T
llsansun 2157fd176d 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>
2026-10-29 16:35:14 +08:00

414 lines
23 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
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);
}