- assert断言
- async_hooks异步钩子
- async_hooks/context异步上下文
- buffer缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process子进程
- cluster集群
- CLI命令行
- console控制台
- Corepack核心包
- crypto加密
- crypto/webcrypto网络加密
- debugger调试器
- deprecation弃用
- dgram数据报
- diagnostics_channel诊断通道
- dns域名服务器
- domain域
- Error错误
- events事件触发器
- fs文件系统
- global全局变量
- http超文本传输协议
- http2超文本传输协议2.0
- https安全超文本传输协议
- inspector检查器
- Intl国际化
- module模块
- module/cjsCommonJS模块
- module/esmECMAScript模块
- module/package包模块
- net网络
- os操作系统
- path路径
- perf_hooks性能钩子
- policy安全策略
- process进程
- punycode域名代码
- querystring查询字符串
- readline逐行读取
- repl交互式解释器
- report诊断报告
- stream流
- stream/web网络流
- string_decoder字符串解码器
- test测试
- timers定时器
- tls安全传输层
- trace_events跟踪事件
- tty终端
- url网址
- util实用工具
- v8引擎
- vm虚拟机
- wasi网络汇编系统接口
- worker_threads工作线程
- zlib压缩
Node.js v18.7.0 文档
- Node.js 18.7.0
- ► 目录
-
►
索引
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS模块
- module/esm ECMAScript模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- policy 安全策略
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- ► 其他版本
- 文档搜索
- 会员登录
目录
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 查询。
异步上下文的示例#
以下是一个示例,其中包含有关 before
和 after
调用之间对 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
。