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.

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

Async worker and error handling documentation #272

Closed
wants to merge 18 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
Fixed errors reported in the first review and added some missing part…
…s about constructor
  • Loading branch information
NickNaso committed Jun 11, 2018
commit 83103ebfcc1248ec0f09a8c72e0ce8c6e20b4504
12 changes: 6 additions & 6 deletions doc/async_operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,20 @@ 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
Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

Choose a reason for hiding this comment

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

I think that's better.

**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
event loop by. Therefore, we need to do this work on another thread.
executing. The node.js guidance is to avoid blocking other work queued on the
event loop thread. Therefore, we need to do this work on another thread.

All this means that native add-ons need to leverage async helpers from libuv as
part of their implementation. This allows them to schedule work to be executed
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
the most common asynchronous use cases. You have two abstract class to implement
asynchronous operation:
Node Addon API provides an ABI-stable interface to support functions that cover
the most common asynchronous use cases. There are abstract classes to implement
asynchronous operations:

- **[AsyncWorker](async_worker.md)**
- **[Async Context](async_context.md)**

These two classes help you to manage asynchronous operations through an abstraction
These two classes help manage asynchronous operations through an abstraction
of the concept of moving data between the **event loop** and **worker threads**.
132 changes: 100 additions & 32 deletions doc/async_worker.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# AsyncWorker
Copy link

Choose a reason for hiding this comment

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

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.


`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
`AsyncWorker` is an abstract class that you can subclass to remove many of the
tedious tasks of moving data between the event loop and worker threads. This
class internally handles all the details of creating and executing an asynchronous
operation.

## Methods
Expand All @@ -19,7 +19,7 @@ Returns the environment in which the async worker has been created.

### Queue

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

```cpp
void Queue();
Expand All @@ -40,8 +40,8 @@ void Cancel();
ObjectReference& Receiver();
```

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

### Callback

Expand All @@ -50,33 +50,32 @@ FunctionReference& Callback();
```

Returns the persistent function reference of the callback set when the async
worker is created. The returned function reference will be called passing it the
results of the computation happened on the `Execute` method.
worker was created. The returned function reference will receive the results of
the computation that happened in the `Execute` method.

### SetError

Sets the error message for the error happened during the execution.
Sets the error message for the error that happened during the execution.

```cpp
void SetError(const std::string& error);
```

- `[in] error`: The reference to string that represent the message of the error.

- `[in] error`: The reference to the string that represent the message of the error.

### Execute

This method is used to execute some tasks out of the **event loop** on a libuv
worker thread.
This method is used to execute some tasks out of the **event loop** on a libuv
Copy link

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

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.

worker thread.

```cpp
virtual void Execute() = 0;
```

### OnOK

This method represents a callback that is invoked when the computation on the
`Excecute` method end.
This method represents a callback that is invoked when the computation in the
`Excecute` method ends.

