From 60867fb030bae582082340ead7dbc7efdc2f5398 Mon Sep 17 00:00:00 2001 From: 8cy <50817549+8cy@users.noreply.github.com> Date: Fri, 3 Apr 2020 02:37:42 -0700 Subject: 2020/04/03, 02:34, v1.2.0 --- .../node-addon-api/doc/async_progress_worker.md | 344 +++++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 node_modules/node-addon-api/doc/async_progress_worker.md (limited to 'node_modules/node-addon-api/doc/async_progress_worker.md') diff --git a/node_modules/node-addon-api/doc/async_progress_worker.md b/node_modules/node-addon-api/doc/async_progress_worker.md new file mode 100644 index 0000000..296b51b --- /dev/null +++ b/node_modules/node-addon-api/doc/async_progress_worker.md @@ -0,0 +1,344 @@ +# AsyncProgressWorker + +`Napi::AsyncProgressWorker` is an abstract class which implements `Napi::AsyncWorker` +while extending `Napi::AsyncWorker` internally with `Napi::ThreadSafeFunction` for +moving work progress reports from worker thread(s) to event loop threads. + +Like `Napi::AsyncWorker`, once created, execution is requested by calling +`Napi::AsyncProgressWorker::Queue`. When a thread is available for execution +the `Napi::AsyncProgressWorker::Execute` method will be invoked. During the +execution, `Napi::AsyncProgressWorker::ExecutionProgress::Send` can be used to +indicate execution process, which will eventually invoke `Napi::AsyncProgressWorker::OnProgress` +on the JavaScript thread to safely call into JavaScript. Once `Napi::AsyncProgressWorker::Execute` +completes either `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` +will be invoked. Once the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` +methods are complete the `Napi::AsyncProgressWorker` instance is destructed. + +For the most basic use, only the `Napi::AsyncProgressWorker::Execute` and +`Napi::AsyncProgressWorker::OnProgress` method must be implemented in a subclass. + +## Methods + +[`Napi::AsyncWorker`][] provides detailed descriptions for most methods. + +### Execute + +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 +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::AsyncProgressWorker::OnOK` method and/or `Napi::AsyncProgressWorker::OnError` +which run on the main thread and are invoked when the `Napi::AsyncProgressWorker::Execute` +method completes. + +```cpp +virtual void Napi::AsyncProgressWorker::Execute(const ExecutionProgress& progress) = 0; +``` + +### OnOK + +This method is invoked when the computation in the `Execute` method ends. +The default implementation runs the `Callback` optionally provided when the +`AsyncProgressWorker` class was created. The `Callback` will by default receive no +arguments. Arguments to the callback can be provided by overriding the `GetResult()` +method. + +```cpp +virtual void Napi::AsyncProgressWorker::OnOK(); +``` + +### OnProgress + +This method is invoked when the computation in the `Napi::AsyncProgressWorker::ExecutionProcess::Send` +method was called during worker thread execution. + +```cpp +virtual void Napi::AsyncProgressWorker::OnProgress(const T* data, size_t count) +``` + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(const Napi::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. + +Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(const Napi::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 string that represents the +identifier for the kind of resource that is being provided for diagnostic +information exposed by the async_hooks API. + +Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name, const Napi::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 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 +will be passed to possible async_hooks. + +Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::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. + +Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::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 string that represents the +identifier for the kind of resource that is being provided for diagnostic +information exposed by the async_hooks API. + +Returns a `Napi::AsyncWork` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name, const Napi::Object& resource); +``` + +- `[in] receiver`: The `this` object to be 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 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 +will be passed to possible async_hooks. + +Returns a `Napi::AsyncWork` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(Napi::Env env); +``` + +- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`. + +Returns an `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling +`Napi::AsyncProgressWorker::Queue`. + +Available with `NAPI_VERSION` equal to or greater than 5. + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name); +``` + +- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`. +- `[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. + +Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by +calling `Napi::AsyncProgressWorker::Queue`. + +Available with `NAPI_VERSION` equal to or greater than 5. + +### Constructor + +Creates a new `Napi::AsyncProgressWorker`. + +```cpp +explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource); +``` + +- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`. +- `[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 +will be passed to possible async_hooks. + +Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by +calling `Napi::AsyncProgressWorker::Queue`. + +Available with `NAPI_VERSION` equal to or greater than 5. + +### Destructor + +Deletes the created work object that is used to execute logic asynchronously and +release the internal `Napi::ThreadSafeFunction`, which will be aborted to prevent +unexpected upcoming thread safe calls. + +```cpp +virtual Napi::AsyncProgressWorker::~AsyncProgressWorker(); +``` + +# AsyncProgressWorker::ExecutionProcess + +A bridge class created before the worker thread execution of `Napi::AsyncProgressWorker::Execute`. + +## Methods + +### Send + +`Napi::AsyncProgressWorker::ExecutionProcess::Send` takes two arguments, a pointer +to a generic type of data, and a `size_t` to indicate how many items the pointer is +pointing to. + +The data pointed to will be copied to internal slots of `Napi::AsyncProgressWorker` so +after the call to `Napi::AsyncProgressWorker::ExecutionProcess::Send` the data can +be safely released. + +Note that `Napi::AsyncProgressWorker::ExecutionProcess::Send` merely guarantees +**eventual** invocation of `Napi::AsyncProgressWorker::OnProgress`, which means +multiple send might be coalesced into single invocation of `Napi::AsyncProgressWorker::OnProgress` +with latest data. + +```cpp +void Napi::AsyncProgressWorker::ExecutionProcess::Send(const T* data, size_t count) const; +``` + +## Example + +The first step to use the `Napi::AsyncProgressWorker` class is to create a new class that +inherits from it and implement the `Napi::AsyncProgressWorker::Execute` abstract method. +Typically input to the worker will be saved within the class' fields generally +passed in through its constructor. + +During the worker thread execution, the first argument of `Napi::AsyncProgressWorker::Execute` +can be used to report the progress of the execution. + +When the `Napi::AsyncProgressWorker::Execute` method completes without errors the +`Napi::AsyncProgressWorker::OnOK` function callback will be invoked. In this function the +results of the computation will be reassembled and returned back to the initial +JavaScript context. + +`Napi::AsyncProgressWorker` ensures that all the code in the `Napi::AsyncProgressWorker::Execute` +function runs in the background out of the **event loop** thread and at the end +the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` function will be +called and are executed as part of the event loop. + +The code below shows a basic example of the `Napi::AsyncProgressWorker` implementation: + +```cpp +#include + +#include +#include + +use namespace Napi; + +class EchoWorker : public AsyncProgressWorker { + public: + EchoWorker(Function& callback, std::string& echo) + : AsyncProgressWorker(callback), echo(echo) {} + + ~EchoWorker() {} + // This code will be executed on the worker thread + void Execute(const ExecutionProgress& progress) { + // Need to simulate cpu heavy task + for (uint32_t i = 0; i < 100; ++i) { + progress.Send(&i, 1) + std::this_thread::sleep_for(std::chrono::seconds(1)); + } + } + + void OnOK() { + HandleScope scope(Env()); + Callback().Call({Env().Null(), String::New(Env(), echo)}); + } + + void OnProgress(const uint32_t* data, size_t /* count */) { + HandleScope scope(Env()); + Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)}); + } + + private: + std::string echo; +}; +``` + +The `EchoWorker`'s constructor calls the base class' constructor to pass in the +callback that the `Napi::AsyncProgressWorker` base class will store persistently. When +the work on the `Napi::AsyncProgressWorker::Execute` method is done the +`Napi::AsyncProgressWorker::OnOk` method is called and the results are return back to +JavaScript when the stored callback is invoked with its associated environment. + +The following code shows an example of how to create and use an `Napi::AsyncProgressWorker` + +```cpp +#include + +// Include EchoWorker class +// .. + +use namespace Napi; + +Value Echo(const CallbackInfo& info) { + // We need to validate the arguments here + Function cb = info[1].As(); + std::string in = info[0].As(); + EchoWorker* wk = new EchoWorker(cb, in); + wk->Queue(); + return info.Env().Undefined(); +} +``` + +The implementation of a `Napi::AsyncProgressWorker` can be used by creating a +new instance and passing to its constructor the callback to execute when the +asynchronous task ends and other data needed for the computation. Once created, +the only other action needed is to call the `Napi::AsyncProgressWorker::Queue` +method that will queue the created worker for execution. + +[`Napi::AsyncWorker`]: ./async_worker.md -- cgit v1.2.3