-
Notifications
You must be signed in to change notification settings - Fork 461
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
Changes from 17 commits
825440a
d11cd21
178dd33
794ee4d
3eae5e1
8cc39be
b79abf0
bfdd76f
83103eb
b46fd8d
be01a86
c7eb8cb
5793481
977cf1f
fce33d1
1c87b82
5a3cc85
c5906f2
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,23 @@ | ||
# Asynchronous operations | ||
|
||
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 | ||
blocking the **event loop** they have to run them asynchronously from the | ||
**event loop**. | ||
In the Node.js model of execution the event loop thread represents the thread | ||
where JavaScript code is 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 interface to support functions that cover | ||
the most common asynchronous use cases. There is an abstract classes to implement | ||
asynchronous operations: | ||
|
||
- **[AsyncWorker](async_worker.md)** | ||
|
||
These class helps manage asynchronous operations through an abstraction | ||
of the concept of moving data between the **event loop** and **worker threads**. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,306 @@ | ||
# Async worker | ||
# AsyncWorker | ||
|
||
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 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. | ||
|
||
Once created, execution is requested by calling `Queue`. When a thread is | ||
available for execution the `Execute` method will be invoked. Once `Execute` | ||
complets either `OnOK` or `OnError` will be invoked. Once the `OnOK` or | ||
`OnError` methods are complete the AsyncWorker instance is destructed. | ||
|
||
For the most basic use, only the `Execute` method must be implemented in a | ||
subclass. | ||
|
||
## Methods | ||
|
||
### Env | ||
|
||
Requests the environment in which the async worker has been initially created. | ||
|
||
```cpp | ||
Env Env() const; | ||
``` | ||
|
||
Returns the environment in which the async worker has been created. | ||
|
||
### Queue | ||
|
||
Requests that the work be queued for execution. | ||
|
||
```cpp | ||
void Queue(); | ||
``` | ||
|
||
### Cancel | ||
|
||
Cancels queued work if it has not yet been started. If it has already started | ||
executing, it cannot be cancelled. If cancelled successfully neither | ||
`OnOK` nor `OnError` will be called. | ||
|
||
```cpp | ||
void Cancel(); | ||
``` | ||
|
||
### Receiver | ||
|
||
```cpp | ||
ObjectReference& Receiver(); | ||
``` | ||
|
||
Returns the persistent object reference of the receiver object set when the async | ||
worker was created. | ||
|
||
### Callback | ||
|
||
```cpp | ||
FunctionReference& Callback(); | ||
``` | ||
|
||
Returns the persistent function reference of the callback set when the async | ||
worker was created. The returned function reference will receive the results of | ||
the computation that happened in the `Execute` method, unless the default | ||
implementation of `OnOK` or `OnError` is overridden. | ||
|
||
### SetError | ||
|
||
Sets the error message for the error that happened during the execution. Setting | ||
an error message will cause the `OnError` method to be invoked instead of `OnOK` | ||
once the `Execute` method completes. | ||
|
||
```cpp | ||
void SetError(const std::string& 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think I covered that with As the method is not |
||
worker thread. Subclasses must implement this method and the method is run on | ||
a thread other than that running the main event loop. 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. Instead once this method is | ||
complete any interactive through node-addon-api with JavaScript should be implemented | ||
in the `OnOK` method which runs on the main thread and is invoked when the `Execute` | ||
method completes. | ||
|
||
```cpp | ||
virtual void Execute() = 0; | ||
``` | ||
|
||
### OnOK | ||
|
||
This method is invoked when the computation in the `Excecute` method ends. | ||
The default implementation runs the Callback provided when the AsyncWorker class | ||
was created. | ||
|
||
```cpp | ||
virtual void OnOK(); | ||
``` | ||
|
||
### OnError | ||
|
||
This method is invoked afer Execute() completes if an error occurs | ||
while `Execute` is running and C++ exceptions are enabled or if an | ||
error was set through a call to `SetError`. The default implementation | ||
calls the callback provided when the AsyncWorker class was created, passing | ||
in the error as the first parameter. | ||
|
||
```cpp | ||
virtual void OnError(const Error& e); | ||
``` | ||
|
||
### Constructor | ||
|
||
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. | ||
|
||
Returns an AsyncWork instance which can later be queued for execution by calling | ||
`Queue`. | ||
|
||
### Constructor | ||
|
||
Creates a new `AsyncWorker`. | ||
|
||
```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. | ||
|
||
Returns an AsyncWork instance which can later be queued for execution by calling | ||
`Queue`. | ||
|
||
|
||
### Constructor | ||
|
||
Creates a new `AsyncWorker`. | ||
|
||
```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. | ||
|
||
Returns an AsyncWork instance which can later be queued for execution by calling | ||
`Queue`. | ||
|
||
### Constructor | ||
|
||
Creates a new `AsyncWorker`. | ||
|
||
```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. | ||
|
||
Returns an AsyncWork instance which can later be queued for execution by calling | ||
`Queue`. | ||
|
||
|
||
### Constructor | ||
|
||
Creates a new `AsyncWorker`. | ||
|
||
```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. | ||
|
||
Returns an AsyncWork instance which can later be queued for execution by calling | ||
`Queue`. | ||
|
||
|
||
### Constructor | ||
|
||
Creates a new `AsyncWorker`. | ||
|
||
```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. | ||
|
||
Returns an AsyncWork instance which can later be queued for execution by calling | ||
`Queue`. | ||
|
||
### Destructor | ||
|
||
Deletes the created work object that is used to execute logic asynchronously. | ||
|
||
```cpp | ||
virtual ~AsyncWorker(); | ||
``` | ||
|
||
## Operator | ||
|
||
```cpp | ||
operator napi_async_work() const; | ||
``` | ||
|
||
Returns the N-API napi_async_work wrapped by the AsyncWorker object. This can be | ||
used to mix usage of the C N-API and node-addon-api. | ||
|
||
## Example | ||
|
||
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 class' fields generally passed in through its | ||
constructor. | ||
|
||
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 the initial JavaScript context. | ||
|
||
`AsyncWorker` ensures 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` the implementation: | ||
|
||
```cpp | ||
#include<napi.h> | ||
|
||
#include <chrono> | ||
#include <thread> | ||
|
||
use namespace Napi; | ||
|
||
class EchoWorker : public AsyncWorker { | ||
public: | ||
EchoWorker(Function& callback, std::string& echo) | ||
: AsyncWorker(callback), echo(echo) {} | ||
|
||
~EchoWorker() {} | ||
// This code will be executed on the worker thread | ||
void Execute() { | ||
// Need to simulate cpu heavy task | ||
std::this_thread::sleep_for(std::chrono::seconds(1)); | ||
} | ||
|
||
void OnOK() { | ||
HandleScope scope(Env()); | ||
Callback().Call({Env().Null(), String::New(Env(), echo)}); | ||
} | ||
|
||
private: | ||
std::string echo; | ||
}; | ||
``` | ||
|
||
The `EchoWorker`'s contructor calls 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 shows an example on how to create and and use an `AsyncWorker` | ||
|
||
```cpp | ||
Value Echo(const CallbackInfo& info) { | ||
// You need to check the input data here | ||
Function cb = info[1].As<Function>(); | ||
std::string in = info[0].As<String>(); | ||
EchoWorker* wk = new EchoWorker(cb, in); | ||
wk->Queue(); | ||
return info.Env().Undefined(); | ||
``` | ||
|
||
Using the implementation of an `AsyncWorker` is straight forward. 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. Once created the | ||
only other action you have to do is to call the `Queue` method that will that will | ||
queue the created worker for execution. |
There was a problem hiding this comment.
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.