Async worker and error handling documentation by NickNaso · Pull Request #272 · nodejs/node-addon-api

NickNaso · 2018-05-17T09:29:46Z

This is a first step on writing AsyncWorker documentation. Please review the document and suggest some improvements.

Changed version of node-addon-api on the package.json example see: [issue 206](#206 (comment))

mhdawson · 2018-05-17T13:55:43Z

-You are reading a draft of the next documentation and it's in continuos update so
-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+Node.js native add-ons often need to execute long running tasks and to avoid of


remove of

mhdawson · 2018-05-17T13:56:58Z

-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+Node.js native add-ons often need to execute long running tasks and to avoid of
+blocking the **event loop** they have to accomplish to them in the asynchronous way.
+Lets do a quick overview of how asynchronous code work in Node.js. In our model


I would drop the sentence Lets ... Node.js and change In our model to be `In the Node.js model'

mhdawson · 2018-05-17T13:57:52Z

+Node.js native add-ons often need to execute long running tasks and to avoid of
+blocking the **event loop** they have to accomplish to them in the asynchronous way.
+Lets do a quick overview of how asynchronous code work in Node.js. In our model
+of execution we have **two threads**, the first is the **event loop** thread, that


'we have' -> 'there are', the node.js guidance is to avoid you, we etc.

mhdawson · 2018-05-17T14:00:56Z

+Lets do a quick overview of how asynchronous code work in Node.js. In our model
+of execution we have **two threads**, the first is the **event loop** thread, that
+represents the thread where or JavaScript code is executing in. We want avoid to 
+stall the event loop thread doing heavy computation so we need to create a sencond


'stalling the event loop thread' -> blocking other work queued on the event loop by. Therefore, we need to do this work on another thread.

mhdawson · 2018-05-17T14:04:35Z

-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+Node.js native add-ons often need to execute long running tasks and to avoid of
+blocking the **event loop** they have to accomplish to them in the asynchronous way.


have to accomplish to them -> have to run them asynchronously from the event loop.

mhdawson · 2018-05-17T14:05:34Z

+blocking the **event loop** they have to accomplish to them in the asynchronous way.
+Lets do a quick overview of how asynchronous code work in Node.js. In our model
+of execution we have **two threads**, the first is the **event loop** thread, that
+represents the thread where or JavaScript code is executing in. We want avoid to 


Remove 'or' and 'in'

We want avoid to -> In order to avoid

NickNaso · 2018-05-21T15:25:42Z

Hi @mhdawson do I consider to add resource_name and resource like reported here #253 on on the documentation for AyncWorker?

NickNaso · 2018-05-22T20:14:02Z

Hi @mhdawson When you have some time, could you review my first pass on AsyncWorker documentation?

mhdawson · 2018-05-25T21:35:42Z

@NickNaso was out travelling this week. Will try to get to it Monday/Tuesday next week, or possibly on my travels for the summit in Berlin.

gabrielschulhof · 2018-06-06T22:29:10Z

+**event loop**.
+In the Node.js model of execution there are **two threads**, the first is the
+**event loop** thread, that represents the thread where JavaScript code is
+executing. The node.js guidance is to avoid you blocking other work queued on the


Node.js should be uppercase.

"avoid ~~you~~"

event loop bythread"

gabrielschulhof · 2018-06-06T22:29:48Z

+asynchronously so that their methods can return in advance of the work being
+completed.
+
+Node Addon API provides an ABI-stable interface to support functions which covers


"~~which covers~~that cover"

gabrielschulhof · 2018-06-06T22:31:11Z

+completed.
+
+Node Addon API provides an ABI-stable interface to support functions which covers
+the most common asynchronous use cases. You have two abstract class to implement


The general guidance is to not formulate sentences using "you". So, we should have "~~You have~~There are".

"abstract classes"

gabrielschulhof · 2018-06-06T22:31:34Z

+
+Node Addon API provides an ABI-stable interface to support functions which covers
+the most common asynchronous use cases. You have two abstract class to implement
+asynchronous operation:


"operations"

gabrielschulhof · 2018-06-06T22:31:59Z

+- **[AsyncWorker](async_worker.md)**
+- **[Async Context](async_context.md)**
+
+These two classes help you to manage asynchronous operations through an abstraction


"help ~~you to~~"

gabrielschulhof · 2018-06-06T22:32:33Z

-You are reading a draft of the next documentation and it's in continuos update so
-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+`AsyncWorker` is an abstract class that you can subclass to remove much of the


"~~much~~many"

gabrielschulhof · 2018-06-06T22:32:53Z

-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+`AsyncWorker` is an abstract class that you can subclass to remove much of the
+tedious tasks on moving data between the event loop and worker threads. This


gabrielschulhof · 2018-06-06T22:33:23Z

-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+`AsyncWorker` is an abstract class that you can subclass to remove much of the
+tedious tasks on moving data between the event loop and worker threads. This
+class internally handles all the details of creating and executing asynchronous


"an asynchronous"

gabrielschulhof · 2018-06-06T22:34:14Z

+
+### Queue
+
+Requests that the created work or task will be placed on the queue of the execution.


Perhaps instead of "placed on the queue of the execution" we could say "queued for execution".

gabrielschulhof · 2018-06-06T22:34:50Z

+ObjectReference& Receiver();
+```
+
+Returns the persistent object reference of the receiver objet set when the async


gabrielschulhof · 2018-06-06T22:35:14Z

+```
+
+Returns the persistent object reference of the receiver objet set when the async
+worker is created.


gabrielschulhof

Excellent!

…s about constructor

NickNaso · 2018-06-12T00:19:04Z

@gabrielschulhof @mhdawson @kfarnung I just fixed documentation as requested. if someone want take another look should be good.

kfarnung · 2018-06-12T00:22:29Z

+Node.js native add-ons often need to execute long running tasks and to avoid
+blocking the **event loop** they have to run them asynchronously from the
+**event loop**.
+In the Node.js model of execution there are **two threads**, the first is the


Are there actually two threads? There's the main event loop thread that's constant and worker threads as needed.

Maybe I can rewrite the sentence like this:
In the Node.js model of execution the event loop thread represents the thread where JavaScript code is executing.

I think that's better.

kfarnung · 2018-06-12T00:24:20Z

+
+### Constructor
+
+Creates new async worker.


nit: "Creates a new AsyncWorker"

webern · 2018-06-14T05:53:52Z

@@ -1,5 +1,260 @@
-# Async worker
+# AsyncWorker


Can you say more about the lifetime of the AsyncWorker? I may have missed it, but I'm trying to understand exactly when/how the AsyncWorker is destroyed. I have an issue currently where Jest never exits and the uv loop has a handle count of 1. I don't know what that object is, it could be something I did in JavaScript, but the AsyncWorker I created is a suspicious candidate.

mhdawson

LGTM

mhdawson · 2018-06-14T16:23:28Z

Believe all comments are addressed, plan to land, hopefully this afternoon.

webern

Thank you for addressing my comments. Looks good and is certainly better than what we have now!

webern · 2018-06-14T15:40:43Z

+
+### Execute
+
+This method is used to execute some tasks out of the **event loop** on a libuv


This should probably warn that using Napi::Objects during the Execute operation will segfault.

I think I covered that with As the method is not
+running on the main event loop, it must avoid calling any methods from node-addon-api
+or running any code that might invoke JavaScript.

PR-URL: #272 Reviewed-By: Kyle Farnung <kfarnung@microsoft.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

mhdawson · 2018-06-14T21:34:07Z

Landed as 5a63f45

PR-URL: nodejs/node-addon-api#272 Reviewed-By: Kyle Farnung <kfarnung@microsoft.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

NickNaso added 7 commits January 4, 2018 02:07

Update package.json example

825440a

Changed version of node-addon-api on the package.json example see: [issue 206](#206 (comment))

First step of error documentation

d11cd21

Start working on error documentation

178dd33

Documentation for error handling

794ee4d

Async operations documentation

3eae5e1

Added example of async woirker

8cc39be

Add description for some async worker method

b79abf0

NickNaso changed the title ~~Async worker~~ Async worker documentation May 17, 2018

NickNaso mentioned this pull request May 17, 2018

Documentation push on node-add-api nodejs/abi-stable-node#280

Closed

mhdawson reviewed May 17, 2018

View reviewed changes

Ececuted changes oafter forst review

bfdd76f

gabrielschulhof reviewed Jun 6, 2018

View reviewed changes

gabrielschulhof reviewed Jun 7, 2018

View reviewed changes

Fixed errors reported in the first review and added some missing part…

83103eb

…s about constructor

NickNaso changed the title ~~Async worker documentation~~ Async worker and error handling documentation Jun 12, 2018

Fixed error handling documentation ofeter review

b46fd8d

NickNaso mentioned this pull request Jun 12, 2018

Documentation for error handling #259

Closed

kfarnung reviewed Jun 12, 2018

View reviewed changes

kfarnung approved these changes Jun 12, 2018

View reviewed changes

NickNaso added 2 commits June 12, 2018 20:01

Fixed async worker contructor docs

be01a86

Updated initial description on ansynchronous operation

c7eb8cb

kfarnung approved these changes Jun 12, 2018

View reviewed changes

mhdawson mentioned this pull request Jun 13, 2018

Segfault when using node-addon-api Objects during AsyncWorker::Execute #281

Closed

webern reviewed Jun 14, 2018

View reviewed changes

NickNaso and others added 5 commits June 14, 2018 08:49

Use one single backtick on constructor doc

5793481

squash: made some suggested changes

977cf1f

squash: add additional details for AsyncWorker

fce33d1

squash: Add some info/edits for error_handling.md

1c87b82

squash: address comments

5a3cc85

mhdawson approved these changes Jun 14, 2018

View reviewed changes

webern approved these changes Jun 14, 2018

View reviewed changes

squash: fix typo

c5906f2

mhdawson pushed a commit that referenced this pull request Jun 14, 2018

doc: First step of error and async doc

5a63f45

PR-URL: #272 Reviewed-By: Kyle Farnung <kfarnung@microsoft.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

mhdawson closed this Jun 14, 2018


		### Queue

		Requests that the created work or task will be placed on the queue of the execution.


		### Execute

		This method is used to execute some tasks out of the event loop on a libuv

Uh oh!

Conversation

NickNaso commented May 17, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mhdawson May 17, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mhdawson May 17, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NickNaso commented May 21, 2018

Uh oh!

NickNaso commented May 22, 2018

Uh oh!

mhdawson commented May 25, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gabrielschulhof Jun 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gabrielschulhof Jun 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gabrielschulhof left a comment

Choose a reason for hiding this comment

Uh oh!

NickNaso commented Jun 12, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mhdawson left a comment

Choose a reason for hiding this comment

Uh oh!

mhdawson commented Jun 14, 2018

Uh oh!

webern left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

mhdawson May 17, 2018 •

edited

Loading

mhdawson May 17, 2018 •

edited

Loading

gabrielschulhof Jun 6, 2018 •

edited

Loading

gabrielschulhof Jun 6, 2018 •

edited

Loading