FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

async_hooks: add using scopes to AsyncLocalStorage · nodejs/node@312476c · GitHub

/ node Public

Commit 312476c

Browse files
Qard
authored and
aduh95
committed
async_hooks: add using scopes to AsyncLocalStorage
Adds support for using scope = storage.withScope(data) to do the equivalent of a storage.run(data, fn) with using syntax. This enables avoiding unnecessary closures. PR-URL: #61674 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de> Reviewed-By: Bryan English <bryan@bryanenglish.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
1 parent 6c6c900 commit 312476c

5 files changed

Lines changed: 409 additions & 0 deletions

File tree

‎doc/api/async_context.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -386,6 +386,110 @@ try {
386386
}
387387
```
388388

389+
### `asyncLocalStorage.withScope(store)`
390+
391+
<!-- YAML
392+
added: REPLACEME
393+
-->
394+
395+
> Stability: 1 - Experimental
396+
397+
* `store` {any}
398+
* Returns: {RunScope}
399+
400+
Creates a disposable scope that enters the given store and automatically
401+
restores the previous store value when the scope is disposed. This method is
402+
designed to work with JavaScript's explicit resource management (`using` syntax).
403+
404+
Example:
405+
406+
```mjs
407+
import { AsyncLocalStorage } from 'node:async_hooks';
408+
409+
const asyncLocalStorage = new AsyncLocalStorage();
410+
411+
{
412+
using _ = asyncLocalStorage.withScope('my-store');
413+
console.log(asyncLocalStorage.getStore()); // Prints: my-store
414+
}
415+
416+
console.log(asyncLocalStorage.getStore()); // Prints: undefined
417+
```
418+
419+
```cjs
420+
const { AsyncLocalStorage } = require('node:async_hooks');
421+
422+
const asyncLocalStorage = new AsyncLocalStorage();
423+
424+
{
425+
using _ = asyncLocalStorage.withScope('my-store');
426+
console.log(asyncLocalStorage.getStore()); // Prints: my-store
427+
}
428+
429+
console.log(asyncLocalStorage.getStore()); // Prints: undefined
430+
```
431+
432+
The `withScope()` method is particularly useful for managing context in
433+
synchronous code where you want to ensure the previous store value is restored
434+
when exiting a block, even if an error is thrown.
435+
436+
```mjs
437+
import { AsyncLocalStorage } from 'node:async_hooks';
438+
439+
const asyncLocalStorage = new AsyncLocalStorage();
440+
441+
try {
442+
using _ = asyncLocalStorage.withScope('my-store');
443+
console.log(asyncLocalStorage.getStore()); // Prints: my-store
444+
throw new Error('test');
445+
} catch (e) {
446+
// Store is automatically restored even after error
447+
console.log(asyncLocalStorage.getStore()); // Prints: undefined
448+
}
449+
```
450+
451+
```cjs
452+
const { AsyncLocalStorage } = require('node:async_hooks');
453+
454+
const asyncLocalStorage = new AsyncLocalStorage();
455+
456+
try {
457+
using _ = asyncLocalStorage.withScope('my-store');
458+
console.log(asyncLocalStorage.getStore()); // Prints: my-store
459+
throw new Error('test');
460+
} catch (e) {
461+
// Store is automatically restored even after error
462+
console.log(asyncLocalStorage.getStore()); // Prints: undefined
463+
}
464+
```
465+
466+
**Important:** When using `withScope()` in async functions before the first
467+
`await`, be aware that the scope change will affect the caller's context. The
468+
synchronous portion of an async function (before the first `await`) runs
469+
immediately when called, and when it reaches the first `await`, it returns the
470+
promise to the caller. At that point, the scope change becomes visible in the
471+
caller's context and will persist in subsequent synchronous code until something
472+
else changes the scope value. For async operations, prefer using `run()` which
473+
properly isolates context across async boundaries.
474+
475+
```mjs
476+
import { AsyncLocalStorage } from 'node:async_hooks';
477+
478+
const asyncLocalStorage = new AsyncLocalStorage();
479+
480+
async function example() {
481+
using _ = asyncLocalStorage.withScope('my-store');
482+
console.log(asyncLocalStorage.getStore()); // Prints: my-store
483+
await someAsyncOperation(); // Function pauses here and returns promise
484+
console.log(asyncLocalStorage.getStore()); // Prints: my-store
485+
}
486+
487+
// Calling without await
488+
example(); // Synchronous portion runs, then pauses at first await
489+
// After the promise is returned, the scope 'my-store' is now active in caller!
490+
console.log(asyncLocalStorage.getStore()); // Prints: my-store (unexpected!)
491+
```
492+
389493
### Usage with `async/await`
390494

391495
If, within an async function, only one `await` call is to run within a context,
@@ -420,6 +524,64 @@ of `asyncLocalStorage.getStore()` after the calls you suspect are responsible
420524
for the loss. When the code logs `undefined`, the last callback called is
421525
probably responsible for the context loss.
422526

527+
## Class: `RunScope`
528+
529+
<!-- YAML
530+
added: REPLACEME
531+
-->
532+
533+
> Stability: 1 - Experimental
534+
535+
A disposable scope returned by [`asyncLocalStorage.withScope()`][] that
536+
automatically restores the previous store value when disposed. This class
537+
implements the [Explicit Resource Management][] protocol and is designed to work
538+
with JavaScript's `using` syntax.
539+
540+
The scope automatically restores the previous store value when the `using` block
541+
exits, whether through normal completion or by throwing an error.
542+
543+
### `scope.dispose()`
544+
545+
<!-- YAML
546+
added: REPLACEME
547+
-->
548+
549+
Explicitly ends the scope and restores the previous store value. This method
550+
is idempotent: calling it multiple times has the same effect as calling it once.
551+
552+
The `[Symbol.dispose]()` method defers to `dispose()`.
553+
554+
If `withScope()` is called without the `using` keyword, `dispose()` must be
555+
called manually to restore the previous store value. Forgetting to call
556+
`dispose()` will cause the store value to persist for the remainder of the
557+
current execution context:
558+
559+
```mjs
560+
import { AsyncLocalStorage } from 'node:async_hooks';
561+
562+
const storage = new AsyncLocalStorage();
563+
564+
// Without using, the scope must be disposed manually
565+
const scope = storage.withScope('my-store');
566+
// storage.getStore() === 'my-store' here
567+
568+
scope.dispose(); // Restore previous value
569+
// storage.getStore() === undefined here
570+
```
571+
572+
```cjs
573+
const { AsyncLocalStorage } = require('node:async_hooks');
574+
575+
const storage = new AsyncLocalStorage();
576+
577+
// Without using, the scope must be disposed manually
578+
const scope = storage.withScope('my-store');
579+
// storage.getStore() === 'my-store' here
580+
581+
scope.dispose(); // Restore previous value
582+
// storage.getStore() === undefined here
583+
```
584+
423585
## Class: `AsyncResource`
424586

425587
<!-- YAML
@@ -905,8 +1067,10 @@ const server = createServer((req, res) => {
9051067
}).listen(3000);
9061068
```
9071069
1070+
[Explicit Resource Management]: https://github.com/tc39/proposal-explicit-resource-management
9081071
[`AsyncResource`]: #class-asyncresource
9091072
[`EventEmitter`]: events.md#class-eventemitter
9101073
[`Stream`]: stream.md#stream
9111074
[`Worker`]: worker_threads.md#class-worker
1075+
[`asyncLocalStorage.withScope()`]: #asynclocalstoragewithscopestore
9121076
[`util.promisify()`]: util.md#utilpromisifyoriginal

