Napa.js Zone 多线程运行时 API 完全指南：从 Broadcast/Execute 到调度器实现

语言运行时并发编程【免费下载链接】napajsNapa.js: a multi-threaded JavaScript runtime项目地址https://gitcode.com/gh_mirrors/na/napajs点击查看免费下载导读zone是 Napa.jsREADME 所述的多线程 JavaScript 运行时对外暴露多线程能力的核心命名空间。本文以 docs/api/zone.md 为骨架完整讲解 Zone 的两种类型Napa zone 与 Node zone、广播broadcast与执行execute两类操作、全套 API 签名与参数语义并结合仓库源码lib/zone/zone.ts、lib/zone/zone-impl.ts、lib/zone.ts、src/zone/scheduler.h与测试test/zone-test.ts深入剖析底层实现。读完本文你将掌握 Zone 的创建、查询、广播、执行、超时控制与结果反序列化的完整用法并理解同构 worker 调度器这一多线程模型的真实工作原理。Zone 是什么多线程 JavaScript 世界的关键概念Zone 是 Napa.js 的核心概念它在 JavaScript 世界中暴露多线程能力本质上是为特定任务服务的、一组对称 worker 的逻辑分组。需要特别澄清的是Napa.js 的zone与以下概念不是同一回事Dart 语言中用于异步调用的上下文对象zoneAngular 的zone.jsTC39 的 zones 提案。Napa.js 的 Zone 是物理线程V8 isolate的运行时分组而不是异步执行上下文。Multiple workers vs. Multiple zones多 worker 与多 zone 的区别Zone 由一个或多个 JavaScript 线程组成每个线程被称为worker。同一 zone 内的 worker 是对称的symmetric这意味着在 zone 内任意一个 worker 上执行代码应返回相同的结果从长期运行的角度看每个 worker 的内部状态应保持一致。因此当你在 Zone API 上编程时最佳实践是确保 zone 内所有 worker 彼此对称即不应假设某个 worker 会维护它自己的独立状态。这一对称性约束在 lib/zone/zone.ts 的接口注释中被明确强调是整个 Zone 模型设计的基石。多个 zone 可以在同一进程中共存每个 zone 可以加载不同的代码承载不同的状态应用不同的策略如堆大小 heap size 等。多 zone 的目的是让复杂任务拥有多种角色每个角色只为自身用途加载最小资源。例如一个 zone 负责计算密集型任务另一个 zone 负责 I/O 密集的 Node.js 操作互不干扰。Zone 类型Napa.js 提供两种类型的 zone类型说明能力Napa zone由 Napa.js 管理的 JavaScript workerV8 isolate组成的 zone可以有多个每个可包含多个 workerworker 支持部分 Node.js APINode zone一个虚拟 zone暴露 Node.js 事件循环可访问完整的 Node.js 能力其中 Node zone 的 id 固定为node可以把它理解为当前 Node.js 进程自身在多线程世界中的代言人——所有 Napa worker 都可以通过napa.zone.get(node)把任务交回 Node.js 主线程执行。Zone 操作Broadcast 与 Execute为强化 zone 内 worker 的对称性Napa.js 设计了两种操作Broadcast广播在所有 worker 上运行会改变 worker 状态的代码返回一个表示操作挂起的 Promise。通过这个 Promise 只能知道操作成功或失败。通常用broadcast来引导bootstrap应用、预缓存对象、或修改应用设置。同时提供同步版本broadcastSync。Execute执行在任意一个 worker 上运行不会改变 worker 状态的代码返回一个携带结果的 Promise。Execute 被设计用于做真正的活实际计算任务。调度语义zone 操作基于先到先服务first-come-first-serve原则但broadcast的优先级高于execute。这一点在 src/zone/scheduler.h 中有对应实现——ScheduleOnWorker与ScheduleOnAllWorkers的注释明确说明它们会立即入队任务因此优先级高于由Schedule()派发的任务即广播/指定 worker 的任务优先于普通执行任务。获取与创建 Zonecreate / get / current / nodezone命名空间的入口实现在 lib/zone.ts包括四个 APIcreate、get、current、node。create(id: string, settings: ZoneSettings): Zone创建一个以字符串 id 标识的 Napa zone。如果该 id 对应的 zone 已存在将抛出错误。可通过settings指定创建参数详见后文ZoneSettings。示例 1创建 id 为zone1的 zone使用默认ZoneSettingsvar napa require(napajs); var zone1 napa.zone.create(zone1);示例 2创建 id 为zone2的 zone指定 1 个 workervar zone2 napa.zone.create(zone2, { workers: 1 });从源码看create在 lib/zone.ts 中的实现会先调用platform.initialize()完成运行时初始化再调用 native 绑定binding.createZone(id, settings)创建底层 zoneexport function create(id: string, settings: zone.ZoneSettings zone.DEFAULT_SETTINGS) : zone.Zone { platform.initialize(); return new impl.ZoneImpl(binding.createZone(id, settings)); }测试用例 test/zone-test.ts 验证了create的行为默认设置创建成功、id 正确返回重复创建相同 id 会抛出异常Node 侧抛错、Napa worker 侧 Promise reject。get(id: string): Zone通过 id 获取 zone 的引用。如果 zone 不存在将抛出错误。var zone napa.zone.get(zone1);底层实现同样调用binding.getZone(id)并包装为ZoneImpl。测试覆盖了 get 成功node zone、napa zone、跨 worker 获取与失败id 不存在两种场景见 test/zone-test.ts。current: Zone返回当前正在运行的 isolate 所属的 zone的引用。如果在 Node.js 环境下访问返回 node zone。var zone napa.zone.current;在 lib/zone.ts 中current被实现为 getter 属性调用binding.getCurrentZone()。测试验证了在 Node 主线程napa.zone.current.id node在 Napa worker 内通过./napa-zone/test模块的getCurrentZone函数执行时返回该 worker 所属的napa-zone1见 test/zone-test.ts 与 test/napa-zone/test.ts。node: Zone返回 Node zone 的引用等价于napa.zone.get(node)var zone napa.zone.node;同样实现为 getter内部调用binding.getZone(node)lib/zone.ts。接口ZoneSettings创建 zone 的参数ZoneSettings是创建 zone 时指定的设置项若未指定将使用DEFAULT_SETTINGS。定义见 lib/zone/zone.ts。settings.workers: numberzone 内的 worker 数量。该参数直接决定底层创建的 V8 isolate 线程数。在 src/zone/scheduler.h 中SchedulerImpl构造函数根据settings.workers创建对应数量的 worker先_workers.reserve(settings.workers)预留空间再循环_workers.emplace_back(...)并逐一Start()。每个 worker 对应一个独立的 V8 isolate 线程。对象DEFAULT_SETTINGS创建 zone 时的默认设置lib/zone/zone.ts{ workers: 2 }即默认创建 2 个 worker。这也是 test/zone-test.ts 中napa.zone.create(napa-zone1)不传 settings 即可正常工作的原因。接口Zone核心操作对象Zone 是 Napa.js 中执行 JavaScript 和应用策略的基本概念。开发者通过 Zone API 可以在所有 worker 上广播 JavaScript 代码或在其中一个 worker 上执行函数。前面已述编程时最佳实践是保证 zone 内 worker 对称、不依赖单个 worker 的私有状态。Zone 的两大类 API 是broadcast与execute均为异步操作并有若干输入形式变体。完整接口签名定义于 lib/zone/zone.ts。zone.id: string获取 zone 的 id。在 lib/zone/zone-impl.ts 中通过this._nativeZone.getId()实现。此外ZoneImpl还提供toJSON()返回{ id, type }其中type在 id 为node时为node否则为napa。zone.broadcast(code: string): Promisevoid将一段 JavaScript 代码字符串异步广播到所有 worker返回Promisevoid。如果任一 worker 执行代码失败Promise 将被拒绝并携带错误信息。var napa require(napajs); var zone napa.zone.get(zone1); zone.broadcast(var state 0;) .then(() { console.log(broadcast succeeded.); }) .catch((error) { console.log(broadcast failed.) });实现细节在 lib/zone/zone-impl.ts 中字符串形式的广播被包装为module: 、function: eval的FunctionSpec代码通过JSON.stringify序列化后作为参数传入最终由 native 层在所有 worker 上eval执行。广播失败时会 rejectresult.errorMessage。测试用例覆盖了合法代码、非法代码var state() 0;、运行时抛错throw new Error();等场景见 test/zone-test.ts。zone.broadcastSync(code: string): void将一段 JavaScript 代码字符串同步广播到所有 worker。如果任一 worker 执行失败将抛出异常并携带错误信息。重要提醒不允许在自身所在的 zone 上调用broadcastSync否则会导致死锁deadlock。这一点在文档中明确标注测试 test/zone-test.ts 也验证了在当前 zone 上执行broadcastSync会失败。var napa require(napajs); var zone napa.zone.get(zone1); try { zone.broadcastSync(var state 0;); console.log(broadcast succeeded.); } catch (error) { console.log(broadcast failed.) }实现上lib/zone/zone-impl.ts调用_nativeZone.broadcastSync(spec)若result.code ! 0则throw new Error(result.errorMessage)。zone.broadcast(function: (...args: any[]) void | Promisevoid, args?: any[]): Promisevoid将一个匿名函数及其参数异步广播到所有 worker返回Promisevoid。任一 worker 执行失败则 Promise 被拒绝。注意事项Remarks如果函数返回 Promise 对象其状态会被采纳为broadcast返回值即广播操作会等待该 Promise 决议函数对象不能访问闭包中的变量除非函数对象带有origin属性否则会使用当前文件作为origin用于设置目标侧的__filename和__dirname参见 transporting functions广播中不可用 TransportContext。所有依赖 TransportContext 的类型如 ShareableWrap、Transportable都不能出现在参数列表中。zone.broadcast((state) { require(some-module).setModuleState(state) }, [{field1: 1}]) .then(() { console.log(broadcast succeeded.); }) .catch((error) { console.log(broadcast failed:, error) });实现细节在 lib/zone/zone-impl.ts 中函数形式的广播会若arg1.origin null通过v8.currentStack(3)[2].getFileName()获取调用者文件路径并赋给arg1.origin将函数通过transport.saveFunction(arg1)保存并以其为function字段module固定为__function参数用transport.marshall(arg, null)序列化注意此处 context 为null正对应广播中无 TransportContext的限制。测试 test/zone-test.ts 验证了匿名函数广播node zone 与 napa zone 互相广播以及含闭包的匿名函数广播会失败如捕获zone变量这与函数对象不能访问闭包变量的约束一致。zone.broadcastSync(function: (...args: any[]) void | Promisevoid, args?: any[]): void将匿名函数及其参数同步广播到所有 worker。任一 worker 执行失败则抛出异常。注意事项不允许在自身所在 zone 上调用broadcastSync否则死锁如果函数返回 Promise 对象其状态会被采纳broadcastSync将等到该 Promise resolve 或 reject 之后才返回函数对象不能访问闭包中的变量除非函数对象带origin属性否则使用当前文件作为origin设置__filename和__dirname参见 transporting functions广播中不可用 TransportContext依赖 TransportContext 的类型如 ShareableWrap、Transportable不能出现在参数列表中。try { zone.broadcastSync((state) { require(some-module).setModuleState(state) }, [{field1: 1}]); console.log(broadcast succeeded.); } catch (error) { console.log(broadcast failed:, error) }zone.execute(moduleName: string, functionName: string, args?: any[], options?: CallOptions): Promiseany通过模块名 函数名在任意一个 worker 上异步执行函数。参数可以是任意可传输类型transportable types的 JavaScript 值。返回Result的 Promise。如果发生错误——无论是错误代码、用户异常还是超时——Promise 都会被拒绝。示例执行模块foo中的函数bar参数为[1, hello, { field1: 1 }]并应用 300ms 超时zone.execute( foo, bar, [1, hello, {field1: 1}], { timeout: 300 }) .then((result) { console.log(execute succeeded:, result.value); }) .catch((error) { console.log(execute failed:, error); });实现细节在 lib/zone/zone-impl.ts 中当第一个参数是字符串时如果模块名是相对路径会通过调用方堆栈v8.currentStack(3)[2].getFileName()解析为绝对路径然后为本次调用创建一个非持有non-owning的 TransportContext参数通过transport.marshall(arg, transportContext)序列化从而支持传输可传输类型如napa.memory.crtAllocator这类 addon 对象。测试 test/zone-test.ts 覆盖了多种模块/函数名执行场景包括空模块名执行全局函数、带命名空间的函数名ns1.ns2.foo、模块导出函数、模块不存在、函数不存在等。执行模块即函数function-as-module的场景也有对应用例见 test/napa-zone/function-as-module.ts。zone.execute(function: (...args: any[]) any, args?: any[], options?: CallOptions): Promiseany在任意一个 worker 上异步执行函数对象。参数可以是任意可传输类型。返回Result的 Promise出错代码错误、用户异常、超时时被拒绝。注意事项如果函数返回 Promise 对象其状态会被采纳函数对象不能访问闭包中的变量除非函数对象带origin属性否则使用当前文件作为origin用于设置目标侧__filename和__dirname参见 transporting functions。示例zone.execute((a: number, b: string, c: object) { return a b JSON.stringify(c); }, [1, hello, {field1: 1}]) .then((result) { console.log(execute succeeded:, result.value); }) .catch((error) { console.log(execute failed:, error); });输出execute succeeded: 1hello{field1:1}另一个示例演示执行匿名函数时访问__filename// File: /usr/file1.js zone.execute(() { console.log(__filename);});输出/usr/file1.js实现细节在 lib/zone/zone-impl.ts 中函数对象形式的 execute 会为函数补充origin来自调用者文件通过transport.saveFunction(arg1)保存函数并以module: __function、保存得到的函数 id 作为function字段构造FunctionSpec。这正对应 transport.md 中描述的将函数定义 marshall 进 store在目标线程上从其定义生成新函数的机制也解释了闭包变量为何无法传输——闭包无法被序列化调用时会出现变量 undefined的运行时错误。测试 test/zone-test.ts 验证了在 node zone 上执行含闭包的匿名函数可以成功闭包就在当前环境而跨 napa zone 执行含闭包的匿名函数会失败。传输可传输参数的 execute测试 test/zone-test.ts 验证了execute可传输napa.memory.crtAllocator这类 addon 对象作为参数和返回值目标 worker 通过assert.deepEqual(allocator.handle, ...)确认收到的是同一个共享对象的句柄——这正是 TransportContext 与 shareable wrap 机制的体现。接口CallOptions调用选项zone.execute中调用函数时的选项接口lib/zone/zone.tsoptions.timeout: number超时时间单位为毫秒。默认值为 0表示不设超时。除文档提到的timeout外从源码看CallOptions还包含transport?: TransportOption字段默认TransportOption.AUTO表示参数传输模式AUTO由 napajs 自动完成 marshall/unmarshall最常用但对多次共享的对象可能不是性能最优MANUAL由用户手动控制。默认执行选项DEFAULT_CALL_OPTIONS定义于 lib/zone/zone.tsexport let DEFAULT_CALL_OPTIONS: CallOptions { timeout: 0, transport: TransportOption.AUTO }测试 test/napa-zone/test.ts 的executeTestFunctionWithTimeout展示了超时选项的用法向 zone 执行waitMS函数并指定{timeout: timeoutInMS}若等待超过超时阈值则任务被判定失败对应文档所述超时到达则 Promise 被拒绝。接口Result访问执行结果Result接口用于访问execute的返回值定义见 lib/zone/zone.ts。其具体实现类在 lib/zone/zone-impl.ts构造时只保存payload与transportContextvalue是惰性求值的 getter——只有在第一次访问result.value时才执行 unmarshall。result.value: any从zone.execute/executeSync调用的函数返回的 JavaScript 值。Napa 会在不同 workerV8 isolate之间对可传输值进行 marshall/unmarshall。当第一次查询result.value时才会发生 unmarshalling。var value result.value;result.payload: string返回值序列化后的载荷JSON 格式。此字段适用于想把结果直接转交给下游调用者、而无需在本侧反序列化的用户。var payload result.payload;result.transportContext: transport.TransportContext将result.payload反序列化为result.value所需的 TransportContext。示例手动 marshall/unmarshall 以验证result.value与手动反序列化结果一致var napa require(napajs); var zone napa.zone.create(zone1); zone.execute(() { return 0; }, []) .then((result) { // Manually marshall. var transportContext result.transportContext; var value napa.transport.unmarshall(result.payload, result.transportContext); // result.value and manual unmarshall from payload are the same. assert.equal(value, result.value); });实现细节在 lib/zone/zone-impl.ts 中execute 的 native 回调会构造new Result(result.returnValue, transport.createTransportContext(true, result.contextHandle))——createTransportContext(true, ...)的true表示持有owning的 TransportContext使共享对象生命周期得以延续。这也解释了result.value惰性 unmarshall 的设计payload 与 context 均已就绪value 只在被访问时才解包从而避免不必要的反序列化开销。底层原理调度器如何支撑 Broadcast 与 ExecuteZone 的异步语义最终由 native 层的调度器实现。从 src/zone/scheduler.h 可以看出Schedule(task)将未指定 worker 的任务派发给空闲 worker若所有 worker 都忙则放入_nonScheduledTasks非调度队列等有 worker 空闲时IdleWorkerNotificationCallback再取出派发——这就是文档所述先到先服务FCFS的落地实现ScheduleOnWorker(workerId, task, phase)显式调度到指定 worker立即入队因此优先级高于普通Schedule派发的任务ScheduleOnAllWorkers(task)在所有 worker 上调度任务广播的底层载体同样立即入队、优先级更高——对应文档中broadcast 优先级高于 execute的调度语义调度器内部使用单线程的SimpleThreadPool同步任务排队与投递并用_beingScheduled原子计数与_nonScheduledTasks队列在析构时确保所有任务被排空。此外src/zone/async-runner.cpp 展示了异步任务的完成回投机制PostAsyncWork/DoAsyncWork在独立线程中执行asyncWork完成后通过context-zone-GetScheduler()-ScheduleOnWorker(context-workerId, asyncCompleteTask)把AsyncCompleteTask投递回原 worker 的 V8 事件循环从而让 Promise 正确 resolve。这套机制从源码层面印证了broadcast/execute返回 Promise 的异步闭环。实战案例用 Zone 并行估算圆周率仓库自带教程 examples/tutorial/estimate-pi-in-parallel/estimate-pi-in-parallel.js 是 Zone API 的典型应用——蒙特卡洛方法并行估算 πvar napa require(napajs); // 控制 napa worker 数量 const NUMBER_OF_WORKERS 4; // 创建包含 4 个 worker 的 napa zone var zone napa.zone.create(zone, { workers: NUMBER_OF_WORKERS }); function estimatePI(points) { var i points; var inside 0; while (i-- 0) { var x Math.random(); var y Math.random(); if ((x * x) (y * y) 1) { inside; } } return inside / points * 4; } function run(points, batches) { var start Date.now(); var promises []; for (var i 0; i batches; i) { promises[i] zone.execute(estimatePI, [points / batches]); } return Promise.all(promises).then(values { var aggregate 0; values.forEach(result aggregate result.value); printResult(points, batches, aggregate / batches, Date.now() - start); }); }该示例演示了核心用法模式用napa.zone.create(zone, { workers: NUMBER_OF_WORKERS })指定 worker 数量创建 zone将计算函数estimatePI通过zone.execute(estimatePI, [points / batches])分发到不同 worker 并行执行通过Promise.all聚合各 worker 返回的result.value求均值。注意estimatePI是无状态纯计算函数不改变 worker 状态、不依赖闭包变量完全符合execute的语义约束而函数跨线程传输依赖于 transport.md 描述的marshall 函数定义、目标线程重建函数机制。总结与最佳实践围绕 docs/api/zone.md 展开的 Zone API 可以总结为三条核心原则对称性第一zone 内 worker 必须保持状态对称broadcast用于修改状态引导、预缓存、改配置execute用于不改变状态的实际计算函数传输有边界广播/执行的匿名函数不能访问闭包变量但可通过origin属性获得正确的__filename/__dirname依赖 TransportContext 的类型不能用于 broadcast 参数结果按需解包Result.value惰性 unmarshallResult.payloadResult.transportContext则支持把序列化载荷直接转交下游。如果需要更深入地了解传输机制可传输类型白名单、TransportContext、函数传输细节请继续阅读 docs/api/transport.mdZone 的完整接口定义与默认参数可查看 lib/zone/zone.ts实现细节可查阅 lib/zone/zone-impl.ts 与 src/zone/scheduler.h全部行为均有 test/zone-test.ts 中的测试用例背书可作为自行验证的参考。赞分享语言运行时并发编程【免费下载链接】napajsNapa.js: a multi-threaded JavaScript runtime项目地址https://gitcode.com/gh_mirrors/na/napajs点击查看免费下载相关推荐Napa.js 多线程 JavaScript 运行时从 Zone 并发模型到跨线程通信的完整实践指南Napa.js 多线程 JavaScript 运行时从 Zone 并发模型到跨线程通信的完整实践指南 Napa.js 是一个构建在 V8 之上的多线程 Jav语言运行时并发编程Napa.js 并行估算圆周率基于 Zone 多线程的 Monte Carlo 实现深度解析Napa.js 并行估算圆周率基于 Zone 多线程的 Monte Carlo 实现深度解析 Napa.js 是一个构建在 V8 之上的多线程 JavaScr语言运行时并发编程Napa.js微软开源的多线程JavaScript运行时深度解析Napa.js微软开源的多线程JavaScript运行时深度解析 Napa.js是微软开发的一个基于V8引擎的多线程JavaScript运行时最初为Bing语言运行时并发编程上一篇Framework7单元测试指南确保组件质量的自动化测试策略下一篇10分钟搞定模板开发AI辅助mustache.js高效实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考