diff options
Diffstat (limited to 'node_modules/node-addon-api/doc/async_progress_worker.md')
| -rw-r--r-- | node_modules/node-addon-api/doc/async_progress_worker.md | 344 |
1 files changed, 0 insertions, 344 deletions
diff --git a/node_modules/node-addon-api/doc/async_progress_worker.md b/node_modules/node-addon-api/doc/async_progress_worker.md deleted file mode 100644 index 296b51b..0000000 --- a/node_modules/node-addon-api/doc/async_progress_worker.md +++ /dev/null @@ -1,344 +0,0 @@ -# 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<napi.h> - -#include <chrono> -#include <thread> - -use namespace Napi; - -class EchoWorker : public AsyncProgressWorker<uint32_t> { - 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 <napi.h> - -// Include EchoWorker class -// .. - -use namespace Napi; - -Value Echo(const CallbackInfo& info) { - // We need to validate the arguments here - Function cb = info[1].As<Function>(); - std::string in = info[0].As<String>(); - 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 |