Skip to content

Commit

Permalink
doc: reduce header nesting in async_hooks.md
Browse files Browse the repository at this point in the history
Maximum header level reduced to 5.

PR-URL: #37839
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Pooja D P <Pooja.D.P@ibm.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
  • Loading branch information
Trott authored and targos committed May 1, 2021
1 parent 4c5eff9 commit b51651c
Showing 1 changed file with 20 additions and 22 deletions.
42 changes: 20 additions & 22 deletions doc/api/async_hooks.md
Expand Up @@ -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.

Expand Down Expand Up @@ -79,7 +77,7 @@ function destroy(asyncId) { }
function promiseResolve(asyncId) { }
```

#### `async_hooks.createHook(callbacks)`
## `async_hooks.createHook(callbacks)`

<!-- YAML
added: v8.1.0
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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`.

Expand All @@ -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`.

Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -415,7 +413,7 @@ TCPSERVERWRAP(5)
Timeout(7)
```

##### `before(asyncId)`
#### `before(asyncId)`

* `asyncId` {number}

Expand All @@ -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}

Expand All @@ -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}

Expand All @@ -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
Expand Down Expand Up @@ -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: v13.9.0
Expand Down Expand Up @@ -541,7 +539,7 @@ const server = createServer((req, res) => {
}).listen(3000);
```

#### `async_hooks.executionAsyncId()`
### `async_hooks.executionAsyncId()`

<!-- YAML
added: v8.1.0
Expand Down Expand Up @@ -582,7 +580,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.
Expand Down

0 comments on commit b51651c

Please sign in to comment.