musix-oss/node_modules/node-addon-api/doc/async_progress_worker.md

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.

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.

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.

virtual void Napi::AsyncProgressWorker::OnProgress(const T* data, size_t count)

Constructor

Creates a new Napi::AsyncProgressWorker.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

#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

#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.