Node.js v18.7.0 文档


目录

worker_threads 工作线程#

中英对照

node:worker_threads 模块允许使用并行执行 JavaScript 的线程。 要访问它:



worker.getEnvironmentData(key)#

中英对照

    在工作线程中,worker.getEnvironmentData() 返回传给衍生线程的 worker.setEnvironmentData() 的数据的克隆。 每个新的 Worker 都会自动接收到自己的环境数据的副本。

    
    

    worker.isMainThread#

    中英对照

      如果此代码不在 Worker 线程内运行,则为 true

      
      

      worker.markAsUntransferable(object)#

      中英对照

      将对象标记为不可传输。 如果 object 出现在 port.postMessage() 调用的传输列表中,则忽略它。

      
      

      worker.moveMessagePortToContext(port, contextifiedSandbox)#

      中英对照

        MessagePort 传输到不同的 vm 上下文 原始的 port 对象变得不可用,返回的 MessagePort 实例取而代之。

        worker.parentPort#

        中英对照

          如果此线程是 Worker,则这是允许与父线程通信的 MessagePort。 使用 parentPort.postMessage() 发送的消息在使用 worker.on('message') 的父线程中可用,使用 worker.postMessage() 从父线程发送的消息在使用 parentPort.on('message') 的该线程中可用。

          
          

          worker.receiveMessageOnPort(port)#

          中英对照

            从给定的 MessagePort 接收消息。 如果没有消息可用,则返回 undefined,否则返回具有单个 message 属性的对象,该对象包含消息负载,对应于 MessagePort 队列中最旧的消息。

            
            

            worker.resourceLimits#

            中英对照

              在这个工作线程中提供了一组 JS 引擎资源约束。 如果将 resourceLimits 选项传给 Worker 构造函数,则这与其值匹配。

              worker.SHARE_ENV#

              中英对照

                可以作为 Worker 构造函数的 env 选项传入的特殊值,表示当前线程和工作线程应该共享对同一组环境变量的读写访问。

                
                

                worker.setEnvironmentData(key[, value])#

                中英对照

                  worker.setEnvironmentData() API 设置当前线程中 worker.getEnvironmentData() 的内容以及从当前上下文产生的所有新 Worker 实例。

                  worker.threadId#

                  中英对照

                    当前线程的整数标识符。 在对应的工作线程对象上(如果有的话),可以作为 worker.threadId 使用。 此值对于单个进程中的每个 Worker 实例都是唯一的。

                    worker.workerData#

                    中英对照

                    任意的 JavaScript 值,其中包含传给该线程的 Worker 构造函数的数据的克隆。

                    
                    

                    继承自 EventTarget 的 BroadcastChannel 类#

                    中英对照

                    BroadcastChannel 的实例允许与绑定到相同通道名称的所有其他 BroadcastChannel 实例进行异步的一对多通信。

                    
                    

                    new BroadcastChannel(name)#

                    中英对照

                      broadcastChannel.close()#

                      中英对照

                      关闭 BroadcastChannel 连接。

                      broadcastChannel.onmessage#

                      中英对照

                        broadcastChannel.onmessageerror#

                        中英对照

                          broadcastChannel.postMessage(message)#

                          中英对照

                            broadcastChannel.ref()#

                            中英对照

                            unref() 的相反。 如果它是唯一剩下的活动句柄(默认行为),则在先前 unref() 的 BroadcastChannel 上调用 ref() 不会让程序退出。 如果端口是 ref() 的,则再次调用 ref() 没有效果。

                            broadcastChannel.unref()#

                            中英对照

                            如果这是事件系统中唯一的活动句柄,则在广播通道上调用 unref() 允许线程退出。 如果广播通道已经 unref(),则再次调用 unref() 无效。

                            MessageChannel#

                            中英对照

                            worker.MessageChannel 类的实例代表异步的双向通信通道。 MessageChannel 没有自己的方法。 new MessageChannel() 产生具有 port1port2 属性的对象,其引用链接的 MessagePort 实例。

                            
                            

                            MessagePort#

                            中英对照

                              worker.MessagePort 类的实例代表异步双向通信通道的一端。 它可以用来在不同的 Worker 之间传输结构化的数据、内存区域和其他 MessagePort

                              'close' 事件#

                              中英对照

                              一旦通道的任一侧断开连接,则会触发 'close' 事件。

                              
                              

                              'message' 事件#

                              中英对照

                                为任何传入消息触发 'message' 事件,其中包含 port.postMessage() 的克隆输入。

                                'messageerror' 事件#

                                中英对照

                                  当反序列化消息失败时,则会触发 'messageerror' 事件。

                                  port.close()#

                                  中英对照

                                  禁止在连接的任一端进一步发送消息。 当此 MessagePort 上不会发生进一步的通信时,可以调用此方法。

                                  port.postMessage(value[, transferList])#

                                  中英对照

                                    向该通道的接收端发送 JavaScript 值。 value 的传输方式与 HTML 结构化克隆算法兼容。

                                      
                                      

                                      
                                      

                                      传输 TypedArray 和 Buffer 时的注意事项#

                                      中英对照

                                      所有 TypedArrayBuffer 实例都是对底层 ArrayBuffer 的视图。 也就是说,实际存储原始数据的是 ArrayBuffer,而 TypedArrayBuffer 对象提供了查看和操作数据的方式。 在同一个 ArrayBuffer 实例上创建多个视图是可能且常见的。 使用传输列表传输 ArrayBuffer 时必须非常小心,因为这样做会导致共享同一个 ArrayBuffer 的所有 TypedArrayBuffer 实例变得不可用。

                                      
                                      

                                      使用原型、类和访问器克隆对象时的注意事项#

                                      中英对照

                                      因为对象克隆使用 HTML 结构化克隆算法,不可枚举的属性、属性访问器和对象原型不会被保留。 特别是,Buffer 对象将在接收方读取为普通 Uint8Array,并且 JavaScript 类的实例将被克隆为普通 JavaScript 对象。

                                      
                                      

                                      
                                      

                                      port.hasRef()#

                                      中英对照

                                        如果为 true,则 MessagePort 对象将使 Node.js 事件循环保持活动状态。

                                        port.ref()#

                                        中英对照

                                        unref() 的相反。 如果它是唯一剩下的活动句柄(默认行为),则在以前的 unref() 端口上调用 ref() 不会让程序退出。 如果端口是 ref() 的,则再次调用 ref() 没有效果。

                                        port.start()#

                                        中英对照

                                        开始在此 MessagePort 上接收消息。 当将此端口用作事件触发器时,一旦绑定了 'message' 监听器,则会自动调用它

                                        port.unref()#

                                        中英对照

                                        如果这是事件系统中唯一的活动句柄,则在端口上调用 unref() 允许线程退出。 如果端口已经 unref(),则再次调用 unref() 无效。

                                        Worker#

                                        中英对照

                                          Worker 类代表独立的 JavaScript 执行线程。 大多数 Node.js API 都可以在其中使用。

                                            
                                            

                                            new Worker(filename[, options])#

                                            中英对照

                                              'error' 事件#

                                              中英对照

                                                如果工作线程抛出未捕获的异常,则会触发 'error' 事件。 在这种情况下,工作线程被终止。

                                                'exit' 事件#

                                                中英对照

                                                  一旦工作线程停止,则会触发 'exit' 事件。 如果工作线程是通过调用 process.exit() 退出的,则 exitCode 参数就是传入的退出码。 如果工作线程被终止,则 exitCode 参数为 1

                                                  'message' 事件#

                                                  中英对照

                                                    当工作线程调用 require('node:worker_threads').parentPort.postMessage() 时,则会触发 'message' 事件。 详情请见 port.on('message') 事件。

                                                    'messageerror' 事件#

                                                    中英对照

                                                      当反序列化消息失败时,则会触发 'messageerror' 事件。

                                                      'online' 事件#

                                                      中英对照

                                                      当工作线程开始执行 JavaScript 代码时,则会触发 'online' 事件。

                                                      worker.getHeapSnapshot()#

                                                      中英对照

                                                        返回工作线程当前状态的 V8 快照的可读流。 有关详细信息,请参阅 v8.getHeapSnapshot()

                                                        worker.performance#

                                                        中英对照

                                                        可用于从工作线程实例查询性能信息的对象。 类似于perf_hooks.performance

                                                        performance.eventLoopUtilization([utilization1[, utilization2]])#

                                                        中英对照

                                                          perf_hooks eventLoopUtilization() 相同的调用,除了返回工作线程实例的值。

                                                          
                                                          

                                                          worker.postMessage(value[, transferList])#

                                                          中英对照

                                                            向通过 require('node:worker_threads').parentPort.on('message') 接收到的工作线程发送消息。 有关详细信息,请参阅 port.postMessage()

                                                            worker.ref()#

                                                            中英对照

                                                            unref() 相反,如果它是唯一剩下的活动句柄(默认行为),则在以前的 unref() 的工作线程上调用 ref() 不会让程序退出。 如果工作线程是 ref() 的,则再次调用 ref() 没有效果。

                                                            worker.resourceLimits#

                                                            中英对照

                                                              为此工作线程提供了一组 JS 引擎资源约束。 如果将 resourceLimits 选项传给 Worker 构造函数,则这与其值匹配。

                                                              worker.stderr#

                                                              中英对照

                                                                这是包含工作线程内写入 process.stderr 的数据的可读流。 如果 stderr: true 没有传给 Worker 构造函数,则数据将通过管道传输到父线程的 process.stderr 流。

                                                                worker.stdin#

                                                                中英对照

                                                                  如果将 stdin: true 传给 Worker 构造函数,则这是可写流。 写入此流的数据将在工作线程中作为 process.stdin 可用。

                                                                  worker.stdout#

                                                                  中英对照

                                                                    这是包含工作线程内写入 process.stdout 的数据的可读流。 如果 stdout: true 没有传给 Worker 构造函数,则数据将通过管道传输到父线程的 process.stdout 流。

                                                                    worker.terminate()#

                                                                    中英对照

                                                                      尽快停止工作线程中的所有 JavaScript 执行。 返回在触发 'exit' 事件时履行退出码的 Promise。

                                                                      worker.threadId#

                                                                      中英对照

                                                                        引用线程的整数标识符。 在工作线程内部,它作为 require('node:worker_threads').threadId 可用。 此值对于单个进程中的每个 Worker 实例都是唯一的。

                                                                        worker.unref()#

                                                                        中英对照

                                                                        如果这是事件系统中唯一的活动句柄,则在工作线程上调用 unref() 允许线程退出。 如果工作线程已经 unref(),则再次调用 unref() 无效。

                                                                        注意事项#

                                                                        标准输入输出的同步阻塞#

                                                                        中英对照

                                                                        Worker 利用通过 <MessagePort> 传入的消息来实现与 stdio 的交互。 这意味着来自 Workerstdio 输出可能会被接收端的同步代码阻塞,这会阻塞 Node.js 事件循环。

                                                                        
                                                                        

                                                                        从预加载脚本启动工作线程#

                                                                        中英对照

                                                                        从预加载脚本(使用 -r 命令行标志加载和运行的脚本)启动工作线程时要小心。 除非显式设置了 execArgv 选项,否则新的工作线程会自动从正在运行的进程继承命令行标志,并将预加载与主线程相同的预加载脚本。 如果预加载脚本无条件地启动工作线程,则每个衍生的线程都会衍生另一个直到应用程序崩溃。

                                                                        返回顶部