Skip to content

Commit 5c11a56

Browse files
legendecaslegendecas
committed
Implement AsyncProgressWorker
1 parent dd9fa8a commit 5c11a56

File tree

8 files changed

+676
-0
lines changed

8 files changed

+676
-0
lines changed

‎doc/async_progress_worker.md

Lines changed: 343 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,343 @@
1+
# AsyncProgressWorker
2+
3+
`Napi::AsyncProgressWorker` is an abstract class, which implements `Napi::AsyncWorker`
4+
while extending `Napi::AsyncWorker` internally with `Napi::ThreadSafeFunction` for
5+
moving work progress reports from worker thread(s) to event loop threads.
6+
7+
Like `Napi::AsyncWorker`, once created, execution is requested by calling
8+
`Napi::AsyncProgressWorker::Queue`. When a thread is available for execution
9+
the `Napi::AsyncProgressWorker::Execute` method will be invoked. During the
10+
execution, `Napi::AsyncProgressWorker::ExecutionProgress::Send` can be used to
11+
indicate execution process, which would eventually invoke `Napi::AsyncProgressWorker::OnProgress`
12+
on the JavaScript thread to safely call into JavaScript. Once `Napi::AsyncProgressWorker::Execute`
13+
completes either `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError`
14+
will be invoked. Once the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError`
15+
methods are complete the `Napi::AsyncProgressWorker` instance is destructed.
16+
17+
For the most basic use, only the `Napi::AsyncProgressWorker::Execute` and
18+
`Napi::AsyncProgressWorker::OnProgress` method must be implemented in a subclass.
19+
20+
## Methods
21+
22+
[`Napi::AsyncWorker`]() provides detailed descriptions for most methods.
23+
24+
### Execute
25+
26+
This method is used to execute some tasks outside of the **event loop** on a libuv
27+
worker thread. Subclasses must implement this method and the method is run on
28+
a thread other than that running the main event loop. As the method is not
29+
running on the main event loop, it must avoid calling any methods from node-addon-api
30+
or running any code that might invoke JavaScript. Instead, once this method is
31+
complete any interaction through node-addon-api with JavaScript should be implemented
32+
in the `Napi::AsyncProgressWorker::OnOK` method or `Napi::AsyncProgressWorker::OnError`
33+
which run on the main thread and are invoked when the `Napi::AsyncProgressWorker::Execute`
34+
method completes.
35+
36+
```cpp
37+
virtual void Napi::AsyncProgressWorker::Execute(const ExecutionProgress& progress) = 0;
38+
```
39+
40+
### OnOK
41+
42+
This method is invoked when the computation in the `Execute` method ends.
43+
The default implementation runs the `Callback` optionally provided when the
44+
`AsyncProgressWorker` class was created. The `Callback` will by default receive no
45+
arguments. Arguments to the callback can be provided by overriding the `GetResult()`
46+
method.
47+
48+
```cpp
49+
virtual void Napi::AsyncProgressWorker::OnOK();
50+
```
51+
52+
### OnProgress
53+
54+
This method is invoked when the computation in the `Napi::AsyncProgressWorker::ExecutionProcess::Send`
55+
method was called during worker thread execution.
56+
57+
```cpp
58+
virtual void Napi::AsyncProgressWorker::OnProgress(const T* data, size_t count)
59+
```
60+
61+
### Constructor
62+
63+
Creates a new `Napi::AsyncProgressWorker`.
64+
65+
```cpp
66+
explicit Napi::AsyncProgressWorker(const Napi::Function& callback);
67+
```
68+
69+
- `[in] callback`: The function which will be called when an asynchronous
70+
operations ends. The given function is called from the main event loop thread.
71+
72+
Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
73+
calling `Napi::AsyncWork::Queue`.
74+
75+
### Constructor
76+
77+
Creates a new `Napi::AsyncProgressWorker`.
78+
79+
```cpp
80+
explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name);
81+
```
82+
83+
- `[in] callback`: The function which will be called when an asynchronous
84+
operations ends. The given function is called from the main event loop thread.
85+
- `[in] resource_name`: Null-terminated string that represents the
86+
identifier for the kind of resource that is being provided for diagnostic
87+
information exposed by the async_hooks API.
88+
89+
Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
90+
calling `Napi::AsyncWork::Queue`.
91+
92+
### Constructor
93+
94+
Creates a new `Napi::AsyncProgressWorker`.
95+
96+
```cpp
97+
explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name, const Napi::Object& resource);
98+
```
99+
100+
- `[in] callback`: The function which will be called when an asynchronous
101+
operations ends. The given function is called from the main event loop thread.
102+
- `[in] resource_name`: Null-terminated string that represents the
103+
identifier for the kind of resource that is being provided for diagnostic
104+
information exposed by the async_hooks API.
105+
- `[in] resource`: Object associated with the asynchronous operation that
106+
will be passed to possible async_hooks.
107+
108+
Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
109+
calling `Napi::AsyncWork::Queue`.
110+
111+
### Constructor
112+
113+
Creates a new `Napi::AsyncProgressWorker`.
114+
115+
```cpp
116+
explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback);
117+
```
118+
119+
- `[in] receiver`: The `this` object passed to the called function.
120+
- `[in] callback`: The function which will be called when an asynchronous
121+
operations ends. The given function is called from the main event loop thread.
122+
123+
Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
124+
calling `Napi::AsyncWork::Queue`.
125+
126+
### Constructor
127+
128+
Creates a new `Napi::AsyncProgressWorker`.
129+
130+
```cpp
131+
explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name);
132+
```
133+
134+
- `[in] receiver`: The `this` object passed to the called function.
135+
- `[in] callback`: The function which will be called when an asynchronous
136+
operations ends. The given function is called from the main event loop thread.
137+
- `[in] resource_name`: Null-terminated string that represents the
138+
identifier for the kind of resource that is being provided for diagnostic
139+
information exposed by the async_hooks API.
140+
141+
Returns a `Napi::AsyncWork` instance which can later be queued for execution by
142+
calling `Napi::AsyncWork::Queue`.
143+
144+
### Constructor
145+
146+
Creates a new `Napi::AsyncProgressWorker`.
147+
148+
```cpp
149+
explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name, const Napi::Object& resource);
150+
```
151+
152+
- `[in] receiver`: The `this` object passed to the called function.
153+
- `[in] callback`: The function which will be called when an asynchronous
154+
operations ends. The given function is called from the main event loop thread.
155+
- `[in] resource_name`: Null-terminated string that represents the
156+
identifier for the kind of resource that is being provided for diagnostic
157+
information exposed by the async_hooks API.
158+
- `[in] resource`: Object associated with the asynchronous operation that
159+
will be passed to possible async_hooks.
160+
161+
Returns a `Napi::AsyncWork` instance which can later be queued for execution by
162+
calling `Napi::AsyncWork::Queue`.
163+
164+
### Constructor
165+
166+
Creates a new `Napi::AsyncProgressWorker`.
167+
168+
```cpp
169+
explicit Napi::AsyncProgressWorker(Napi::Env env);
170+
```
171+
172+
- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
173+
174+
Returns an `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling
175+
`Napi::AsyncProgressWorker::Queue`.
176+
177+
Available with `NAPI_VERSION` equal to or greater than 5.
178+
179+
### Constructor
180+
181+
Creates a new `Napi::AsyncProgressWorker`.
182+
183+
```cpp
184+
explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name);
185+
```
186+
187+
- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
188+
- `[in] resource_name`: Null-terminated string that represents the
189+
identifier for the kind of resource that is being provided for diagnostic
190+
information exposed by the async_hooks API.
191+
192+
Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
193+
calling `Napi::AsyncProgressWorker::Queue`.
194+
195+
Available with `NAPI_VERSION` equal to or greater than 5.
196+
197+
### Constructor
198+
199+
Creates a new `Napi::AsyncProgressWorker`.
200+
201+
```cpp
202+
explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource);
203+
```
204+
205+
- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
206+
- `[in] resource_name`: Null-terminated string that represents the
207+
identifier for the kind of resource that is being provided for diagnostic
208+
information exposed by the async_hooks API.
209+
- `[in] resource`: Object associated with the asynchronous operation that
210+
will be passed to possible async_hooks.
211+
212+
Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
213+
calling `Napi::AsyncProgressWorker::Queue`.
214+
215+
Available with `NAPI_VERSION` equal to or greater than 5.
216+
217+
### Destructor
218+
219+
Deletes the created work object that is used to execute logic asynchronously and
220+
release the internal `Napi::ThreadSafeFunction`, which would be aborted to prevent
221+
unexpected upcoming thread safe calls.
222+
223+
```cpp
224+
virtual Napi::AsyncProgressWorker::~AsyncProgressWorker();
225+
```
226+
227+
# AsyncProgressWorker::ExecutionProcess
228+
229+
A bridge class created before the worker thread execution of `Napi::AsyncProgressWorker::Execute`.
230+
231+
## Methods
232+
233+
### Send
234+
235+
`Napi::AsyncProgressWorker::ExecutionProcess::Send` takes two arguments, a pointer
236+
to a generic type of data, and a `size_t` to indicate how many items the pointer is pointed to.
237+
238+
The data pointed to will be copied to internal slots of `Napi::AsyncProgressWorker` so
239+
after the call to `Napi::AsyncProgressWorker::ExecutionProcess::Send` the data can
240+
be safely released.
241+
242+
Note that `Napi::AsyncProgressWorker::ExecutionProcess::Send` merely guarantees
243+
**eventual** invocation of `Napi::AsyncProgressWorker::OnProgress`, which means
244+
multiple send might be coalesced into single invocation of `Napi::AsyncProgressWorker::OnProgress`
245+
with latest data.
246+
247+
```cpp
248+
void Napi::AsyncProgressWorker::ExecutionProcess::Send(const T* data, size_t count) const;
249+
```
250+
251+
## Example
252+
253+
The first step to use the `Napi::AsyncProgressWorker` class is to create a new class that
254+
inherits from it and implement the `Napi::AsyncProgressWorker::Execute` abstract method.
255+
Typically input to your worker will be saved within the class' fields generally
256+
passed in through its constructor.
257+
258+
During the worker thread execution, the first argument of `Napi::AsyncProgressWorker::Execute`
259+
can be used to report the process of the execution.
260+
261+
When the `Napi::AsyncProgressWorker::Execute` method completes without errors the
262+
`Napi::AsyncProgressWorker::OnOK` function callback will be invoked. In this function the
263+
results of the computation will be reassembled and returned back to the initial
264+
JavaScript context.
265+
266+
`Napi::AsyncProgressWorker` ensures that all the code in the `Napi::AsyncProgressWorker::Execute`
267+
function runs in the background out of the **event loop** thread and at the end
268+
the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` function will be
269+
called and are executed as part of the event loop.
270+
271+
The code below shows a basic example of `Napi::AsyncProgressWorker` the implementation:
272+
273+
```cpp
274+
#include<napi.h>
275+
276+
#include <chrono>
277+
#include <thread>
278+
279+
use namespace Napi;
280+
281+
class EchoWorker : public AsyncProgressWorker<uint32_t> {
282+
public:
283+
EchoWorker(Function& callback, std::string& echo)
284+
: AsyncProgressWorker(callback), echo(echo) {}
285+
286+
~EchoWorker() {}
287+
// This code will be executed on the worker thread
288+
void Execute(const ExecutionProgress& progress) {
289+
// Need to simulate cpu heavy task
290+
for (uint32_t i = 0; i < 100; ++i) {
291+
progress.Send(&i, 1)
292+
std::this_thread::sleep_for(std::chrono::seconds(1));
293+
}
294+
}
295+
296+
void OnOK() {
297+
HandleScope scope(Env());
298+
Callback().Call({Env().Null(), String::New(Env(), echo)});
299+
}
300+
301+
void OnProgress(const uint32_t* data, size_t /* count */) {
302+
HandleScope scope(Env());
303+
Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)});
304+
}
305+
306+
private:
307+
std::string echo;
308+
};
309+
```
310+
311+
The `EchoWorker`'s contructor calls the base class' constructor to pass in the
312+
callback that the `Napi::AsyncProgressWorker` base class will store persistently. When
313+
the work on the `Napi::AsyncProgressWorker::Execute` method is done the
314+
`Napi::AsyncProgressWorker::OnOk` method is called and the results return back to
315+
JavaScript invoking the stored callback with its associated environment.
316+
317+
The following code shows an example of how to create and use an `Napi::AsyncProgressWorker`
318+
319+
```cpp
320+
#include<napi.h>
321+
322+
// Include EchoWorker class
323+
// ..
324+
325+
use namespace Napi;
326+
327+
Value Echo(const CallbackInfo& info) {
328+
// You need to validate the arguments here
329+
Function cb = info[1].As<Function>();
330+
std::string in = info[0].As<String>();
331+
EchoWorker* wk = new EchoWorker(cb, in);
332+
wk->Queue();
333+
return info.Env().Undefined();
334+
}
335+
```
336+
337+
Using the implementation of a `Napi::AsyncProgressWorker` is straight forward. You only
338+
need to create a new instance and pass to its constructor the callback you want to
339+
execute when your asynchronous task ends and other data you need for your
340+
computation. Once created the only other action you have to do is to call the
341+
`Napi::AsyncProgressWorker::Queue` method that will queue the created worker for execution.
342+
343+
[`Napi::AsyncWorker`]: ./async_worker.md

0 commit comments

Comments
 (0)