From 2e6872b076e9c35c912dc89bd1021a02e687289e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gerhard=20St=C3=B6bich?= <18708370+Flarna@users.noreply.github.com> Date: Mon, 7 Nov 2022 23:02:54 +0100 Subject: [PATCH 01/15] doc, async_hooks: improve and add migration hints Add hints to migrate away from async hooks. Change docs at various places to be more clear that resources are internals and may change at any time. --- doc/api/async_hooks.md | 43 ++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 9439edbe224159..3021775649444b 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -6,6 +6,14 @@ +This module will most likely never reach stable state. Please migrate to +other APIs. + +* [`AsyncLocalStorage`][] is stable and designed to cover one of the +main usecases to track async context +* [`process.getActiveResourcesInfo()`][] might fit better to track active +resources + The `node:async_hooks` module provides an API to track asynchronous resources. It can be accessed using: @@ -327,20 +335,11 @@ current Node.js instance. 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 -resource's constructor. - -Valid values are: - -```text -FSEVENTWRAP, FSREQCALLBACK, GETADDRINFOREQWRAP, GETNAMEINFOREQWRAP, HTTPINCOMINGMESSAGE, -HTTPCLIENTREQUEST, JSSTREAM, PIPECONNECTWRAP, PIPEWRAP, PROCESSWRAP, QUERYWRAP, -SHUTDOWNWRAP, SIGNALWRAP, STATWATCHER, TCPCONNECTWRAP, TCPSERVERWRAP, TCPWRAP, -TTYWRAP, UDPSENDWRAP, UDPWRAP, WRITEWRAP, ZLIB, SSLCONNECTION, PBKDF2REQUEST, -RANDOMBYTESREQUEST, TLSWRAP, Microtask, Timeout, Immediate, TickObject -``` +resource's constructor. The `type` of resources created by Node.js itself +can change in any Node.js release. -These values can change in any Node.js release. Furthermore users of [`AsyncResource`][] -likely provide other values. +Furthermore users of [`AsyncResource`][] create async resources independent +of Node.js itself. There is also the `PROMISE` resource type, which is used to track `Promise` instances and asynchronous work scheduled by them. @@ -414,19 +413,19 @@ of propagating what resource is responsible for the new resource's existence. ##### `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 -the value of `type`. For instance, for the `GETADDRINFOREQWRAP` resource type, -`resource` provides the host name used when looking up the IP address for the -host in `net.Server.listen()`. The API for accessing this information is -not supported, but using the Embedder API, users can provide -and document their own resource objects. For example, such a resource object -could contain the SQL query being executed. +been initialized. The API to access the object may be specified by the +creator of the resource. Resources created by Node.js itself are internal +and may change at any time therefore no API is specified for these. 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 +The context tracking use case is covered by the stable API [`AsyncLocalStorage`][]. +This example only illustrates async hooks operation but [`AsyncLocalStorage`][] +fits better to this use case. + The following is an example with additional information about the calls to `init` between the `before` and `after` calls, specifically what the callback to `listen()` will look like. The output formatting is slightly more @@ -568,6 +567,9 @@ 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. +Using the destroy hook results in additional overhead because it enables +tracking of `Promise` instances via garbage collector. + #### `promiseResolve(asyncId)` -> Stability: 1 - Experimental +> Stability: 1 - Experimental. This module will most likely never reach stable +> state. Please migrate to other APIs. -This module will most likely never reach stable state. Please migrate to -other APIs. +There are other APIs available to replace async_hooks at least for most use +cases. Migrate/use them instead of using async_hooks. For example: -* [`AsyncLocalStorage`][] is stable and designed to cover one of the -main usecases to track async context -* [`process.getActiveResourcesInfo()`][] might fit better to track active -resources +* [`AsyncLocalStorage`][] tracks async context +* [`process.getActiveResourcesInfo()`][] tracks active resources The `node:async_hooks` module provides an API to track asynchronous resources. It can be accessed using: From 23db5d4c53401eec9bb280b74e178b781f655b77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gerhard=20St=C3=B6bich?= <18708370+Flarna@users.noreply.github.com> Date: Tue, 8 Nov 2022 14:07:58 +0100 Subject: [PATCH 07/15] fixup: build --- doc/api/async_hooks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 5830de59792a47..8e107cc49c8021 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -7,8 +7,8 @@ -There are other APIs available to replace async_hooks at least for most use -cases. Migrate/use them instead of using async_hooks. For example: +There are other APIs available to replace `async_hooks` at least for most use +cases. Migrate/use them instead of using `async_hooks`. For example: * [`AsyncLocalStorage`][] tracks async context * [`process.getActiveResourcesInfo()`][] tracks active resources From e96057ce3ea4a4a85a8a9f6058e691c2dfac55ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gerhard=20St=C3=B6bich?= Date: Tue, 8 Nov 2022 19:49:22 +0100 Subject: [PATCH 08/15] remove note regading reaching stable state --- doc/api/async_hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 8e107cc49c8021..734cf59f2890c2 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -2,7 +2,7 @@ -> Stability: 1 - Experimental. This module will most likely never reach stable +> Stability: 1 - Experimental > state. Please migrate to other APIs. From 9dc833e2d0d12bba1935ab7dd04d2f0364a1296a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gerhard=20St=C3=B6bich?= Date: Wed, 9 Nov 2022 12:18:40 +0100 Subject: [PATCH 09/15] improve intro Co-authored-by: Geoffrey Booth --- doc/api/async_hooks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 734cf59f2890c2..b85e97d5f7cd83 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -7,8 +7,8 @@ -There are other APIs available to replace `async_hooks` at least for most use -cases. Migrate/use them instead of using `async_hooks`. For example: +We strongly discourage the use of the `async_hooks` API. +Other APIs that can cover most of its use cases include: * [`AsyncLocalStorage`][] tracks async context * [`process.getActiveResourcesInfo()`][] tracks active resources From 5634f7bdebeca5245251bca357976b5c1361a61d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gerhard=20St=C3=B6bich?= Date: Wed, 9 Nov 2022 12:19:56 +0100 Subject: [PATCH 10/15] fixup: remove leftover Co-authored-by: Geoffrey Booth --- doc/api/async_hooks.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index b85e97d5f7cd83..a9428e9ab5d2ce 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -3,7 +3,6 @@ > Stability: 1 - Experimental -> state. Please migrate to other APIs. From c1b0d0e92c54ba9f1c3500b9a5f142aba41fa45a Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 9 Nov 2022 15:12:03 -0800 Subject: [PATCH 11/15] Update doc/api/async_hooks.md --- doc/api/async_hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index a9428e9ab5d2ce..a52560dce1fda8 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -336,7 +336,7 @@ The `type` is a string identifying the type of resource that caused resource's constructor. The `type` of resources created by Node.js itself can change in any Node.js -release. Valid values at the time of writing are for example `TLSWRAP`, +release. Valid values are `TLSWRAP`, `TCPWRAP`, `TCPSERVERWRAP`, `GETADDRINFOREQWRAP`, `FSREQCALLBACK`, `Microtask`, `Timeout`. Inspect the source code of the Node.js version used to get the full list. From 6da950b75f3da00e23934303a76d6875a141fcd8 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 9 Nov 2022 15:12:44 -0800 Subject: [PATCH 12/15] Update doc/api/async_hooks.md --- doc/api/async_hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index a52560dce1fda8..b9d6dc6015114f 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -338,7 +338,7 @@ resource's constructor. The `type` of resources created by Node.js itself can change in any Node.js release. Valid values are `TLSWRAP`, `TCPWRAP`, `TCPSERVERWRAP`, `GETADDRINFOREQWRAP`, `FSREQCALLBACK`, -`Microtask`, `Timeout`. Inspect the source code of the Node.js version used +`Microtask`, and `Timeout`. Inspect the source code of the Node.js version used to get the full list. Furthermore users of [`AsyncResource`][] create async resources independent From c0e4745e47dd8db116a8c1cc0ad371a300b99457 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 9 Nov 2022 15:13:11 -0800 Subject: [PATCH 13/15] Update doc/api/async_hooks.md --- doc/api/async_hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index b9d6dc6015114f..153837ffc0fb5e 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -336,7 +336,7 @@ The `type` is a string identifying the type of resource that caused resource's constructor. The `type` of resources created by Node.js itself can change in any Node.js -release. Valid values are `TLSWRAP`, +release. Valid values include `TLSWRAP`, `TCPWRAP`, `TCPSERVERWRAP`, `GETADDRINFOREQWRAP`, `FSREQCALLBACK`, `Microtask`, and `Timeout`. Inspect the source code of the Node.js version used to get the full list. From 55ef7839f614bc2dbbdf5a669d47b78a1d73c6d7 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 9 Nov 2022 15:14:22 -0800 Subject: [PATCH 14/15] Update doc/api/async_hooks.md --- doc/api/async_hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 153837ffc0fb5e..404acfd10f816f 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -418,7 +418,7 @@ of propagating what resource is responsible for the new resource's existence. `resource` is an object that represents the actual async resource that has been initialized. The API to access the object may be specified by the creator of the resource. Resources created by Node.js itself are internal -and may change at any time therefore no API is specified for these. +and may change at any time. Therefore no API is specified for these. 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. From 797f82fb76aa87cc5b7a62723310b26281da039c Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 9 Nov 2022 15:15:25 -0800 Subject: [PATCH 15/15] Update doc/api/async_hooks.md --- doc/api/async_hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 404acfd10f816f..99ada9240f18c2 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -571,7 +571,7 @@ 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. Using the destroy hook results in additional overhead because it enables -tracking of `Promise` instances via garbage collector. +tracking of `Promise` instances via the garbage collector. #### `promiseResolve(asyncId)`