-
Notifications
You must be signed in to change notification settings - Fork 465
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 1 commit
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
…s about constructor
- Loading branch information
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,8 +1,8 @@ | ||
# AsyncWorker | ||
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. 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 | ||
|
@@ -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(); | ||
|
@@ -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 | ||
|
||
|
@@ -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 | ||
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. | ||
|
||
```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(); | ||
|
@@ -90,23 +89,92 @@ virtual void OnError(const Error& e); | |
|
||
### Constructor | ||
|
||
Creates new async worker | ||
Creates new async worker. | ||
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. nit: "Creates a new |
||
|
||
```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(); | ||
|
@@ -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> | ||
|
@@ -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) { | ||
|
@@ -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. |
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.
Are there actually two threads? There's the main event loop thread that's constant and worker threads as needed.
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.
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.
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.
I think that's better.