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

async_hooks: docs and api ergonomics tweaks #15103

Closed
wants to merge 5 commits into from
Closed

async_hooks: docs and api ergonomics tweaks #15103

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
73b8272
doc: some async_hooks docs improvements
jasnell Aug 30, 2017
def3c83
async_hooks: add type checking for AsyncResource type
jasnell Sep 1, 2017
f1cdae3
[Squash] Doc nits
jasnell Sep 1, 2017
b4a1075
[Squash] Update tests
jasnell Sep 6, 2017
8f032cf
[Squash] Nits
jasnell Sep 14, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
[Squash] Doc nits
  • Loading branch information
@jasnell
jasnell committed Sep 1, 2017
commit f1cdae3a5611cae2440e63cbbf6f3e50adf12736
27 changes: 14 additions & 13 deletions doc/api/async_hooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,26 +283,27 @@ propagating what resource is responsible for the new resource's existence.

###### `resource`

`resource` is an object that represents the actual resource. This can contain
useful information that can vary based on the value of `type`. For instance,
for the `GETADDRINFOREQWRAP` resource type, it provides the hostname used when
looking up the IP address for the hostname in `net.Server.listen()`. The API for
accessing this information is currently not considered public, but using the
Embedder API, users can provide and document their own resource objects. Such
a resource object could for example contain the SQL query being executed.
`resource` is an object that represents the actual async resource that has
been initialized. This can contain useful information that can vary based on
the value of `type`. For instance, for the `GETADDRINFOREQWRAP` resource type,
`resource` provides the hostname used when looking up the IP address for the
hostname in `net.Server.listen()`. The API for accessing this information is
currently not considered public, but using the Embedder API, users can provide
and document their own resource objects. Such a resource object could for
example contain the SQL query being executed.

In the case of Promises, the `resource` object will have `promise` property
that refers to the Promise that is being initialized, and a `parentId` property
that set to the `asyncId` of a parent Promise, if there is one, and
`undefined` otherwise. For example, in the case of `b = a.then(handler)`,
`a` is considered a parent Promise of `b`.
set to the `asyncId` of a parent Promise, if there is one, and `undefined`
otherwise. For example, in the case of `b = a.then(handler)`, `a` is considered
a parent Promise of `b`.

*Note*: In some cases the resource object is reused for performance reasons,
it is thus not safe to use it as a key in a `WeakMap` or add properties to it.

###### Asynchronous context example
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure of any current style, but should headers capitalize all words? doesn't matter to me either way.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

heck if I know. I don't think we've had much of a consistent style here.


Following is an example with additional information about the calls to
The following is an example with additional information about the calls to
`init` between the `before` and `after` calls, specifically what the
callback to `listen()` will look like. The output formatting is slightly more
elaborate to make calling context easier to see.
Expand Down Expand Up @@ -427,7 +428,7 @@ called asynchronously from the embedder API `emitDestroy()`.
*Note:* Some resources depend on garbage collection for cleanup, so if a
reference is made to the `resource` object passed to `init` it is possible that
`destroy` will never be called, causing a memory leak in the application. If
the resource does not depend on garbage collection then this will not be an
the resource does not depend on garbage collection, then this will not be an
issue.

#### `async_hooks.executionAsyncId()`
Expand Down Expand Up @@ -533,7 +534,7 @@ asyncResource.triggerAsyncId();
#### `AsyncResource(type[, triggerAsyncId])`

* arguments
* `type` {string} the type of ascyc event
* `type` {string} the type of async event
* `triggerAsyncId` {number} the ID of the execution context that created this
async event

Expand Down