```cpp
virtual void OnOK();
Expand All @@ -90,23 +89,92 @@ virtual void OnError(const Error& e);

### Constructor

Creates new async worker
Creates new async worker.
Copy link
Contributor

Choose a reason for hiding this comment

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

nit: "Creates a new AsyncWorker"


```cpp
explicit AsyncWorker(const Function& callback);
```

- ```[in] callback```: The function which will be called when an asynchronous
operations ends. The given function is called from the main event loop thread.

### Constructor

Creates new async worker.

```cpp
explicit AsyncWorker(const Function& callback, const char* resource_name);
```

- ```[in] callback```: The function which will be called when an asynchronous
operations ends. The given function is called from the main event loop thread.
- ```[in] resource_name```: Null-terminated strings that represents the
identifier for the kind of resource that is being provided for diagnostic
information exposed by the async_hooks API.

### Constructor

Creates new async worker.

```cpp
explicit AsyncWorker(const Function& callback, const char* resource_name, const Object& resource);
```

- ```[in] callback```: The function which will be called when an asynchronous
operations ends. The given function is called from the main event loop thread.
- ```[in] resource_name```: Null-terminated strings that represents the
identifier for the kind of resource that is being provided for diagnostic
information exposed by the async_hooks API.
- ```[in] resource```: Object associated with the asynchronous operation that
will be passed to possible async_hooks.

### Constructor

Creates new async worker
Creates new async worker.

```cpp
explicit AsyncWorker(const Object& receiver, const Function& callback);
```

- ```[in] receiver```: The `this` object passed to the called function.
- ```[in] callback```: The function which will be called when an asynchronous
operations ends. The given function is called from the main event loop thread.

### Constructor

Creates new async worker.

```cpp
explicit AsyncWorker(const Object& receiver, const Function& callback,const char* resource_name);
```

- ```[in] receiver```: The `this` object passed to the called function.
- ```[in] callback```: The function which will be called when an asynchronous
operations ends. The given function is called from the main event loop thread.
- ```[in] resource_name```: Null-terminated strings that represents the
identifier for the kind of resource that is being provided for diagnostic
information exposed by the async_hooks API.

### Constructor

Creates new async worker.

```cpp
explicit AsyncWorker(const Object& receiver, const Function& callback, const char* resource_name, const Object& resource);
```

- ```[in] receiver```: The `this` object passed to the called function.
- ```[in] callback```: The function which will be called when an asynchronous
operations ends. The given function is called from the main event loop thread.
- ```[in] resource_name```: Null-terminated strings that represents the
identifier for the kind of resource that is being provided for diagnostic
information exposed by the async_hooks API.
- ```[in] resource```: Object associated with the asynchronous operation that
will be passed to possible async_hooks.

### Destructor

Deletes the created work object that is used to execute logic asynchronously
Deletes the created work object that is used to execute logic asynchronously.

```cpp
virtual ~AsyncWorker();
Expand All @@ -123,20 +191,20 @@ used to mix usage of the C N-API and node-addon-api.

## Example

The first step to use `AsyncWorker` class is to create a new class that inherit
The first step to use the `AsyncWorker` class is to create a new class that inherit
from it and implement the `Execute` abstract method. Typically input to your
worker will be saved within your fields' class generally passed in through its
worker will be saved within class' fields generally passed in through its
constructor.

When the `Execute` method complete without errors the `OnOK` function callback
When the `Execute` method completes without errors the `OnOK` function callback
will be invoked. In this function the results of the computation will be
reassembled and returned back to initial JavaScript context.
reassembled and returned back to the initial JavaScript context.

`AsyncWorker` ensure that all the code inside in the `Execute` function runs in
background out of the **event loop** thread and at the end `OnOK` or `OnError`
`AsyncWorker` ensure that all the code in the `Execute` function runs in the
background out of the **event loop** thread and at the end the `OnOK` or `OnError`
function will be called and are executed as part of the event loop.

The code below show a basic example of `AsyncWorker` implementation:
The code below show a basic example of `AsyncWorker` the implementation:

```cpp
#include<napi.h>
Expand Down Expand Up @@ -168,12 +236,12 @@ class EchoWorker : public AsyncWorker {
};
```

The `EchoWorker`'s contructor call the base class's constructor to pass in the
The `EchoWorker`'s contructor call the base class' constructor to pass in the
callback that the `AsyncWorker` base class will store persistently. When the work
on the `Execute` method is done the `OnOk` method is called and the results return
back to JavaScript invoking the stored callback with its associated environment.

The following code show an example on how to create and and use an `AsyncWorker`
The following code shows an example on how to create and and use an `AsyncWorker`

```cpp
Value Echo(const CallbackInfo& info) {
Expand All @@ -185,8 +253,8 @@ Value Echo(const CallbackInfo& info) {
return info.Env().Undefined();
```

Use the implementation of an `AsyncWorker` is very simple you need only to
create a new instance and pass to its constructor the callback you want exectute
when your asynchronous task end and other data you need for your computation. The
only action you have to do is to call the `Queue` method that will place the
crearted worker on the queue of the execution.
Using the implementation of an `AsyncWorker` is very simple. You need only create
a new instance and pass to its constructor the callback you want to execute when
your asynchronous task ends and other data you need for your computation. The
only action you have to do is to call the `Queue` method that will that will
queue the created worker for execution.