docs: documenting async hooks features #13287

AndreasMadsen · 2017-05-29T19:23:54Z

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

async hooks
docs

This is a continuation on #12953 it should "fix" all the suggestions.

It took me 3 hours fix all the issues, so I would like if nits are done by you in a followup PR I simply don't have this much time. Also please be very specific with the suggestions, as in replace "this" with "this".

addaleax

LGTM modulo typos (if it helps I can fix them myself and push to this PR)

addaleax · 2017-05-29T19:25:50Z

doc/api/async_hooks.md

+
+If any `AsyncHook` callbacks throw, the application will print the stack trace
+and exit. The exit path does follow that of an uncaught exception but
+all `uncaughtException` listeners are removed, thus forceing the process to


typo: forceing → forcing

addaleax · 2017-05-29T19:26:00Z

doc/api/async_hooks.md

+If any `AsyncHook` callbacks throw, the application will print the stack trace
+and exit. The exit path does follow that of an uncaught exception but
+all `uncaughtException` listeners are removed, thus forceing the process to
+exit. The `'exit'` callbacks will still call unless the application is run with


call → be called

addaleax · 2017-05-29T19:26:27Z

doc/api/async_hooks.md

+
+##### Printing in AsyncHooks callbacks
+
+Because printing to the console is an asynchronous operations `console.log()`


typo: operations → operation

addaleax · 2017-05-29T19:26:39Z

doc/api/async_hooks.md

+##### Printing in AsyncHooks callbacks
+
+Because printing to the console is an asynchronous operations `console.log()`
+will cause the AsyncHooks callbacks to write. Using `console.log()` or similar


write → be called

addaleax · 2017-05-29T19:31:01Z

doc/api/async_hooks.md

+
+The `type` is a string that represents the type of resource that caused
+`init()` to call. Generally it will be the name of the resource's constructor.
+The resource types provided by the build in Node.js modules are:


typo: build in → built-in

addaleax · 2017-05-29T19:32:37Z

doc/api/async_hooks.md

+the user's callback is placed in a `process.nextTick()`.
+
+The graph only shows **when** a resource was created. Not **why**. So to track
+the **why** use `triggerId`.


typos: created. Not **why**. So to → created, not **why**, so to

addaleax · 2017-05-29T19:33:39Z

doc/api/async_hooks.md

+For example:
+
+```js
+const server = net.createServer(conn => {


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

addaleax · 2017-05-29T19:34:11Z

doc/api/async_hooks.md

+* Returns {undefined}
+
+Call all `before()` callbacks and let them know a new asynchronous execution
+context is being entered. If nested calls to `emitBefore()` are made the stack


comma after made

addaleax · 2017-05-29T19:34:22Z

doc/api/async_hooks.md

+
+* Returns {undefined}
+
+Call all `after()` callbacks. If nested calls to `emitBefore()` were made then


comma after made

addaleax · 2017-05-29T19:34:56Z

doc/api/async_hooks.md

+make sure the stack is unwound properly. Otherwise an error will be thrown.
+
+If the user's callback throws an exception then `emitAfter()` will
+automatically be called for all `id`'s on the stack if the error is handled by


remove the apostrophe (`id`'s → `id`s)

AndreasMadsen · 2017-05-29T19:57:38Z

LGTM modulo typos (if it helps I can fix them myself and push to this PR)

that would be awesome as I will go to bed soon. For minor things, I find this much more helpful.

mikesherov · 2017-05-29T20:58:21Z

doc/api/async_hooks.md

+
+An asynchronous resource represents an object with an associated callback.
+This callback may be called multiple times, for example, the `connection` event
+in `net.createServer`, or just a single time like in `fs.open`. A resource


A word is missing somewhere in this sentence: a resource can also be closed the callback is called

Thanks.

a resource can also be closed the before callback is called

trevnorris

Looking good. My bad on not seeing most of these before now.

trevnorris · 2017-05-30T21:43:37Z

doc/api/async_hooks.md

+An asynchronous resource represents an object with an associated callback.
+This callback may be called multiple times, for example, the `connection` event
+in `net.createServer`, or just a single time like in `fs.open`. A resource
+can also be closed before the callback is called. AsyncHooks does not


The class name is actually AsyncHook. Reason the module is called async_hooks (plural) was to match events and timers (both plural but their class names aren't).

A resource can also be closed before the callback is called.

It looks like we're abstracting the difference between a request and an handle? Personally that would make me sad. Spent a lot of time precisely describing the difference between the two. :P

There are zero references to request and handle in the of the documentation (except for the previous terminology section). If request and handle are to be included, it should be described exactly how those concepts are visible in async_hooks.

see: #12953 (comment)

trevnorris · 2017-05-30T21:50:05Z

doc/api/async_hooks.md

+
+// destroy() is called when an AsyncWrap instance is destroyed.
+function destroy(id) { }
+```


