From e3ef2607d787ae66bcb64ec51a70d584aed4d72e Mon Sep 17 00:00:00 2001 From: Romuald Brillout Date: Fri, 15 Jan 2021 16:38:13 +0100 Subject: [PATCH 1/6] doc: improve AsyncLocalStorage introduction --- doc/api/async_hooks.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 4a8a225c576fdb..52d3309868605a 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -973,6 +973,15 @@ chains. It allows storing data throughout the lifetime of a web request or any other asynchronous duration. It is similar to thread-local storage in other languages. +`AsyncLocalStorage` doesn't provide any new functionality that Async Hooks +doesn't already provide: anything implemented with `AsyncLocalStorage` can be +implemented with Async Hooks instead. The goal of `AsyncLocalStorage` is to +provide a more performant and memory safe way to share state accross +asynchronous calls. For example, the `AsyncLocalStorage` implementation doesn't +involve any `destroy` callback, which considerably improves performance, and, +in some cases, `destoy` can not be called or called very late which usually +leads to memory leak in implementations using it. + The following example uses `AsyncLocalStorage` to build a simple logger that assigns IDs to incoming HTTP requests and includes them in messages logged within each request. From af8e5143df66ac1968a304ebb47ee619083570cd Mon Sep 17 00:00:00 2001 From: Romuald Brillout Date: Fri, 15 Jan 2021 17:42:13 +0100 Subject: [PATCH 2/6] [review] add title --- doc/api/async_hooks.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 52d3309868605a..eeb4101e97ac29 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -973,14 +973,20 @@ chains. It allows storing data throughout the lifetime of a web request or any other asynchronous duration. It is similar to thread-local storage in other languages. -`AsyncLocalStorage` doesn't provide any new functionality that Async Hooks +## Difference with raw Async Hooks + +`AsyncLocalStorage` doesn't provide any new functionality that raw Async Hooks doesn't already provide: anything implemented with `AsyncLocalStorage` can be -implemented with Async Hooks instead. The goal of `AsyncLocalStorage` is to -provide a more performant and memory safe way to share state accross -asynchronous calls. For example, the `AsyncLocalStorage` implementation doesn't -involve any `destroy` callback, which considerably improves performance, and, -in some cases, `destoy` can not be called or called very late which usually -leads to memory leak in implementations using it. +implemented with Async Hooks instead. + +The goal of `AsyncLocalStorage` is to provide a more performant and memory safe +way to share state accross asynchronous calls. For example, the +`AsyncLocalStorage` implementation doesn't involve any `destroy` callback, +which considerably improves performance, and, in some cases, `destoy` can not +be called or called very late which usually leads to memory leak in +implementations using it. + +## Example The following example uses `AsyncLocalStorage` to build a simple logger that assigns IDs to incoming HTTP requests and includes them in messages From fdf72e706bdca31df8893fae317b59ab6423cf5b Mon Sep 17 00:00:00 2001 From: Romuald Brillout Date: Mon, 18 Jan 2021 22:25:12 +0100 Subject: [PATCH 3/6] [review] typo --- 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 eeb4101e97ac29..de8459680259b2 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -980,9 +980,9 @@ doesn't already provide: anything implemented with `AsyncLocalStorage` can be implemented with Async Hooks instead. The goal of `AsyncLocalStorage` is to provide a more performant and memory safe -way to share state accross asynchronous calls. For example, the +way to share state across asynchronous calls. For example, the `AsyncLocalStorage` implementation doesn't involve any `destroy` callback, -which considerably improves performance, and, in some cases, `destoy` can not +which considerably improves performance, and, in some cases, `destroy` can not be called or called very late which usually leads to memory leak in implementations using it. From a8db18cf2221096c7e1a5a2f718bd16b48019f60 Mon Sep 17 00:00:00 2001 From: Romuald Brillout Date: Mon, 18 Jan 2021 22:38:32 +0100 Subject: [PATCH 4/6] [review] remove information that are unnecessary, prone to become false, or prone to misinterpretationtion --- doc/api/async_hooks.md | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index de8459680259b2..24ed2a47ef10da 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -973,20 +973,9 @@ chains. It allows storing data throughout the lifetime of a web request or any other asynchronous duration. It is similar to thread-local storage in other languages. -## Difference with raw Async Hooks - -`AsyncLocalStorage` doesn't provide any new functionality that raw Async Hooks -doesn't already provide: anything implemented with `AsyncLocalStorage` can be -implemented with Async Hooks instead. - -The goal of `AsyncLocalStorage` is to provide a more performant and memory safe -way to share state across asynchronous calls. For example, the -`AsyncLocalStorage` implementation doesn't involve any `destroy` callback, -which considerably improves performance, and, in some cases, `destroy` can not -be called or called very late which usually leads to memory leak in -implementations using it. - -## Example +While you can implement your own implementation on top of the `async_hooks` +module, `AsyncLocalStorage` is a performant and memory safe implementation that +involves non-obvious optimizations. The following example uses `AsyncLocalStorage` to build a simple logger that assigns IDs to incoming HTTP requests and includes them in messages From c26fe6024d8958554be77feefd0ce62d276059a2 Mon Sep 17 00:00:00 2001 From: Romuald Brillout Date: Tue, 19 Jan 2021 08:57:26 +0100 Subject: [PATCH 5/6] [review] implement @puzpuzpuz's feedback --- doc/api/async_hooks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 24ed2a47ef10da..ed75732d5eefe1 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -973,9 +973,9 @@ chains. It allows storing data throughout the lifetime of a web request or any other asynchronous duration. It is similar to thread-local storage in other languages. -While you can implement your own implementation on top of the `async_hooks` -module, `AsyncLocalStorage` is a performant and memory safe implementation that -involves non-obvious optimizations. +While you can create your own implementation on top of the `async_hooks` module, +`AsyncLocalStorage` should be preferred as it is a performant and memory safe +implementation that involves non-obvious optimizations. The following example uses `AsyncLocalStorage` to build a simple logger that assigns IDs to incoming HTTP requests and includes them in messages From 2fe233d76c8701426d2a4ba340aec00b5a9a90ec Mon Sep 17 00:00:00 2001 From: Romuald Brillout Date: Fri, 22 Jan 2021 08:39:44 +0100 Subject: [PATCH 6/6] [review] emphasis significance of performance --- doc/api/async_hooks.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index ed75732d5eefe1..5f1d578beeb351 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -975,7 +975,8 @@ in other languages. While you can create your own implementation on top of the `async_hooks` module, `AsyncLocalStorage` should be preferred as it is a performant and memory safe -implementation that involves non-obvious optimizations. +implementation that involves significant optimizations that are non-obvious to +implement. The following example uses `AsyncLocalStorage` to build a simple logger that assigns IDs to incoming HTTP requests and includes them in messages