‎lib/internal/async_local_storage/async_context_frame.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ const {
1212
const AsyncContextFrame = require('internal/async_context_frame');
1313
const { AsyncResource } = require('async_hooks');
1414

15+
const RunScope = require('internal/async_local_storage/run_scope');
16+
1517
class AsyncLocalStorage {
1618
#defaultValue = undefined;
1719
#name = undefined;
@@ -77,6 +79,10 @@ class AsyncLocalStorage {
7779
}
7880
return frame?.get(this);
7981
}
82+
83+
withScope(store) {
84+
return new RunScope(this, store);
85+
}
8086
}
8187

8288
module.exports = AsyncLocalStorage;

‎lib/internal/async_local_storage/async_hooks.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ const {
1919
executionAsyncResource,
2020
} = require('async_hooks');
2121

22+
const RunScope = require('internal/async_local_storage/run_scope');
23+
2224
const storageList = [];
2325
const storageHook = createHook({
2426
init(asyncId, type, triggerAsyncId, resource) {
@@ -142,6 +144,10 @@ class AsyncLocalStorage {
142144
}
143145
return this.#defaultValue;
144146
}
147+
148+
withScope(store) {
149+
return new RunScope(this, store);
150+
}
145151
}
146152

147153
module.exports = AsyncLocalStorage;

‎lib/internal/async_local_storage/run_scope.js‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
'use strict';
2+
3+
const {
4+
SymbolDispose,
5+
} = primordials;
6+
7+
class RunScope {
8+
#storage;
9+
#previousStore;
10+
#disposed = false;
11+
12+
constructor(storage, store) {
13+
this.#storage = storage;
14+
this.#previousStore = storage.getStore();
15+
storage.enterWith(store);
16+
}
17+
18+
dispose() {
19+
if (this.#disposed) {
20+
return;
21+
}
22+
this.#disposed = true;
23+
this.#storage.enterWith(this.#previousStore);
24+
}
25+
26+
[SymbolDispose]() {
27+
this.dispose();
28+
}
29+
}
30+
31+
module.exports = RunScope;

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL