Skip to content

Commit

Permalink
doc: improve ALS.enterWith and exit descriptions
Browse files Browse the repository at this point in the history
PR-URL: #36705
Refs: #36683
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de>
Reviewed-By: Rich Trott <rtrott@gmail.com>
  • Loading branch information
puzpuzpuz authored and danielleadams committed Jan 12, 2021
1 parent 9eff709 commit 181bd05
Showing 1 changed file with 15 additions and 10 deletions.
25 changes: 15 additions & 10 deletions doc/api/async_hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -1000,7 +1000,7 @@ added:
-->

Creates a new instance of `AsyncLocalStorage`. Store is only provided within a
`run` method call.
`run` or after `enterWith` method call.

### `asyncLocalStorage.disable()`
<!-- YAML
Expand All @@ -1011,7 +1011,7 @@ added:

This method disables the instance of `AsyncLocalStorage`. All subsequent calls
to `asyncLocalStorage.getStore()` will return `undefined` until
`asyncLocalStorage.run()` is called again.
`asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()` is called again.

When calling `asyncLocalStorage.disable()`, all current contexts linked to the
instance will be exited.
Expand All @@ -1035,7 +1035,8 @@ added:

This method returns the current store.
If this method is called outside of an asynchronous context initialized by
calling `asyncLocalStorage.run`, it will return `undefined`.
calling `asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()`, it will
return `undefined`.

### `asyncLocalStorage.enterWith(store)`
<!-- YAML
Expand All @@ -1046,14 +1047,15 @@ added:

* `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.
This method transitions into the context for the remainder of the current
synchronous execution and then persists the store through any following
asynchronous calls.

Example:

```js
const store = { id: 1 };
// Replaces previous store with the given store object
asyncLocalStorage.enterWith(store);
asyncLocalStorage.getStore(); // Returns the store object
someAsyncOperation(() => {
Expand All @@ -1064,7 +1066,9 @@ someAsyncOperation(() => {
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`.
specifically bound to another context with an `AsyncResource`. That is why
`run` should be preferred over `enterWith` unless there are strong reasons
to use the latter method.

```js
const store = { id: 1 };
Expand Down Expand Up @@ -1130,14 +1134,15 @@ added:

This methods runs a function synchronously outside of a context and return its
return value. The store is not accessible within the callback function or
the asynchronous operations created within the callback.
the asynchronous operations created within the callback, i.e. any `getStore`
call done within the callback function will always return `undefined`.

Optionally, arguments can be passed to the function. They will be passed to
the callback function.

If the callback function throws an error, it will be thrown by `exit` too.
The stacktrace will not be impacted by this call and
the context will be re-entered.
The stacktrace will not be impacted by this call and the context will be
re-entered.

Example:

Expand Down

0 comments on commit 181bd05

Please sign in to comment.