diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 04b0929f91baae..726f30c1cd83df 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -25,9 +25,7 @@ as the abstract concept that is a resource. If [`Worker`][]s are used, each thread has an independent `async_hooks` interface, and each thread will use a new set of async IDs. -## Public API - -### Overview +## Overview Following is a simple overview of the public API. @@ -79,7 +77,7 @@ function destroy(asyncId) { } function promiseResolve(asyncId) { } ``` -#### `async_hooks.createHook(callbacks)` +## `async_hooks.createHook(callbacks)` <!-- YAML added: v8.1.0 @@ -133,7 +131,7 @@ Because promises are asynchronous resources whose lifecycle is tracked via the async hooks mechanism, the `init()`, `before()`, `after()`, and `destroy()` callbacks *must not* be async functions that return promises. -##### Error handling +### Error handling If any `AsyncHook` callbacks throw, the application will print the stack trace and exit. The exit path does follow that of an uncaught exception, but @@ -150,7 +148,7 @@ future. This is subject to change in the future if a comprehensive analysis is performed to ensure an exception can follow the normal control flow without unintentional side effects. -##### Printing in AsyncHooks callbacks +### Printing in AsyncHooks callbacks Because printing to the console is an asynchronous operation, `console.log()` will cause the AsyncHooks callbacks to be called. Using `console.log()` or @@ -176,12 +174,12 @@ provided by AsyncHooks itself. The logging should then be skipped when it was the logging itself that caused AsyncHooks callback to call. By doing this the otherwise infinite recursion is broken. -### Class: `AsyncHook` +## Class: `AsyncHook` The class `AsyncHook` exposes an interface for tracking lifetime events of asynchronous operations. -#### `asyncHook.enable()` +### `asyncHook.enable()` * Returns: {AsyncHook} A reference to `asyncHook`. @@ -197,7 +195,7 @@ const async_hooks = require('async_hooks'); const hook = async_hooks.createHook(callbacks).enable(); ``` -#### `asyncHook.disable()` +### `asyncHook.disable()` * Returns: {AsyncHook} A reference to `asyncHook`. @@ -207,13 +205,13 @@ be called again until enabled. For API consistency `disable()` also returns the `AsyncHook` instance. -#### Hook callbacks +### Hook callbacks Key events in the lifetime of asynchronous events have been categorized into four areas: instantiation, before/after the callback is called, and when the instance is destroyed. -##### `init(asyncId, type, triggerAsyncId, resource)` +#### `init(asyncId, type, triggerAsyncId, resource)` * `asyncId` {number} A unique ID for the async resource. * `type` {string} The type of the async resource. @@ -240,7 +238,7 @@ clearTimeout(setTimeout(() => {}, 10)); Every new resource is assigned an ID that is unique within the scope of the current Node.js instance. -###### `type` +##### `type` The `type` is a string identifying the type of resource that caused `init` to be called. Generally, it will correspond to the name of the @@ -263,7 +261,7 @@ It is possible to have type name collisions. Embedders are encouraged to use unique prefixes, such as the npm package name, to prevent collisions when listening to the hooks. -###### `triggerAsyncId` +##### `triggerAsyncId` `triggerAsyncId` is the `asyncId` of the resource that caused (or "triggered") the new resource to initialize and that caused `init` to call. This is different @@ -302,7 +300,7 @@ that information, it would be impossible to link resources together in terms of what caused them to be created, so `triggerAsyncId` is given the task of propagating what resource is responsible for the new resource's existence. -###### `resource` +##### `resource` `resource` is an object that represents the actual async resource that has been initialized. This can contain useful information that can vary based on @@ -316,7 +314,7 @@ could contain the SQL query being executed. In some cases the resource object is reused for performance reasons, it is thus not safe to use it as a key in a `WeakMap` or add properties to it. -###### Asynchronous context example +##### Asynchronous context example The following is an example with additional information about the calls to `init` between the `before` and `after` calls, specifically what the @@ -415,7 +413,7 @@ TCPSERVERWRAP(5) Timeout(7) ``` -##### `before(asyncId)` +#### `before(asyncId)` * `asyncId` {number} @@ -432,7 +430,7 @@ asynchronous resources like a TCP server will typically call the `before` callback multiple times, while other operations like `fs.open()` will call it only once. -##### `after(asyncId)` +#### `after(asyncId)` * `asyncId` {number} @@ -442,7 +440,7 @@ If an uncaught exception occurs during execution of the callback, then `after` will run *after* the `'uncaughtException'` event is emitted or a `domain`'s handler runs. -##### `destroy(asyncId)` +#### `destroy(asyncId)` * `asyncId` {number} @@ -454,7 +452,7 @@ made to the `resource` object passed to `init` it is possible that `destroy` will never be called, causing a memory leak in the application. If the resource does not depend on garbage collection, then this will not be an issue. -##### `promiseResolve(asyncId)` +#### `promiseResolve(asyncId)` <!-- YAML added: v8.6.0 @@ -485,7 +483,7 @@ init for PROMISE with id 6, trigger id: 5 # the Promise returned by then() after 6 ``` -#### `async_hooks.executionAsyncResource()` +### `async_hooks.executionAsyncResource()` <!-- YAML added: @@ -543,7 +541,7 @@ const server = createServer((req, res) => { }).listen(3000); ``` -#### `async_hooks.executionAsyncId()` +### `async_hooks.executionAsyncId()` <!-- YAML added: v8.1.0 @@ -584,7 +582,7 @@ const server = net.createServer((conn) => { Promise contexts may not get precise `executionAsyncIds` by default. See the section on [promise execution tracking][]. -#### `async_hooks.triggerAsyncId()` +### `async_hooks.triggerAsyncId()` * Returns: {number} The ID of the resource responsible for calling the callback that is currently being executed.