Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: improve ALS.enterWith and exit descriptions #36705

Merged
merged 1 commit into from Jan 2, 2021
Merged

doc: improve ALS.enterWith and exit descriptions #36705

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
25 changes: 15 additions & 10 deletions doc/api/async_hooks.md
View file
Open in desktop
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