Skip to content

Commit

Permalink
async_hooks: add sync enterWith to ALS
Browse files Browse the repository at this point in the history
This allows transitioning the entire following sync and async execution
sub-tree to the given async storage context. With this one can be sure
the context binding will remain for any following sync activity and all
descending async execution whereas the `run*(...)` methods must wrap
everything that is intended to exist within the context. This is helpful
for scenarios such as prepending a `'connection'` event to an http
server which binds everything that occurs within each request to
the given context. This is helpful for APMs to minimize the need
for patching and especially adding closures.

PR-URL: #31945
Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
  • Loading branch information
Qard authored and mhdawson committed Mar 9, 2020
1 parent 2a7d662 commit d368dcc
Show file tree
Hide file tree
Showing 3 changed files with 65 additions and 3 deletions.
42 changes: 42 additions & 0 deletions doc/api/async_hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -950,6 +950,48 @@ If this method is called outside of an asynchronous context initialized by
calling `asyncLocalStorage.run` or `asyncLocalStorage.runAndReturn`, it will
return `undefined`.

### `asyncLocalStorage.enterWith(store)`
<!-- YAML
added: REPLACEME
-->

* `store` {any}

Calling `asyncLocalStorage.enterWith(store)` will transition into the context
for the remainder of the current synchronous execution and will persist
through any following asynchronous calls.

Example:

```js
const store = { id: 1 };
asyncLocalStorage.enterWith(store);
asyncLocalStorage.getStore(); // Returns the store object
someAsyncOperation(() => {
asyncLocalStorage.getStore(); // Returns the same object
});
```

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`.

```js
const store = { id: 1 };

emitter.on('my-event', () => {
asyncLocalStorage.enterWith(store);
});
emitter.on('my-event', () => {
asyncLocalStorage.getStore(); // Returns the same object
});

asyncLocalStorage.getStore(); // Returns undefined
emitter.emit('my-event');
asyncLocalStorage.getStore(); // Returns the same object
```

### `asyncLocalStorage.run(store, callback[, ...args])`
<!-- YAML
added: v13.10.0
Expand Down
6 changes: 3 additions & 3 deletions lib/async_hooks.js
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ class AsyncLocalStorage {
}
}

_enter(store) {
enterWith(store) {
if (!this.enabled) {
this.enabled = true;
storageList.push(this);
Expand All @@ -258,7 +258,7 @@ class AsyncLocalStorage {
runSyncAndReturn(store, callback, ...args) {
const resource = executionAsyncResource();
const outerStore = resource[this.kResourceStore];
this._enter(store);
this.enterWith(store);
try {
return callback(...args);
} finally {
Expand Down Expand Up @@ -288,7 +288,7 @@ class AsyncLocalStorage {
run(store, callback, ...args) {
const resource = executionAsyncResource();
const outerStore = resource[this.kResourceStore];
this._enter(store);
this.enterWith(store);
process.nextTick(callback, ...args);
resource[this.kResourceStore] = outerStore;
}
Expand Down
20 changes: 20 additions & 0 deletions test/async-hooks/test-async-local-storage-enter-with.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
'use strict';
require('../common');
const assert = require('assert');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

setImmediate(() => {
const store = { foo: 'bar' };
asyncLocalStorage.enterWith(store);

assert.strictEqual(asyncLocalStorage.getStore(), store);
setTimeout(() => {
assert.strictEqual(asyncLocalStorage.getStore(), store);
}, 10);
});

setTimeout(() => {
assert.strictEqual(asyncLocalStorage.getStore(), undefined);
}, 10);

0 comments on commit d368dcc

Please sign in to comment.