Node.js v18.7.0 文档


目录

async_hooks 异步钩子#

中英对照

node:async_hooks模块提供了 API 来跟踪异步的资源。 可以使用以下方式访问它:


术语#

中英对照

异步的资源表示具有关联回调的对象。 此回调可能会被多次调用,比如 net.createServer() 中的 'connection' 事件、或者像 fs.open() 一样只调用一次。 资源也可以在调用回调之前关闭。 AsyncHook 没有明确区分这些不同的情况,而是将它们表示为抽象的概念,即资源。

概述#

中英对照

以下是公共 API 的简单概述。


async_hooks.createHook(callbacks)#

中英对照

    为每个异步操作的不同生命周期事件注册要调用的函数。

    
    

    
    

    异常处理#

    中英对照

    如果任何 AsyncHook 回调抛出,则应用程序将打印堆栈跟踪并退出。 退出路径确实遵循未捕获异常的路径,但所有 'uncaughtException' 监听器都被删除,从而强制进程退出。 除非应用程序使用 --abort-on-uncaught-exception 运行,否则仍将调用 'exit' 回调,在这种情况下,将打印堆栈跟踪并且应用程序退出,留下核心文件。

    在 AsyncHook 回调中打印#

    中英对照

    因为打印到控制台是异步的操作,所以 console.log() 会导致 AsyncHook 回调被调用。 在 AsyncHook 回调函数中使用 console.log() 或类似的异步操作将导致无限递归。 当调试时,一个简单的解决方案是使用同步的日志记录操作,例如 fs.writeFileSync(file, msg, flag)。 这将打印到文件并且不会递归地调用 AsyncHook,因为它是同步的。

    
    

    AsyncHook#

    中英对照

    AsyncHook 类公开了一个用于跟踪异步操作的生命周期事件的接口。

    asyncHook.enable()#

    中英对照

      启用给定 AsyncHook 实例的回调。 如果没有提供回调,则启用是无操作的。

      
      

      asyncHook.disable()#

      中英对照

        从要执行的 AsyncHook 回调全局池中禁用给定 AsyncHook 实例的回调。 一旦一个钩子被禁用,则它在启用之前不会被再次调用。

        钩子回调#

        中英对照

        异步事件生命周期中的关键事件分为四个区域:实例化、回调调用前后、实例销毁时。

        init(asyncId, type, triggerAsyncId, resource)#

        中英对照

          当构造有可能触发异步事件的类时调用。 这并不意味着实例必须在调用 destroy 之前调用 before/after,只是存在这种可能性。

          
          

          type#

          中英对照

          type 是字符串,标识导致调用 init 的资源类型。 一般会对应资源的构造函数名。

          
          

          triggerAsyncId#

          中英对照

          triggerAsyncId 是导致(或“触发”)新资源初始化并导致 init 调用的资源的 asyncId。 这与 async_hooks.executionAsyncId() 不同,async_hooks.executionAsyncId() 只显示何时创建资源,而 triggerAsyncId 显示创建资源的原因。

          
          

          
          

          resource#

          中英对照

          resource 是一个对象,表示已初始化的实际异步资源。 这可能包含有用的信息,这些信息可能会根据 type 的值而有所不同。 例如,对于 GETADDRINFOREQWRAP 资源类型,resource 提供了在 net.Server.listen() 中查找主机 IP 地址时使用的主机名。 不支持访问此信息的 API,但使用 Embedder API,用户可以提供和记录自己的资源对象。 例如,这样的资源对象可能包含正在执行的 SQL 查询。

          异步上下文的示例#

          中英对照

          以下是一个示例,其中包含有关 beforeafter 调用之间对 init 的调用的附加信息,特别是对 listen() 的回调将是什么样子。 输出格式稍微复杂一点,使调用上下文更容易看到。

          
          

          
          

          
          

          
          
          before(asyncId)#

          中英对照

            当异步操作启动(如 TCP 服务器接收新连接)或完成(如将数据写入磁盘)时,会调用回调通知用户。 before 回调在所述回调执行之前被调用。 asyncId 是分配给即将执行回调的资源的唯一标识符。

            after(asyncId)#

            中英对照

              before 中指定的回调完成后立即调用。

              destroy(asyncId)#

              中英对照

                asyncId 对应的资源销毁后调用。 它也从嵌入器 API emitDestroy() 异步调用。

                promiseResolve(asyncId)#

                中英对照

                  当调用传给 Promise 构造函数的 resolve 函数时调用(直接或通过其他解决 promise 的方法)。

                  
                  

                  
                  

                  async_hooks.executionAsyncResource()#

                  中英对照

                    executionAsyncResource() 返回的资源对象通常是带有未记录 API 的内部 Node.js 句柄对象。 在对象上使用任何函数或属性都可能使您的应用程序崩溃,应该避免。

                    
                    

                    
                    

                    async_hooks.executionAsyncId()#

                    中英对照

                      
                      

                      executionAsyncId() 返回的 ID 与执行时机有关,与因果无关(被 triggerAsyncId() 涵盖):

                      
                      

                      async_hooks.triggerAsyncId()#

                      中英对照

                        
                        

                        默认情况下,promise 上下文可能无法获得有效的 triggerAsyncId。 请参阅 promise 执行跟踪部分。

                        async_hooks.asyncWrapProviders#

                        中英对照

                          此特性禁止使用 process.binding('async_wrap').Providers。 参阅:DEP0111

                          Promise 执行跟踪#

                          中英对照

                          默认情况下,由于 V8 提供的 promise 自省 API 相对昂贵,因此不会为 promise 执行分配 asyncId。 这意味着默认情况下,使用 promise 或 async/await 的程序将无法正确执行并触发 promise 回调上下文的 id。

                          
                          

                          
                          

                          JavaScript 嵌入的接口#

                          中英对照

                          处理自己的异步资源执行 I/O、连接池或管理回调队列等任务的库开发者可以使用 AsyncResource JavaScript API 以便调用所有适当的回调。

                          AsyncResource#

                          中英对照

                          该类的文档已移至 AsyncResource

                          AsyncLocalStorage#

                          中英对照

                          该类的文档已移至 AsyncLocalStorage

                          返回顶部