@@ -25,9 +25,7 @@ as the abstract concept that is a resource. |
25 | 25 | If [`Worker`][]s are used, each thread has an independent `async_hooks` |
26 | 26 | interface, and each thread will use a new set of async IDs. |
27 | 27 |
|
28 | | -## Public API |
29 | | - |
30 | | -### Overview |
| 28 | +## Overview |
31 | 29 |
|
32 | 30 | Following is a simple overview of the public API. |
33 | 31 |
|
@@ -79,7 +77,7 @@ function destroy(asyncId) { } |
79 | 77 | function promiseResolve(asyncId) { } |
80 | 78 | ``` |
81 | 79 |
|
82 | | -#### `async_hooks.createHook(callbacks)` |
| 80 | +## `async_hooks.createHook(callbacks)` |
83 | 81 |
|
84 | 82 | <!-- YAML |
85 | 83 | added: v8.1.0 |
@@ -133,7 +131,7 @@ Because promises are asynchronous resources whose lifecycle is tracked |
133 | 131 | via the async hooks mechanism, the `init()`, `before()`, `after()`, and |
134 | 132 | `destroy()` callbacks *must not* be async functions that return promises. |
135 | 133 |
|
136 | | -##### Error handling |
| 134 | +### Error handling |
137 | 135 |
|
138 | 136 | If any `AsyncHook` callbacks throw, the application will print the stack trace |
139 | 137 | 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 |
150 | 148 | performed to ensure an exception can follow the normal control flow without |
151 | 149 | unintentional side effects. |
152 | 150 |
|
153 | | -##### Printing in AsyncHooks callbacks |
| 151 | +### Printing in AsyncHooks callbacks |
154 | 152 |
|
155 | 153 | Because printing to the console is an asynchronous operation, `console.log()` |
156 | 154 | 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 |
176 | 174 | it was the logging itself that caused AsyncHooks callback to call. By |
177 | 175 | doing this the otherwise infinite recursion is broken. |
178 | 176 |
|
179 | | -### Class: `AsyncHook` |
| 177 | +## Class: `AsyncHook` |
180 | 178 |
|
181 | 179 | The class `AsyncHook` exposes an interface for tracking lifetime events |
182 | 180 | of asynchronous operations. |
183 | 181 |
|
184 | | -#### `asyncHook.enable()` |
| 182 | +### `asyncHook.enable()` |
185 | 183 |
|
186 | 184 | * Returns: {AsyncHook} A reference to `asyncHook`. |
187 | 185 |
|
@@ -197,7 +195,7 @@ const async_hooks = require('async_hooks'); |
197 | 195 | const hook = async_hooks.createHook(callbacks).enable(); |
198 | 196 | ``` |
199 | 197 |
|
200 | | -#### `asyncHook.disable()` |
| 198 | +### `asyncHook.disable()` |
201 | 199 |
|
202 | 200 | * Returns: {AsyncHook} A reference to `asyncHook`. |
203 | 201 |
|
@@ -207,13 +205,13 @@ be called again until enabled. |
207 | 205 |
|
208 | 206 | For API consistency `disable()` also returns the `AsyncHook` instance. |
209 | 207 |
|
210 | | -#### Hook callbacks |
| 208 | +### Hook callbacks |
211 | 209 |
|
212 | 210 | Key events in the lifetime of asynchronous events have been categorized into |
213 | 211 | four areas: instantiation, before/after the callback is called, and when the |
214 | 212 | instance is destroyed. |
215 | 213 |
|
216 | | -##### `init(asyncId, type, triggerAsyncId, resource)` |
| 214 | +#### `init(asyncId, type, triggerAsyncId, resource)` |
217 | 215 |
|
218 | 216 | * `asyncId` {number} A unique ID for the async resource. |
219 | 217 | * `type` {string} The type of the async resource. |
@@ -240,7 +238,7 @@ clearTimeout(setTimeout(() => {}, 10)); |
240 | 238 | Every new resource is assigned an ID that is unique within the scope of the |
241 | 239 | current Node.js instance. |
242 | 240 |
|
243 | | -###### `type` |
| 241 | +##### `type` |
244 | 242 |
|
245 | 243 | The `type` is a string identifying the type of resource that caused |
246 | 244 | `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 |
263 | 261 | unique prefixes, such as the npm package name, to prevent collisions when |
264 | 262 | listening to the hooks. |
265 | 263 |
|
266 | | -###### `triggerAsyncId` |
| 264 | +##### `triggerAsyncId` |
267 | 265 |
|
268 | 266 | `triggerAsyncId` is the `asyncId` of the resource that caused (or "triggered") |
269 | 267 | 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 |
302 | 300 | terms of what caused them to be created, so `triggerAsyncId` is given the task |
303 | 301 | of propagating what resource is responsible for the new resource's existence. |
304 | 302 |
|
305 | | -###### `resource` |
| 303 | +##### `resource` |
306 | 304 |
|
307 | 305 | `resource` is an object that represents the actual async resource that has |
308 | 306 | been initialized. This can contain useful information that can vary based on |
@@ -316,7 +314,7 @@ could contain the SQL query being executed. |
316 | 314 | In some cases the resource object is reused for performance reasons, it is |
317 | 315 | thus not safe to use it as a key in a `WeakMap` or add properties to it. |
318 | 316 |
|
319 | | -###### Asynchronous context example |
| 317 | +##### Asynchronous context example |
320 | 318 |
|
321 | 319 | The following is an example with additional information about the calls to |
322 | 320 | `init` between the `before` and `after` calls, specifically what the |
@@ -415,7 +413,7 @@ TCPSERVERWRAP(5) |
415 | 413 | Timeout(7) |
416 | 414 | ``` |
417 | 415 |
|
418 | | -##### `before(asyncId)` |
| 416 | +#### `before(asyncId)` |
419 | 417 |
|
420 | 418 | * `asyncId` {number} |
421 | 419 |
|
@@ -432,7 +430,7 @@ asynchronous resources like a TCP server will typically call the `before` |
432 | 430 | callback multiple times, while other operations like `fs.open()` will call |
433 | 431 | it only once. |
434 | 432 |
|
435 | | -##### `after(asyncId)` |
| 433 | +#### `after(asyncId)` |
436 | 434 |
|
437 | 435 | * `asyncId` {number} |
438 | 436 |
|
@@ -442,7 +440,7 @@ If an uncaught exception occurs during execution of the callback, then `after` |
442 | 440 | will run *after* the `'uncaughtException'` event is emitted or a `domain`'s |
443 | 441 | handler runs. |
444 | 442 |
|
445 | | -##### `destroy(asyncId)` |
| 443 | +#### `destroy(asyncId)` |
446 | 444 |
|
447 | 445 | * `asyncId` {number} |
448 | 446 |
|
@@ -454,7 +452,7 @@ made to the `resource` object passed to `init` it is possible that `destroy` |
454 | 452 | will never be called, causing a memory leak in the application. If the resource |
455 | 453 | does not depend on garbage collection, then this will not be an issue. |
456 | 454 |
|
457 | | -##### `promiseResolve(asyncId)` |
| 455 | +#### `promiseResolve(asyncId)` |
458 | 456 |
|
459 | 457 | <!-- YAML |
460 | 458 | added: v8.6.0 |
@@ -485,7 +483,7 @@ init for PROMISE with id 6, trigger id: 5 # the Promise returned by then() |
485 | 483 | after 6 |
486 | 484 | ``` |
487 | 485 |
|
488 | | -#### `async_hooks.executionAsyncResource()` |
| 486 | +### `async_hooks.executionAsyncResource()` |
489 | 487 |
|
490 | 488 | <!-- YAML |
491 | 489 | added: v13.9.0 |
@@ -541,7 +539,7 @@ const server = createServer((req, res) => { |
541 | 539 | }).listen(3000); |
542 | 540 | ``` |
543 | 541 |
|
544 | | -#### `async_hooks.executionAsyncId()` |
| 542 | +### `async_hooks.executionAsyncId()` |
545 | 543 |
|
546 | 544 | <!-- YAML |
547 | 545 | added: v8.1.0 |
@@ -582,7 +580,7 @@ const server = net.createServer((conn) => { |
582 | 580 | Promise contexts may not get precise `executionAsyncIds` by default. |
583 | 581 | See the section on [promise execution tracking][]. |
584 | 582 |
|
585 | | -#### `async_hooks.triggerAsyncId()` |
| 583 | +### `async_hooks.triggerAsyncId()` |
586 | 584 |
|
587 | 585 | * Returns: {number} The ID of the resource responsible for calling the callback |
588 | 586 | that is currently being executed. |
|