From dde8740af3b9c635caa4ea6bc95ef4830a66d8a8 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Sat, 5 Nov 2022 20:38:41 -0700 Subject: [PATCH] doc: add async_hooks migration note PR-URL: https://github.com/nodejs/node/pull/45335 Reviewed-By: Yagiz Nizipli Reviewed-By: Matteo Collina Reviewed-By: Rich Trott --- doc/api/async_hooks.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index e905e9844a9722..eb6af648c10e36 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -2,7 +2,16 @@ -> Stability: 1 - Experimental +> Stability: 1 - Experimental. Please migrate away from this API, if you can. +> We do not recommend using the [`createHook`][], [`AsyncHook`][], and +> [`executionAsyncResource`][] APIs as they have usability issues, safety risks, +> and performance implications. Async context tracking use cases are better +> served by the stable [`AsyncLocalStorage`][] API. If you have a use case for +> `createHook`, `AsyncHook`, or `executionAsyncResource` beyond the context +> tracking need solved by [`AsyncLocalStorage`][] or diagnostics data currently +> provided by [Diagnostics Channel][], please open an issue at +> describing your use case so we can +> create a more purpose-focused API. @@ -869,14 +878,18 @@ The documentation for this class has moved [`AsyncResource`][]. The documentation for this class has moved [`AsyncLocalStorage`][]. [DEP0111]: deprecations.md#dep0111-processbinding +[Diagnostics Channel]: diagnostics_channel.md [Hook Callbacks]: #hook-callbacks [PromiseHooks]: https://docs.google.com/document/d/1rda3yKGHimKIhg5YeoAmCOtyURgsbTH_qaYR79FELlk/edit +[`AsyncHook`]: #class-asynchook [`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage [`AsyncResource`]: async_context.md#class-asyncresource [`Worker`]: worker_threads.md#class-worker [`after` callback]: #afterasyncid [`before` callback]: #beforeasyncid +[`createHook`]: #async_hookscreatehookcallbacks [`destroy` callback]: #destroyasyncid +[`executionAsyncResource`]: #async_hooksexecutionasyncresource [`init` callback]: #initasyncid-type-triggerasyncid-resource [`process.getActiveResourcesInfo()`]: process.md#processgetactiveresourcesinfo [`promiseResolve` callback]: #promiseresolveasyncid