From be398d0897231fa347dd18fe8cdc60f3184e6e49 Mon Sep 17 00:00:00 2001 From: Roy Wright Date: Thu, 31 Oct 2019 08:52:36 +0800 Subject: [PATCH] doc: improve AsyncWorker docs (#571) PR-URL: https://github.com/nodejs/node-addon-api/pull/571 Reviewed-By: NickNaso Reviewed-By: Michael Dawson Reviewed-By: Gabriel Schulhof --- doc/async_worker.md | 45 +++++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/doc/async_worker.md b/doc/async_worker.md index a13e8a1..88668af 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -7,8 +7,8 @@ operation. Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When a thread is available for execution the `Napi::AsyncWorker::Execute` method will -be invoked. Once `Napi::AsyncWorker::Execute` completes either -`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once +be invoked. Once `Napi::AsyncWorker::Execute` completes either +`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are complete the `Napi::AsyncWorker` instance is destructed. @@ -38,7 +38,7 @@ void Napi::AsyncWorker::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 +executing, it cannot be cancelled. If cancelled successfully neither `OnOK` nor `OnError` will be called. ```cpp @@ -90,14 +90,14 @@ void Napi::AsyncWorker::SetError(const std::string& error); ### Execute -This method is used to execute some tasks out of the **event loop** on a libuv +This method is used to execute some tasks outside of the **event loop** on a libuv 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 +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 interaction through node-addon-api with JavaScript should be implemented -in the `Napi::AsyncWorker::OnOK` method which runs on the main thread and is -invoked when the `Napi::AsyncWorker::Execute` method completes. +in the `Napi::AsyncWorker::OnOK` method and `Napi::AsyncWorker::OnError` which run +on the main thread and are invoked when the `Napi::AsyncWorker::Execute` method completes. ```cpp virtual void Napi::AsyncWorker::Execute() = 0; @@ -106,18 +106,19 @@ virtual void Napi::AsyncWorker::Execute() = 0; ### OnOK This method is invoked when the computation in the `Execute` method ends. -The default implementation runs the Callback optionally provided when the AsyncWorker class -was created. The callback will by default receive no arguments. To provide arguments, -override the `GetResult()` method. +The default implementation runs the `Callback` optionally provided when the +`AsyncWorker` class was created. The `Callback` will by default receive no +arguments. The arguments to the `Callback` can be provided by overriding the +`GetResult()` method. ```cpp virtual void Napi::AsyncWorker::OnOK(); ``` ### GetResult -This method returns the arguments passed to the Callback invoked by the default +This method returns the arguments passed to the `Callback` invoked by the default `OnOK()` implementation. The default implementation returns an empty vector, -providing no arguments to the Callback. +providing no arguments to the `Callback`. ```cpp virtual std::vector Napi::AsyncWorker::GetResult(Napi::Env env); @@ -128,7 +129,7 @@ virtual std::vector Napi::AsyncWorker::GetResult(Napi::Env env); This method is invoked after `Napi::AsyncWorker::Execute` completes if an error occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`. -The default implementation calls the callback provided when the `Napi::AsyncWorker` +The default implementation calls the `Callback` provided when the `Napi::AsyncWorker` class was created, passing in the error as the first parameter. ```cpp @@ -172,7 +173,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* 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 +- `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. @@ -189,7 +190,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* 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 +- `[in] resource_name`: Null-terminated string 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 @@ -224,7 +225,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c - `[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 +- `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. @@ -242,7 +243,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c - `[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 +- `[in] resource_name`: Null-terminated string 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 @@ -274,7 +275,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name); ``` - `[in] env`: The environment in which to create the `Napi::AsyncWorker`. -- `[in] resource_name`: Null-terminated strings that represents the +- `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. @@ -290,7 +291,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi: ``` - `[in] env`: The environment in which to create the `Napi::AsyncWorker`. -- `[in] resource_name`: Null-terminated strings that represents the +- `[in] resource_name`: Null-terminated string 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 @@ -333,7 +334,7 @@ function runs in the background out of the **event loop** thread and at the end the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` function will be called and are executed as part of the event loop. -The code below show a basic example of `Napi::AsyncWorker` the implementation: +The code below shows a basic example of `Napi::AsyncWorker` the implementation: ```cpp #include @@ -371,7 +372,7 @@ the work on the `Napi::AsyncWorker::Execute` method is done the `Napi::AsyncWorker::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 use an `Napi::AsyncWorker` +The following code shows an example of how to create and use an `Napi::AsyncWorker`. ```cpp #include @@ -382,7 +383,7 @@ The following code shows an example on how to create and use an `Napi::AsyncWork use namespace Napi; Value Echo(const CallbackInfo& info) { - // You need to check the input data here + // You need to validate the arguments here. Function cb = info[1].As(); std::string in = info[0].As(); EchoWorker* wk = new EchoWorker(cb, in);