Async worker and error handling documentation #272

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

doc/async_operations.md

remove of

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

doc/async_operations.md

+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

doc/async_operations.md

+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

doc/async_operations.md

+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

doc/async_operations.md

+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

doc/async_operations.md

+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

doc/async_operations.md

+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

doc/async_operations.md

+completed.
+
+Node Addon API provides an ABI-stable interface to support functions which covers


"~~which covers~~that cover"

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

doc/async_operations.md

+
+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

doc/async_operations.md

+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

doc/async_operations.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

doc/async_worker.md

"~~much~~many"

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

doc/async_worker.md

+`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

doc/async_worker.md

+`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

doc/async_worker.md

+### 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

doc/async_worker.md

+```
+
+Returns the persistent object reference of the receiver objet set when the async


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

doc/async_worker.md

+
+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

doc/async_operations.md

+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

doc/async_worker.md

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


nit: "Creates a new AsyncWorker"

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

doc/async_worker.md

@@ -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

doc/async_worker.md

+### 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Async worker and error handling documentation #272

Async worker and error handling documentation #272

NickNaso commented May 17, 2018

mhdawson May 17, 2018

mhdawson May 17, 2018 •

edited

Loading

mhdawson May 17, 2018 •

edited

Loading

mhdawson May 17, 2018

mhdawson May 17, 2018

mhdawson May 17, 2018

mhdawson May 17, 2018

NickNaso commented May 21, 2018

NickNaso commented May 22, 2018

mhdawson commented May 25, 2018

gabrielschulhof Jun 6, 2018

gabrielschulhof Jun 6, 2018

gabrielschulhof Jun 6, 2018 •

edited

Loading

gabrielschulhof Jun 6, 2018

gabrielschulhof Jun 6, 2018 •

edited

Loading

gabrielschulhof Jun 6, 2018

gabrielschulhof Jun 6, 2018

gabrielschulhof Jun 6, 2018

gabrielschulhof Jun 6, 2018

gabrielschulhof Jun 6, 2018

gabrielschulhof Jun 6, 2018

gabrielschulhof left a comment

NickNaso commented Jun 12, 2018

kfarnung Jun 12, 2018

NickNaso Jun 12, 2018

kfarnung Jun 12, 2018

kfarnung Jun 12, 2018

webern Jun 14, 2018

mhdawson left a comment

mhdawson commented Jun 14, 2018

webern left a comment

webern Jun 14, 2018

mhdawson Jun 14, 2018

mhdawson commented Jun 14, 2018

		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.

		completed.

		Node Addon API provides an ABI-stable interface to support functions which covers


		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

		- [Async Context](async_context.md)

		These two classes help you to manage asynchronous operations through an abstraction

		`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

		### Queue

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

		```

		Returns the persistent object reference of the receiver objet set when the async


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

		### Execute

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

Async worker and error handling documentation #272

Async worker and error handling documentation #272

Conversation

NickNaso commented May 17, 2018

Choose a reason for hiding this comment

mhdawson May 17, 2018 • edited Loading

Choose a reason for hiding this comment

mhdawson May 17, 2018 • edited Loading

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

NickNaso commented May 21, 2018

NickNaso commented May 22, 2018

mhdawson commented May 25, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gabrielschulhof Jun 6, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gabrielschulhof Jun 6, 2018 • edited Loading

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

gabrielschulhof left a comment

Choose a reason for hiding this comment

NickNaso commented Jun 12, 2018

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

mhdawson left a comment

Choose a reason for hiding this comment

mhdawson commented Jun 14, 2018

webern left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhdawson commented Jun 14, 2018

mhdawson May 17, 2018 •

edited

Loading

mhdawson May 17, 2018 •

edited

Loading

gabrielschulhof Jun 6, 2018 •

edited

Loading

gabrielschulhof Jun 6, 2018 •

edited

Loading