Should we just drop this whole section and replace it with common patterns and questions? e.g. "Handling events only once" in Events.

There are some corrections this section needs, but not going to comment b/c it may possibly be removed.

We definitely need a common patterns section, but let's not do it in this PR. When we write that I'm fine with removing this.

trevnorris · 2017-05-30T21:51:03Z

doc/api/async_hooks.md

+
+Registers functions to be called for different lifetime events of each async
+operation.
+The callbacks `init()`/`before()`/`after()`/`destroy()` are registered via an


why the early return after "operation."? Looks like this should be a single paragraph.

I'd either simplify this to:

The callbacks init()/before()/after()/destroy() are called for the respective asynchronous event during a resource's lifetime.

Or take the time to explain what "registered" means:

The callbacks init()/before()/after()/destroy() are registered to a global list of hooks that are called for each respective asynchronous event during a resource's lifetime.

trevnorris · 2017-05-30T21:59:25Z

doc/api/async_hooks.md

+All callbacks are optional. So, for example, if only resource cleanup needs to
+be tracked then only the `destroy()` callback needs to be passed. The
+specifics of all functions that can be passed to `callbacks` is in the section
+[`Hook Callbacks`][].


Possibly add that enabling an empty AsyncHook instance is a noop. Or add this in the enable() API section.

trevnorris · 2017-05-30T22:02:04Z

doc/api/async_hooks.md

+track of what caused the asynchronous operation using the information
+provided by AsyncHooks itself. The logging should then be skipped when
+it was the logging itself that caused AsyncHooks callback to call. By
+doing this the otherwise infinite recursion is broken.


I presented the idea elsewhere, but what about just disabling the ability to call a hook while other hooks are running? That would solve this easily (and I think it's reasonable that we don't need to give async statistics while the async hooks are running).

please respond to #12953 (comment)

/cc @jasnell

trevnorris · 2017-05-30T22:24:46Z

doc/api/async_hooks.md

+
+The `init()` hook will trigger when an `AsyncResource` is instantiated.
+
+It is important that before/after calls are unwined


We should make the document consistent between before()/after() or before/after or before/after. No personal preference, but is more aesthetically pleasing.

Instead:

It is important that before/after calls are unwound in the same order [...]

trevnorris · 2017-05-30T22:27:02Z

doc/api/async_hooks.md

