node-addon-api 1.7.2 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.travis.yml +3 -9
- package/CHANGELOG.md +154 -9
- package/README.md +58 -9
- package/benchmark/README.md +47 -0
- package/benchmark/binding.gyp +25 -0
- package/benchmark/function_args.cc +153 -0
- package/benchmark/function_args.js +52 -0
- package/benchmark/index.js +34 -0
- package/benchmark/property_descriptor.cc +60 -0
- package/benchmark/property_descriptor.js +29 -0
- package/common.gypi +21 -0
- package/doc/array_buffer.md +1 -1
- package/doc/async_context.md +10 -0
- package/doc/async_operations.md +1 -1
- package/doc/async_worker.md +56 -26
- package/doc/async_worker_variants.md +456 -0
- package/doc/basic_types.md +8 -0
- package/doc/bigint.md +2 -1
- package/doc/class_property_descriptor.md +5 -6
- package/doc/cmake-js.md +58 -9
- package/doc/creating_a_release.md +5 -5
- package/doc/date.md +68 -0
- package/doc/env.md +14 -0
- package/doc/function.md +108 -1
- package/doc/object.md +74 -1
- package/doc/object_lifetime_management.md +1 -1
- package/doc/object_wrap.md +291 -4
- package/doc/prebuild_tools.md +1 -1
- package/doc/property_descriptor.md +64 -9
- package/doc/setup.md +0 -1
- package/doc/string.md +1 -1
- package/doc/symbol.md +1 -1
- package/doc/threadsafe_function.md +18 -1
- package/doc/value.md +10 -1
- package/except.gypi +16 -0
- package/index.js +5 -42
- package/napi-inl.h +1048 -147
- package/napi.h +424 -49
- package/node_api.gyp +9 -0
- package/noexcept.gypi +16 -0
- package/{src/nothing.c → nothing.c} +0 -0
- package/package.json +244 -47
- package/tools/README.md +4 -4
- package/tools/conversion.js +0 -4
- package/external-napi/node_api.h +0 -7
- package/src/node_api.cc +0 -3655
- package/src/node_api.gyp +0 -21
- package/src/node_api.h +0 -588
- package/src/node_api_types.h +0 -115
- package/src/node_internals.cc +0 -142
- package/src/node_internals.h +0 -157
- package/src/util-inl.h +0 -38
- package/src/util.h +0 -7
|
@@ -0,0 +1,456 @@
|
|
|
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 will 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 and/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 to be 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 will 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
|
|
237
|
+
pointing to.
|
|
238
|
+
|
|
239
|
+
The data pointed to will be copied to internal slots of `Napi::AsyncProgressWorker` so
|
|
240
|
+
after the call to `Napi::AsyncProgressWorker::ExecutionProcess::Send` the data can
|
|
241
|
+
be safely released.
|
|
242
|
+
|
|
243
|
+
Note that `Napi::AsyncProgressWorker::ExecutionProcess::Send` merely guarantees
|
|
244
|
+
**eventual** invocation of `Napi::AsyncProgressWorker::OnProgress`, which means
|
|
245
|
+
multiple send might be coalesced into single invocation of `Napi::AsyncProgressWorker::OnProgress`
|
|
246
|
+
with latest data.
|
|
247
|
+
|
|
248
|
+
```cpp
|
|
249
|
+
void Napi::AsyncProgressWorker::ExecutionProcess::Send(const T* data, size_t count) const;
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
## Example
|
|
253
|
+
|
|
254
|
+
The first step to use the `Napi::AsyncProgressWorker` class is to create a new class that
|
|
255
|
+
inherits from it and implement the `Napi::AsyncProgressWorker::Execute` abstract method.
|
|
256
|
+
Typically input to the worker will be saved within the class' fields generally
|
|
257
|
+
passed in through its constructor.
|
|
258
|
+
|
|
259
|
+
During the worker thread execution, the first argument of `Napi::AsyncProgressWorker::Execute`
|
|
260
|
+
can be used to report the progress of the execution.
|
|
261
|
+
|
|
262
|
+
When the `Napi::AsyncProgressWorker::Execute` method completes without errors the
|
|
263
|
+
`Napi::AsyncProgressWorker::OnOK` function callback will be invoked. In this function the
|
|
264
|
+
results of the computation will be reassembled and returned back to the initial
|
|
265
|
+
JavaScript context.
|
|
266
|
+
|
|
267
|
+
`Napi::AsyncProgressWorker` ensures that all the code in the `Napi::AsyncProgressWorker::Execute`
|
|
268
|
+
function runs in the background out of the **event loop** thread and at the end
|
|
269
|
+
the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` function will be
|
|
270
|
+
called and are executed as part of the event loop.
|
|
271
|
+
|
|
272
|
+
The code below shows a basic example of the `Napi::AsyncProgressWorker` implementation:
|
|
273
|
+
|
|
274
|
+
```cpp
|
|
275
|
+
#include <napi.h>
|
|
276
|
+
|
|
277
|
+
#include <chrono>
|
|
278
|
+
#include <thread>
|
|
279
|
+
|
|
280
|
+
using namespace Napi;
|
|
281
|
+
|
|
282
|
+
class EchoWorker : public AsyncProgressWorker<uint32_t> {
|
|
283
|
+
public:
|
|
284
|
+
EchoWorker(Function& callback, std::string& echo)
|
|
285
|
+
: AsyncProgressWorker(callback), echo(echo) {}
|
|
286
|
+
|
|
287
|
+
~EchoWorker() {}
|
|
288
|
+
// This code will be executed on the worker thread
|
|
289
|
+
void Execute(const ExecutionProgress& progress) {
|
|
290
|
+
// Need to simulate cpu heavy task
|
|
291
|
+
for (uint32_t i = 0; i < 100; ++i) {
|
|
292
|
+
progress.Send(&i, 1)
|
|
293
|
+
std::this_thread::sleep_for(std::chrono::seconds(1));
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
void OnOK() {
|
|
298
|
+
HandleScope scope(Env());
|
|
299
|
+
Callback().Call({Env().Null(), String::New(Env(), echo)});
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
void OnProgress(const uint32_t* data, size_t /* count */) {
|
|
303
|
+
HandleScope scope(Env());
|
|
304
|
+
Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)});
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
private:
|
|
308
|
+
std::string echo;
|
|
309
|
+
};
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
The `EchoWorker`'s constructor calls the base class' constructor to pass in the
|
|
313
|
+
callback that the `Napi::AsyncProgressWorker` base class will store persistently. When
|
|
314
|
+
the work on the `Napi::AsyncProgressWorker::Execute` method is done the
|
|
315
|
+
`Napi::AsyncProgressWorker::OnOk` method is called and the results are return back to
|
|
316
|
+
JavaScript when the stored callback is invoked with its associated environment.
|
|
317
|
+
|
|
318
|
+
The following code shows an example of how to create and use an `Napi::AsyncProgressWorker`
|
|
319
|
+
|
|
320
|
+
```cpp
|
|
321
|
+
#include <napi.h>
|
|
322
|
+
|
|
323
|
+
// Include EchoWorker class
|
|
324
|
+
// ..
|
|
325
|
+
|
|
326
|
+
using namespace Napi;
|
|
327
|
+
|
|
328
|
+
Value Echo(const CallbackInfo& info) {
|
|
329
|
+
// We need to validate the arguments here
|
|
330
|
+
Function cb = info[1].As<Function>();
|
|
331
|
+
std::string in = info[0].As<String>();
|
|
332
|
+
EchoWorker* wk = new EchoWorker(cb, in);
|
|
333
|
+
wk->Queue();
|
|
334
|
+
return info.Env().Undefined();
|
|
335
|
+
}
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
The implementation of a `Napi::AsyncProgressWorker` can be used by creating a
|
|
339
|
+
new instance and passing to its constructor the callback to execute when the
|
|
340
|
+
asynchronous task ends and other data needed for the computation. Once created,
|
|
341
|
+
the only other action needed is to call the `Napi::AsyncProgressWorker::Queue`
|
|
342
|
+
method that will queue the created worker for execution.
|
|
343
|
+
|
|
344
|
+
# AsyncProgressQueueWorker
|
|
345
|
+
|
|
346
|
+
`Napi::AsyncProgressQueueWorker` acts exactly like `Napi::AsyncProgressWorker`
|
|
347
|
+
except that each progress committed by `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send`
|
|
348
|
+
during `Napi::AsyncProgressQueueWorker::Execute` is guaranteed to be
|
|
349
|
+
processed by `Napi::AsyncProgressQueueWorker::OnProgress` on the JavaScript
|
|
350
|
+
thread in the order it was committed.
|
|
351
|
+
|
|
352
|
+
For the most basic use, only the `Napi::AsyncProgressQueueWorker::Execute` and
|
|
353
|
+
`Napi::AsyncProgressQueueWorker::OnProgress` method must be implemented in a subclass.
|
|
354
|
+
|
|
355
|
+
# AsyncProgressQueueWorker::ExecutionProcess
|
|
356
|
+
|
|
357
|
+
A bridge class created before the worker thread execution of `Napi::AsyncProgressQueueWorker::Execute`.
|
|
358
|
+
|
|
359
|
+
## Methods
|
|
360
|
+
|
|
361
|
+
### Send
|
|
362
|
+
|
|
363
|
+
`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` takes two arguments, a pointer
|
|
364
|
+
to a generic type of data, and a `size_t` to indicate how many items the pointer is
|
|
365
|
+
pointing to.
|
|
366
|
+
|
|
367
|
+
The data pointed to will be copied to internal slots of `Napi::AsyncProgressQueueWorker` so
|
|
368
|
+
after the call to `Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` the data can
|
|
369
|
+
be safely released.
|
|
370
|
+
|
|
371
|
+
`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` guarantees invocation
|
|
372
|
+
of `Napi::AsyncProgressQueueWorker::OnProgress`, which means multiple `Send`
|
|
373
|
+
call will result in the in-order invocation of `Napi::AsyncProgressQueueWorker::OnProgress`
|
|
374
|
+
with each data item.
|
|
375
|
+
|
|
376
|
+
```cpp
|
|
377
|
+
void Napi::AsyncProgressQueueWorker::ExecutionProcess::Send(const T* data, size_t count) const;
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
## Example
|
|
381
|
+
|
|
382
|
+
The code below shows a basic example of the `Napi::AsyncProgressQueueWorker` implementation:
|
|
383
|
+
|
|
384
|
+
```cpp
|
|
385
|
+
#include <napi.h>
|
|
386
|
+
|
|
387
|
+
#include <chrono>
|
|
388
|
+
#include <thread>
|
|
389
|
+
|
|
390
|
+
using namespace Napi;
|
|
391
|
+
|
|
392
|
+
class EchoWorker : public AsyncProgressQueueWorker<uint32_t> {
|
|
393
|
+
public:
|
|
394
|
+
EchoWorker(Function& callback, std::string& echo)
|
|
395
|
+
: AsyncProgressQueueWorker(callback), echo(echo) {}
|
|
396
|
+
|
|
397
|
+
~EchoWorker() {}
|
|
398
|
+
// This code will be executed on the worker thread
|
|
399
|
+
void Execute(const ExecutionProgress& progress) {
|
|
400
|
+
// Need to simulate cpu heavy task
|
|
401
|
+
for (uint32_t i = 0; i < 100; ++i) {
|
|
402
|
+
progress.Send(&i, 1);
|
|
403
|
+
std::this_thread::sleep_for(std::chrono::seconds(1));
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
void OnOK() {
|
|
408
|
+
HandleScope scope(Env());
|
|
409
|
+
Callback().Call({Env().Null(), String::New(Env(), echo)});
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
void OnProgress(const uint32_t* data, size_t /* count */) {
|
|
413
|
+
HandleScope scope(Env());
|
|
414
|
+
Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)});
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
private:
|
|
418
|
+
std::string echo;
|
|
419
|
+
};
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
The `EchoWorker`'s constructor calls the base class' constructor to pass in the
|
|
423
|
+
callback that the `Napi::AsyncProgressQueueWorker` base class will store
|
|
424
|
+
persistently. When the work on the `Napi::AsyncProgressQueueWorker::Execute`
|
|
425
|
+
method is done the `Napi::AsyncProgressQueueWorker::OnOk` method is called and
|
|
426
|
+
the results are returned back to JavaScript when the stored callback is invoked
|
|
427
|
+
with its associated environment.
|
|
428
|
+
|
|
429
|
+
The following code shows an example of how to create and use an
|
|
430
|
+
`Napi::AsyncProgressQueueWorker`.
|
|
431
|
+
|
|
432
|
+
```cpp
|
|
433
|
+
#include <napi.h>
|
|
434
|
+
|
|
435
|
+
// Include EchoWorker class
|
|
436
|
+
// ..
|
|
437
|
+
|
|
438
|
+
using namespace Napi;
|
|
439
|
+
|
|
440
|
+
Value Echo(const CallbackInfo& info) {
|
|
441
|
+
// We need to validate the arguments here.
|
|
442
|
+
Function cb = info[1].As<Function>();
|
|
443
|
+
std::string in = info[0].As<String>();
|
|
444
|
+
EchoWorker* wk = new EchoWorker(cb, in);
|
|
445
|
+
wk->Queue();
|
|
446
|
+
return info.Env().Undefined();
|
|
447
|
+
}
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
The implementation of a `Napi::AsyncProgressQueueWorker` can be used by creating a
|
|
451
|
+
new instance and passing to its constructor the callback to execute when the
|
|
452
|
+
asynchronous task ends and other data needed for the computation. Once created,
|
|
453
|
+
the only other action needed is to call the `Napi::AsyncProgressQueueWorker::Queue`
|
|
454
|
+
method that will queue the created worker for execution.
|
|
455
|
+
|
|
456
|
+
[`Napi::AsyncWorker`]: ./async_worker.md
|
package/doc/basic_types.md
CHANGED
|
@@ -257,6 +257,14 @@ bool Napi::Value::IsExternal() const;
|
|
|
257
257
|
Returns `true` if the underlying value is a N-API external object or `false`
|
|
258
258
|
otherwise.
|
|
259
259
|
|
|
260
|
+
#### IsDate
|
|
261
|
+
```cpp
|
|
262
|
+
bool Napi::Value::IsDate() const;
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Returns `true` if the underlying value is a JavaScript `Date` or `false`
|
|
266
|
+
otherwise.
|
|
267
|
+
|
|
260
268
|
#### ToBoolean
|
|
261
269
|
```cpp
|
|
262
270
|
Napi::Boolean Napi::Value::ToBoolean() const;
|
package/doc/bigint.md
CHANGED
|
@@ -8,6 +8,7 @@ A JavaScript BigInt value.
|
|
|
8
8
|
|
|
9
9
|
```cpp
|
|
10
10
|
static Napi::BigInt Napi::BigInt::New(Napi::Env env, int64_t value);
|
|
11
|
+
static Napi::BigInt Napi::BigInt::New(Napi::Env env, uint64_t value);
|
|
11
12
|
```
|
|
12
13
|
|
|
13
14
|
- `[in] env`: The environment in which to construct the `Napi::BigInt` object.
|
|
@@ -47,7 +48,7 @@ Returns a new empty JavaScript `Napi::BigInt`.
|
|
|
47
48
|
### Int64Value
|
|
48
49
|
|
|
49
50
|
```cpp
|
|
50
|
-
int64_t Napi::
|
|
51
|
+
int64_t Napi::BigInt::Int64Value(bool* lossless) const;
|
|
51
52
|
```
|
|
52
53
|
|
|
53
54
|
- `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly.
|
|
@@ -20,15 +20,15 @@ class Example : public Napi::ObjectWrap<Example> {
|
|
|
20
20
|
static Napi::FunctionReference constructor;
|
|
21
21
|
double _value;
|
|
22
22
|
Napi::Value GetValue(const Napi::CallbackInfo &info);
|
|
23
|
-
|
|
23
|
+
void SetValue(const Napi::CallbackInfo &info, const Napi::Value &value);
|
|
24
24
|
};
|
|
25
25
|
|
|
26
26
|
Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
|
|
27
27
|
Napi::Function func = DefineClass(env, "Example", {
|
|
28
28
|
// Register a class instance accessor with getter and setter functions.
|
|
29
|
-
InstanceAccessor
|
|
30
|
-
// We can also register a readonly accessor by
|
|
31
|
-
InstanceAccessor("readOnlyProp"
|
|
29
|
+
InstanceAccessor<&Example::GetValue, &Example::SetValue>("value"),
|
|
30
|
+
// We can also register a readonly accessor by omitting the setter.
|
|
31
|
+
InstanceAccessor<&Example::GetValue>("readOnlyProp")
|
|
32
32
|
});
|
|
33
33
|
|
|
34
34
|
constructor = Napi::Persistent(func);
|
|
@@ -52,12 +52,11 @@ Napi::Value Example::GetValue(const Napi::CallbackInfo &info) {
|
|
|
52
52
|
return Napi::Number::New(env, this->_value);
|
|
53
53
|
}
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
void Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) {
|
|
56
56
|
Napi::Env env = info.Env();
|
|
57
57
|
// ...
|
|
58
58
|
Napi::Number arg = value.As<Napi::Number>();
|
|
59
59
|
this->_value = arg.DoubleValue();
|
|
60
|
-
return this->GetValue(info);
|
|
61
60
|
}
|
|
62
61
|
|
|
63
62
|
// Initialize native add-on
|
package/doc/cmake-js.md
CHANGED
|
@@ -1,19 +1,68 @@
|
|
|
1
1
|
# CMake.js
|
|
2
2
|
|
|
3
|
-
**CMake.js** is a build tool that allow native addon
|
|
4
|
-
C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
|
|
5
|
-
instead of Google's **gyp**
|
|
3
|
+
[**CMake.js**](https://github.com/cmake-js/cmake-js) is a build tool that allow native addon developers to compile their
|
|
4
|
+
C or C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
|
|
5
|
+
instead of Google's [**gyp**](https://gyp.gsrc.io) tool it is based on the [**CMake**](https://cmake.org) build system.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Quick Start
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
### Install CMake
|
|
10
|
+
|
|
11
|
+
CMake.js requires that CMake be installed. Installers for a variety of platforms can be found on the [CMake website](https://cmake.org).
|
|
12
|
+
|
|
13
|
+
### Install CMake.js
|
|
14
|
+
|
|
15
|
+
For developers, CMake.js is typically installed as a global package:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install -g cmake-js
|
|
19
|
+
cmake-js --help
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
> For *users* of your native addon, CMake.js should be configured as a dependency in your `package.json` as described in the [CMake.js documentation](https://github.com/cmake-js/cmake-js).
|
|
23
|
+
|
|
24
|
+
### CMakeLists.txt
|
|
25
|
+
|
|
26
|
+
Your project will require a `CMakeLists.txt` file. The [CMake.js README file](https://github.com/cmake-js/cmake-js#usage) shows what's necessary.
|
|
27
|
+
|
|
28
|
+
### NAPI_VERSION
|
|
29
|
+
|
|
30
|
+
When building N-API addons, it's crucial to specify the N-API version your code is designed to work with. With CMake.js, this information is specified in the `CMakeLists.txt` file:
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
add_definitions(-DNAPI_VERSION=3)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Since N-API is ABI-stable, your N-API addon will work, without recompilation, with the N-API version you specify in `NAPI_VERSION` and all subsequent N-API versions.
|
|
37
|
+
|
|
38
|
+
In the absence of a need for features available only in a specific N-API version, version 3 is a good choice as it is the version of N-API that was active when N-API left experimental status.
|
|
39
|
+
|
|
40
|
+
### NAPI_EXPERIMENTAL
|
|
41
|
+
|
|
42
|
+
The following line in the `CMakeLists.txt` file will enable N-API experimental features if your code requires them:
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
add_definitions(-DNAPI_EXPERIMENTAL)
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### node-addon-api
|
|
49
|
+
|
|
50
|
+
If your N-API native add-on uses the optional [**node-addon-api**](https://github.com/nodejs/node-addon-api#node-addon-api-module) C++ wrapper, the `CMakeLists.txt` file requires additional configuration information as described on the [CMake.js README file](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api).
|
|
51
|
+
|
|
52
|
+
## Example
|
|
53
|
+
|
|
54
|
+
A working example of an N-API native addon built using CMake.js can be found on the [node-addon-examples repository](https://github.com/nodejs/node-addon-examples/tree/master/build_with_cmake#building-n-api-addons-using-cmakejs).
|
|
55
|
+
|
|
56
|
+
## **CMake** Reference
|
|
57
|
+
|
|
58
|
+
- [Installation](https://github.com/cmake-js/cmake-js#installation)
|
|
59
|
+
- [How to use](https://github.com/cmake-js/cmake-js#usage)
|
|
11
60
|
- [Using N-API and node-addon-api](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api)
|
|
12
|
-
- [Tutorials](https://
|
|
13
|
-
- [Use case in the works - ArrayFire.js](https://
|
|
61
|
+
- [Tutorials](https://github.com/cmake-js/cmake-js#tutorials)
|
|
62
|
+
- [Use case in the works - ArrayFire.js](https://github.com/cmake-js/cmake-js#use-case-in-the-works---arrayfirejs)
|
|
14
63
|
|
|
15
64
|
Sometimes finding the right settings is not easy so to accomplish at most
|
|
16
65
|
complicated task please refer to:
|
|
17
66
|
|
|
18
67
|
- [CMake documentation](https://cmake.org/)
|
|
19
|
-
- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)
|
|
68
|
+
- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)
|
|
@@ -13,7 +13,7 @@ tools:
|
|
|
13
13
|
|
|
14
14
|
* [Changelog maker](https://www.npmjs.com/package/changelog-maker)
|
|
15
15
|
|
|
16
|
-
If not please follow the instruction reported in the tool's documentation to
|
|
16
|
+
If not please follow the instruction reported in the tool's documentation to
|
|
17
17
|
install it.
|
|
18
18
|
|
|
19
19
|
## Publish new release
|
|
@@ -27,13 +27,13 @@ new release. Give people some time to comment or suggest PRs that should land fi
|
|
|
27
27
|
|
|
28
28
|
* Update the version in **package.json** appropriately.
|
|
29
29
|
|
|
30
|
-
* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/master/README.md)
|
|
30
|
+
* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/master/README.md)
|
|
31
31
|
to show the new version as the latest.
|
|
32
32
|
|
|
33
33
|
* Generate the changelog for the new version using **changelog maker** tool. From
|
|
34
34
|
the route folder of the repo launch the following command:
|
|
35
35
|
|
|
36
|
-
```bash
|
|
36
|
+
```bash
|
|
37
37
|
> changelog-maker
|
|
38
38
|
```
|
|
39
39
|
* Use the output generated by **changelog maker** to pdate the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/master/CHANGELOG.md)
|
|
@@ -43,8 +43,8 @@ following the style used in publishing the previous release.
|
|
|
43
43
|
|
|
44
44
|
* Validate all tests pass by running npm test on master.
|
|
45
45
|
|
|
46
|
-
* Use **[CI](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api/)**
|
|
47
|
-
to validate tests pass
|
|
46
|
+
* Use **[CI](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api-new/)**
|
|
47
|
+
to validate tests pass (note there are still some issues on SmartOS and
|
|
48
48
|
Windows in the testing).
|
|
49
49
|
|
|
50
50
|
* Do a clean checkout of node-addon-api.
|