Skip to content

docs: documenting async hooks features #13287

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

Closed
AndreasMadsen wants to merge 18 commits into from
Closed

docs: documenting async hooks features #13287

Changes from 1 commit
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
59088f3
docs: async-hooks documentation
thlorenz Nov 28, 2016
1e35d73
[squash] addressing nits pointed out by Trevor
thlorenz Feb 7, 2017
c5db0a6
[squash] renaming Number to number
thlorenz May 10, 2017
3218d31
[squash] addressing simple nits
thlorenz May 18, 2017
aa830d7
[squash] remove standalone JS Embedder API docs
AndreasMadsen May 26, 2017
d09735f
[squash] AsyncEvent is renamed to AsyncResource
AndreasMadsen May 26, 2017
fa37457
[squash] use fs.writeSync and describe issue and solution
AndreasMadsen May 29, 2017
9b9cc15
[squash] async-hooks -> async_hooks
AndreasMadsen May 29, 2017
affa7a7
[squash] addaleax sugestions
AndreasMadsen May 29, 2017
1f23ab2
[squash] jasnell sugestions
AndreasMadsen May 29, 2017
47a51c1
[squash] id => ID
AndreasMadsen May 29, 2017
9864609
[squash] sam-github suggesions
AndreasMadsen May 29, 2017
de40c74
[squash] document resource object and its limitations
AndreasMadsen May 29, 2017
7c9ecd4
[squash] more sam-github suggesions
AndreasMadsen May 29, 2017
de82ef4
[squash] fix typos + make linter pass
addaleax May 29, 2017
d3ee97e
[squash] fix internal link
AndreasMadsen May 29, 2017
4ba706f
[squash] mikesherov suggesion
AndreasMadsen May 30, 2017
82149a8
[squash] trevnorris suggestions
AndreasMadsen Jun 1, 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] id => ID
  • Loading branch information
@AndreasMadsen
AndreasMadsen committed May 29, 2017
commit 47a51c11128528c0a38b0cc9e975632afa016bec
28 changes: 14 additions & 14 deletions doc/api/async_hooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,10 @@ Following is a simple overview of the public API.
```js
const async_hooks = require('async_hooks');

// Return the id of the current execution context.
// Return the ID of the current execution context.
const cid = async_hooks.currentId();

// Return the id of the handle responsible for triggering the callback of the
// Return the ID of the handle responsible for triggering the callback of the
// current execution scope to fire.
const tid = async_hooks.triggerId();

Expand Down Expand Up @@ -165,9 +165,9 @@ destructor calls are emulated.

##### `init(id, type, triggerId, resource)`
Copy link
Copy Markdown
Contributor

@trevnorris trevnorris May 30, 2017

Choose a reason for hiding this comment

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

The code has replaced id with asyncId for consistency and to always be more explicit about which id is being referred to.

Copy link
Copy Markdown
Contributor

@trevnorris trevnorris May 30, 2017

Choose a reason for hiding this comment

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

Feel like there's a lot of content in here that should either have it's own sub-header under init() or moved to it's own sub-header under Async Hooks.


* `id` {number} a unique id for the async resource
* `id` {number} a unique ID for the async resource
* `type` {string} the type of the async resource
* `triggerId` {number} the unique id of the async resource in whose
* `triggerId` {number} the unique ID of the async resource in whose
execution context this async resource was created
* `resource` {Object} reference to the resource representing the async operation,
needs to be released during _destroy_
Expand All @@ -187,7 +187,7 @@ require('net').createServer().listen(function() { this.close() });
clearTimeout(setTimeout(() => {}, 10));
```

Every new resource is assigned a unique id.
Every new resource is assigned a unique ID.

The `type` is a string that represents the type of resource that caused
`init()` to fire. Generally it will be the name of the resource's constructor.
Expand Down Expand Up @@ -370,27 +370,27 @@ fs.open(path, (err, fd) => {
}):
```

It is important to note that the id returned fom `currentId()` is related to
It is important to note that the ID returned fom `currentId()` is related to
execution timing, not causality (which is covered by `triggerId()`). For
example:

```js
const server = net.createServer(function onConnection(conn) {
// Returns the id of the server, not of the new connection, because the
// Returns the ID of the server, not of the new connection, because the
// onConnection callback runs in the execution scope of the server's
// MakeCallback().
async_hooks.currentId();

}).listen(port, function onListening() {
// Returns the id of a TickObject (i.e. process.nextTick()) because all
// Returns the ID of a TickObject (i.e. process.nextTick()) because all
// callbacks passed to .listen() are wrapped in a nextTick().
async_hooks.currentId();
});
```

#### `async_hooks.triggerId()`

* Returns {number} the id of the resource responsible for calling the callback
* Returns {number} the ID of the resource responsible for calling the callback
that is currently being executed.

For example:
Expand All @@ -399,13 +399,13 @@ For example:
const server = net.createServer(conn => {
Copy link
Copy Markdown
Member

@addaleax addaleax May 29, 2017

Choose a reason for hiding this comment

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

I think we run the linter on docs now, so this might need to be (conn) instead of conn

// Though the resource that caused (or triggered) this callback to
// be called was that of the new connection. Thus the return value
// of triggerId() is the id of "conn".
// of triggerId() is the ID of "conn".
async_hooks.triggerId();

}).listen(port, () => {
// Even though all callbacks passed to .listen() are wrapped in a nextTick()
// the callback itself exists because the call to the server's .listen()
// was made. So the return value would be the id of the server.
// was made. So the return value would be the ID of the server.
async_hooks.triggerId();
});
```
Expand Down Expand Up @@ -443,18 +443,18 @@ asyncResource.emitAfter();
// Call destroy() hooks.
asyncResource.emitDestroy();

// Return the unique id assigned to the AsyncResource instance.
// Return the unique ID assigned to the AsyncResource instance.
asyncResource.asyncId();

// Return the trigger id for the AsyncResource instance.
// Return the trigger ID for the AsyncResource instance.
asyncResource.triggerId();
```
Copy link
Copy Markdown
Contributor

@trevnorris trevnorris May 30, 2017

Choose a reason for hiding this comment

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

If this is supposed to be an API overview then it should probably have the sub-heading that says that. But it may also want to be removed, like I discussed above or the other similar section.


#### `AsyncResource(type[, triggerId])`

* arguments
* `type` {string} the type of ascycn event
* `triggerId` {number} the id of the execution context that created this async
* `triggerId` {number} the ID of the execution context that created this async
event
Copy link
Copy Markdown
Contributor

@trevnorris trevnorris May 30, 2017

Choose a reason for hiding this comment

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

Add that the default is currentId()

Copy link
Copy Markdown
Member Author

@AndreasMadsen AndreasMadsen May 31, 2017

Choose a reason for hiding this comment

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

Again, we can't document details in the summary.

* Returns {AsyncResource} A reference to `asyncHook`.

Expand Down