+
+// Return the trigger ID for the AsyncResource instance.
+asyncResource.triggerId();
+```


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.

trevnorris · 2017-05-30T22:27:28Z

doc/api/async_hooks.md

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


Add that the default is currentId()

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

trevnorris · 2017-05-30T22:29:04Z

doc/api/async_hooks.md

+never called, causing a memory leak in the application. Of course if
+the resource doesn't depend on GC then this isn't an issue.
+
+#### `async_hooks.currentId()`


I think this should either be changed to asyncId() or currentAsyncId() (to follow the change for the function argument names). If the latter then triggerId() should probably be changed to currentTriggerId(). I'm down to hear alternatives, but would like to see it be more explicit and uniform. (sorry, my bad)

This would have been a really nice comment to make before node.js 8 was released.

/cc @addaleax

Yeah, it would be nice to have done that before, but I don’t think it needs to be a big deal.

currentAsyncId() and currentTriggerId() sound fine to me. We can always make the old names (non-enumerable?) aliases for those, so we don’t break any existing code.

I'm okay with renaming it, but I think it would be much better to do that in another PR.

trevnorris · 2017-05-30T22:30:49Z

doc/api/async_hooks.md

+```js
+class DBQuery extends AsyncResource {
+  constructor(db) {
+    super();


May want to do super('DBQuery'). Since this would throw. from source:

if (typeof type !== 'string' || type.length <= 0) throw new TypeError('type must be a string with length > 0');

AndreasMadsen · 2017-05-31T08:06:46Z

@trevnorris thanks for the review. I'm not going to fix any of this in the next 24 hours. I have addressed the comments I don't understand.

trevnorris · 2017-05-31T14:37:50Z

@AndreasMadsen No worries. I'll get to those you did leave comments on.

AndreasMadsen · 2017-06-01T08:26:07Z

@trevnorris please take a look.

I don't see a need for the handle and request terminology, I've described some different cases/examples in the before().
I didn't add the common patterns section, I think we can do that in a follow-up PR. When that is done I'm fine with removing some of the API overviews.
I didn't rename async_hooks.currentId(). I just want this to be a documentation PR, we can rename it in a follow-up PR.

trevnorris

Much thanks for getting this ready.

addaleax · 2017-06-01T21:04:11Z

Landed in 126170a 🎉

(fixed up 2 linter complaints while landing.)

Author: Thorsten Lorenz <[email protected]> Author: Andreas Madsen <[email protected]> PR-URL: #13287 Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Anna Henningsen <[email protected]>

MylesBorins · 2017-07-17T17:19:13Z

This does not land cleanly in LTS. Please feel free to manually backport. Please also feel free to replace do-not-land if it is being backported

thlorenz and others added 14 commits May 29, 2017 21:16

docs: async-hooks documentation

59088f3

[squash] addressing nits pointed out by Trevor

1e35d73

[squash] renaming Number to number

c5db0a6

[squash] addressing simple nits

3218d31

[squash] remove standalone JS Embedder API docs

aa830d7

[squash] AsyncEvent is renamed to AsyncResource

d09735f

[squash] use fs.writeSync and describe issue and solution

fa37457

[squash] async-hooks -> async_hooks

9b9cc15

[squash] addaleax sugestions

affa7a7

[squash] jasnell sugestions

1f23ab2

[squash] id => ID

47a51c1

[squash] sam-github suggesions

9864609

[squash] document resource object and its limitations

de40c74

[squash] more sam-github suggesions

7c9ecd4

nodejs-github-bot added async_hooks Issues and PRs related to the async hooks subsystem. doc Issues and PRs related to the documentations. labels May 29, 2017

AndreasMadsen mentioned this pull request May 29, 2017

8.0.0 Release Proposal #12220

Closed

addaleax approved these changes May 29, 2017

View reviewed changes

addaleax and others added 2 commits May 29, 2017 22:03

[squash] fix typos + make linter pass

de82ef4

[squash] fix internal link

d3ee97e

mikesherov reviewed May 29, 2017

View reviewed changes

AndreasMadsen mentioned this pull request May 30, 2017

[async_hooks] tracking issue nodejs/diagnostics#29

Closed

27 tasks

[squash] mikesherov suggesion

4ba706f

AndreasMadsen mentioned this pull request May 30, 2017

docs: documenting async hooks features #12953

Closed

2 tasks

trevnorris suggested changes May 30, 2017

View reviewed changes

Fishrock123 mentioned this pull request May 31, 2017

How do I try the new async_hook debugging features in node 8? nodejs/help#645

Closed

[squash] trevnorris suggestions

82149a8

trevnorris approved these changes Jun 1, 2017

View reviewed changes

addaleax closed this Jun 1, 2017

AndreasMadsen deleted the async-hooks-docs branch June 1, 2017 21:05

AndreasMadsen mentioned this pull request Jun 4, 2017

async_hooks: use resource objects for Promises #13452

Closed

4 tasks

jasnell mentioned this pull request Jun 5, 2017

8.1.0 Proposal #13483

Closed

gibfahn mentioned this pull request Jun 15, 2017

Auditing for 6.11.1 nodejs/Release#230

Closed

3 tasks

MylesBorins added the dont-land-on-v6.x label Jul 17, 2017


		##### Printing in AsyncHooks callbacks

		Because printing to the console is an asynchronous operations `console.log()`


		* Returns {undefined}

		Call all `after()` callbacks. If nested calls to `emitBefore()` were made then


		The `init()` hook will trigger when an `AsyncResource` is instantiated.

		It is important that before/after calls are unwined

docs: documenting async hooks features #13287

docs: documenting async hooks features #13287

Conversation

AndreasMadsen commented May 29, 2017

Checklist

Affected core subsystem(s)

addaleax left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AndreasMadsen commented May 29, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trevnorris left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AndreasMadsen commented May 31, 2017

trevnorris commented May 31, 2017

AndreasMadsen commented Jun 1, 2017 • edited Loading

trevnorris left a comment

Choose a reason for hiding this comment

addaleax commented Jun 1, 2017

MylesBorins commented Jul 17, 2017

AndreasMadsen commented May 29, 2017 •

edited

Loading

AndreasMadsen commented Jun 1, 2017 •

edited

Loading