Skip to content

Commit 8d6132f

Browse files
legendecasmhdawson
authored andcommitted
doc: improve AsyncWorker docs (#571)
PR-URL: #571 Reviewed-By: NickNaso <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Gabriel Schulhof <[email protected]>
1 parent bc8fc23 commit 8d6132f

File tree

1 file changed

+23
-22
lines changed

1 file changed

+23
-22
lines changed

doc/async_worker.md

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ operation.
77

88
Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When
99
a thread is available for execution the `Napi::AsyncWorker::Execute` method will
10-
be invoked. Once `Napi::AsyncWorker::Execute` completes either
11-
`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once
10+
be invoked. Once `Napi::AsyncWorker::Execute` completes either
11+
`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once
1212
the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are
1313
complete the `Napi::AsyncWorker` instance is destructed.
1414

@@ -38,7 +38,7 @@ void Napi::AsyncWorker::Queue();
3838
### Cancel
3939

4040
Cancels queued work if it has not yet been started. If it has already started
41-
executing, it cannot be cancelled. If cancelled successfully neither
41+
executing, it cannot be cancelled. If cancelled successfully neither
4242
`OnOK` nor `OnError` will be called.
4343

4444
```cpp
@@ -90,14 +90,14 @@ void Napi::AsyncWorker::SetError(const std::string& error);
9090
9191
### Execute
9292
93-
This method is used to execute some tasks out of the **event loop** on a libuv
93+
This method is used to execute some tasks outside of the **event loop** on a libuv
9494
worker thread. Subclasses must implement this method and the method is run on
95-
a thread other than that running the main event loop. As the method is not
95+
a thread other than that running the main event loop. As the method is not
9696
running on the main event loop, it must avoid calling any methods from node-addon-api
9797
or running any code that might invoke JavaScript. Instead, once this method is
9898
complete any interaction through node-addon-api with JavaScript should be implemented
99-
in the `Napi::AsyncWorker::OnOK` method which runs on the main thread and is
100-
invoked when the `Napi::AsyncWorker::Execute` method completes.
99+
in the `Napi::AsyncWorker::OnOK` method and `Napi::AsyncWorker::OnError` which run
100+
on the main thread and are invoked when the `Napi::AsyncWorker::Execute` method completes.
101101
102102
```cpp
103103
virtual void Napi::AsyncWorker::Execute() = 0;
@@ -106,18 +106,19 @@ virtual void Napi::AsyncWorker::Execute() = 0;
106106
### OnOK
107107

108108
This method is invoked when the computation in the `Execute` method ends.
109-
The default implementation runs the Callback optionally provided when the AsyncWorker class
110-
was created. The callback will by default receive no arguments. To provide arguments,
111-
override the `GetResult()` method.
109+
The default implementation runs the `Callback` optionally provided when the
110+
`AsyncWorker` class was created. The `Callback` will by default receive no
111+
arguments. The arguments to the `Callback` can be provided by overriding the
112+
`GetResult()` method.
112113

113114
```cpp
114115
virtual void Napi::AsyncWorker::OnOK();
115116
```
116117
### GetResult
117118

118-
This method returns the arguments passed to the Callback invoked by the default
119+
This method returns the arguments passed to the `Callback` invoked by the default
119120
`OnOK()` implementation. The default implementation returns an empty vector,
120-
providing no arguments to the Callback.
121+
providing no arguments to the `Callback`.
121122

122123
```cpp
123124
virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
@@ -128,7 +129,7 @@ virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
128129
This method is invoked after `Napi::AsyncWorker::Execute` completes if an error
129130
occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are
130131
enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`.
131-
The default implementation calls the callback provided when the `Napi::AsyncWorker`
132+
The default implementation calls the `Callback` provided when the `Napi::AsyncWorker`
132133
class was created, passing in the error as the first parameter.
133134
134135
```cpp
@@ -172,7 +173,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_
172173

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

@@ -189,7 +190,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_
189190
190191
- `[in] callback`: The function which will be called when an asynchronous
191192
operations ends. The given function is called from the main event loop thread.
192-
- `[in] resource_name`: Null-terminated strings that represents the
193+
- `[in] resource_name`: Null-terminated string that represents the
193194
identifier for the kind of resource that is being provided for diagnostic
194195
information exposed by the async_hooks API.
195196
- `[in] resource`: Object associated with the asynchronous operation that
@@ -224,7 +225,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
224225
- `[in] receiver`: The `this` object passed to the called function.
225226
- `[in] callback`: The function which will be called when an asynchronous
226227
operations ends. The given function is called from the main event loop thread.
227-
- `[in] resource_name`: Null-terminated strings that represents the
228+
- `[in] resource_name`: Null-terminated string that represents the
228229
identifier for the kind of resource that is being provided for diagnostic
229230
information exposed by the async_hooks API.
230231
@@ -242,7 +243,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
242243
- `[in] receiver`: The `this` object passed to the called function.
243244
- `[in] callback`: The function which will be called when an asynchronous
244245
operations ends. The given function is called from the main event loop thread.
245-
- `[in] resource_name`: Null-terminated strings that represents the
246+
- `[in] resource_name`: Null-terminated string that represents the
246247
identifier for the kind of resource that is being provided for diagnostic
247248
information exposed by the async_hooks API.
248249
- `[in] resource`: Object associated with the asynchronous operation that
@@ -274,7 +275,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name);
274275
```
275276

276277
- `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
277-
- `[in] resource_name`: Null-terminated strings that represents the
278+
- `[in] resource_name`: Null-terminated string that represents the
278279
identifier for the kind of resource that is being provided for diagnostic
279280
information exposed by the async_hooks API.
280281

@@ -290,7 +291,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi:
290291
```
291292
292293
- `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
293-
- `[in] resource_name`: Null-terminated strings that represents the
294+
- `[in] resource_name`: Null-terminated string that represents the
294295
identifier for the kind of resource that is being provided for diagnostic
295296
information exposed by the async_hooks API.
296297
- `[in] resource`: Object associated with the asynchronous operation that
@@ -333,7 +334,7 @@ function runs in the background out of the **event loop** thread and at the end
333334
the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` function will be
334335
called and are executed as part of the event loop.
335336

336-
The code below show a basic example of `Napi::AsyncWorker` the implementation:
337+
The code below shows a basic example of `Napi::AsyncWorker` the implementation:
337338

338339
```cpp
339340
#include<napi.h>
@@ -371,7 +372,7 @@ the work on the `Napi::AsyncWorker::Execute` method is done the
371372
`Napi::AsyncWorker::OnOk` method is called and the results return back to
372373
JavaScript invoking the stored callback with its associated environment.
373374

374-
The following code shows an example on how to create and use an `Napi::AsyncWorker`
375+
The following code shows an example of how to create and use an `Napi::AsyncWorker`.
375376

376377
```cpp
377378
#include<napi.h>
@@ -382,7 +383,7 @@ The following code shows an example on how to create and use an `Napi::AsyncWork
382383
use namespace Napi;
383384

384385
Value Echo(const CallbackInfo& info) {
385-
// You need to check the input data here
386+
// You need to validate the arguments here.
386387
Function cb = info[1].As<Function>();
387388
std::string in = info[0].As<String>();
388389
EchoWorker* wk = new EchoWorker(cb, in);

0 commit comments

Comments
 (0)