From d4e5c381c129c4e0af04a7fcc7b312123bd6d7a5 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 08:33:09 +0100 Subject: [PATCH 1/2] async_hooks: rename AsyncLocalStore#enterWith to set The name enterWith indicates that there should be a matching exit but this is not the case. AsyncLocalStore#exit exists but it is not the opponent of enterWith. enterWith() is kept as alias and marked as doc only deprecated. --- benchmark/diagnostics_channel/http.js | 4 +-- doc/api/async_context.md | 28 ++++++++++++++----- lib/async_hooks.js | 5 +++- .../test-async-local-storage-enter-with.js | 4 ++- ...t-diagnostics-channel-http-server-start.js | 2 +- 5 files changed, 31 insertions(+), 12 deletions(-) diff --git a/benchmark/diagnostics_channel/http.js b/benchmark/diagnostics_channel/http.js index 55fac8a706df15..74c6adfdfded24 100644 --- a/benchmark/diagnostics_channel/http.js +++ b/benchmark/diagnostics_channel/http.js @@ -42,7 +42,7 @@ function patch() { function wrappedEmit(...args) { const [name, req, res] = args; if (name === 'request') { - als.enterWith({ + als.set({ url: req.url, start: process.hrtime.bigint() }); @@ -72,7 +72,7 @@ function diagnostics_channel() { const finish = dc.channel('http.server.response.finish'); function onStart(req) { - als.enterWith({ + als.set({ url: req.url, start: process.hrtime.bigint() }); diff --git a/doc/api/async_context.md b/doc/api/async_context.md index a41b73ce67697e..31d24bd5f42ee4 100644 --- a/doc/api/async_context.md +++ b/doc/api/async_context.md @@ -125,7 +125,7 @@ added: --> Creates a new instance of `AsyncLocalStorage`. Store is only provided within a -`run()` call or after an `enterWith()` call. +`run()` call or after an `set()` call. ### `asyncLocalStorage.disable()` @@ -139,7 +139,7 @@ added: Disables the instance of `AsyncLocalStorage`. All subsequent calls to `asyncLocalStorage.getStore()` will return `undefined` until -`asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()` is called again. +`asyncLocalStorage.run()` or `asyncLocalStorage.set()` is called again. When calling `asyncLocalStorage.disable()`, all current contexts linked to the instance will be exited. @@ -164,7 +164,7 @@ added: Returns the current store. If called outside of an asynchronous context initialized by -calling `asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()`, it +calling `asyncLocalStorage.run()` or `asyncLocalStorage.set()`, it returns `undefined`. ### `asyncLocalStorage.enterWith(store)` @@ -173,13 +173,26 @@ returns `undefined`. added: - v13.11.0 - v12.17.0 +deprecated: + - REPLACEME +--> + +> Stability: 0 - Deprecated: Use [`asyncLocalStorage.set(store)`][] + +This is a deprecated alias for [`asyncLocalStorage.set(store)`][]. + +### `asyncLocalStorage.set(store)` + + > Stability: 1 - Experimental * `store` {any} -Transitions into the context for the remainder of the current +Sets `store` on current execution context for the remainder of the current synchronous execution and then persists the store through any following asynchronous calls. @@ -188,7 +201,7 @@ Example: ```js const store = { id: 1 }; // Replaces previous store with the given store object -asyncLocalStorage.enterWith(store); +asyncLocalStorage.set(store); asyncLocalStorage.getStore(); // Returns the store object someAsyncOperation(() => { asyncLocalStorage.getStore(); // Returns the same object @@ -199,14 +212,14 @@ This transition will continue for the _entire_ synchronous execution. This means that if, for example, the context is entered within an event handler subsequent event handlers will also run within that context unless specifically bound to another context with an `AsyncResource`. That is why -`run()` should be preferred over `enterWith()` unless there are strong reasons +`run()` should be preferred over `set()` unless there are strong reasons to use the latter method. ```js const store = { id: 1 }; emitter.on('my-event', () => { - asyncLocalStorage.enterWith(store); + asyncLocalStorage.set(store); }); emitter.on('my-event', () => { asyncLocalStorage.getStore(); // Returns the same object @@ -816,4 +829,5 @@ const server = createServer((req, res) => { [`EventEmitter`]: events.md#class-eventemitter [`Stream`]: stream.md#stream [`Worker`]: worker_threads.md#class-worker +[`asyncLocalStorage.set(store)`]: #asynclocalstoragesetstore [`util.promisify()`]: util.md#utilpromisifyoriginal diff --git a/lib/async_hooks.js b/lib/async_hooks.js index 8638bb4d7b3497..642c418b3b5acd 100644 --- a/lib/async_hooks.js +++ b/lib/async_hooks.js @@ -307,7 +307,7 @@ class AsyncLocalStorage { } } - enterWith(store) { + set(store) { this._enable(); const resource = executionAsyncResource(); resource[this.kResourceStore] = store; @@ -353,6 +353,9 @@ class AsyncLocalStorage { } } +// Create deprecated enterWith alias +AsyncLocalStorage.prototype.enterWith = AsyncLocalStorage.prototype.set; + // Placing all exports down here because the exported classes won't export // otherwise. module.exports = { diff --git a/test/async-hooks/test-async-local-storage-enter-with.js b/test/async-hooks/test-async-local-storage-enter-with.js index 736dd83f853763..c66f244a07241b 100644 --- a/test/async-hooks/test-async-local-storage-enter-with.js +++ b/test/async-hooks/test-async-local-storage-enter-with.js @@ -5,9 +5,11 @@ const { AsyncLocalStorage } = require('async_hooks'); const asyncLocalStorage = new AsyncLocalStorage(); +assert.strictEqual(AsyncLocalStorage.prototype.enterWith, AsyncLocalStorage.prototype.set); + setImmediate(() => { const store = { foo: 'bar' }; - asyncLocalStorage.enterWith(store); + asyncLocalStorage.set(store); assert.strictEqual(asyncLocalStorage.getStore(), store); setTimeout(() => { diff --git a/test/parallel/test-diagnostics-channel-http-server-start.js b/test/parallel/test-diagnostics-channel-http-server-start.js index ad2f6ba48872e2..38ffafab4c8208 100644 --- a/test/parallel/test-diagnostics-channel-http-server-start.js +++ b/test/parallel/test-diagnostics-channel-http-server-start.js @@ -11,7 +11,7 @@ let context; // Bind requests to an AsyncLocalStorage context dc.subscribe('http.server.request.start', common.mustCall((message) => { - als.enterWith(message); + als.set(message); context = message; })); From 75eb1eb25b3b6ba954ec23a7afa58ba98b014ef9 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 09:18:55 +0100 Subject: [PATCH 2/2] fixup: align test name --- ...ocal-storage-enter-with.js => test-async-local-storage-set.js} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename test/async-hooks/{test-async-local-storage-enter-with.js => test-async-local-storage-set.js} (100%) diff --git a/test/async-hooks/test-async-local-storage-enter-with.js b/test/async-hooks/test-async-local-storage-set.js similarity index 100% rename from test/async-hooks/test-async-local-storage-enter-with.js rename to test/async-hooks/test-async-local-storage-set.js