koffi 1.1.0-beta.1 → 1.1.0-beta.2

package/vendor/node-addon-api/doc/async_worker_variants.md

@@ -0,0 +1,557 @@
+# 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. If you would like to guarantee that there is one invocation of
+`OnProgress` for every `Send` call, you should use the `Napi::AsyncProgressQueueWorker` 
+class instead which is documented further down this page.
+
+```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 along with an
+example of how the counterpart in Javascript would appear:
+
+```cpp
+#include <napi.h>
+
+#include <chrono>
+#include <thread>
+
+using namespace Napi;
+
+class EchoWorker : public AsyncProgressWorker<uint32_t> {
+    public:
+        EchoWorker(Function& okCallback, std::string& echo)
+        : AsyncProgressWorker(okCallback), echo(echo) {}
+
+        ~EchoWorker() {}
+        
+        // This code will be executed on the worker thread
+        void Execute(const ExecutionProgress& progress) {
+            // Need to simulate cpu heavy task
+            // Note: This Send() call is not guaranteed to trigger an equal
+            // number of OnProgress calls (read documentation above for more info)
+            for (uint32_t i = 0; i < 100; ++i) {
+              progress.Send(&i, 1)
+            }
+        }
+        
+        void OnError(const Error &e) {
+            HandleScope scope(Env());
+            // Pass error onto JS, no data for other parameters
+            Callback().Call({String::New(Env(), e.Message())});
+        }
+
+        void OnOK() {
+            HandleScope scope(Env());
+            // Pass no error, give back original data
+            Callback().Call({Env().Null(), String::New(Env(), echo)});
+        }
+
+        void OnProgress(const uint32_t* data, size_t /* count */) {
+            HandleScope scope(Env());
+            // Pass no error, no echo data, but do pass on the progress data
+            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
+// ..
+
+using namespace Napi;
+
+Value Echo(const CallbackInfo& info) {
+    // We need to validate the arguments here
+    std::string in = info[0].As<String>();
+    Function cb = info[1].As<Function>();
+    EchoWorker* wk = new EchoWorker(cb, in);
+    wk->Queue();
+    return info.Env().Undefined();
+}
+
+// Register the native method for JS to access
+Object Init(Env env, Object exports)
+{
+    exports.Set(String::New(env, "echo"), Function::New(env, Echo));
+
+    return exports;
+}
+
+// Register our native addon
+NODE_API_MODULE(nativeAddon, Init)
+```
+
+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.
+
+Lastly, the following Javascript (ES6+) code would be associated the above example:
+
+```js
+const { nativeAddon } = require('binding.node');
+
+const exampleCallback = (errorResponse, okResponse, progressData) => {
+    // Use the data accordingly
+    // ...
+};
+
+// Call our native addon with the parameters of a string and a function
+nativeAddon.echo("example", exampleCallback);
+```
+
+# AsyncProgressQueueWorker
+
+`Napi::AsyncProgressQueueWorker` acts exactly like `Napi::AsyncProgressWorker`
+except that each progress committed by `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send`
+during `Napi::AsyncProgressQueueWorker::Execute` is guaranteed to be
+processed by `Napi::AsyncProgressQueueWorker::OnProgress` on the JavaScript
+thread in the order it was committed.
+
+For the most basic use, only the `Napi::AsyncProgressQueueWorker::Execute` and
+`Napi::AsyncProgressQueueWorker::OnProgress` method must be implemented in a subclass.
+
+# AsyncProgressQueueWorker::ExecutionProcess
+
+A bridge class created before the worker thread execution of `Napi::AsyncProgressQueueWorker::Execute`.
+
+## Methods
+
+### Send
+
+`Napi::AsyncProgressQueueWorker::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::AsyncProgressQueueWorker` so
+after the call to `Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` the data can
+be safely released.
+
+`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` guarantees invocation
+of `Napi::AsyncProgressQueueWorker::OnProgress`, which means multiple `Send`
+call will result in the in-order invocation of `Napi::AsyncProgressQueueWorker::OnProgress`
+with each data item.
+
+```cpp
+void Napi::AsyncProgressQueueWorker::ExecutionProcess::Send(const T* data, size_t count) const;
+```
+
+## Example
+
+The code below shows an example of the `Napi::AsyncProgressQueueWorker` implementation, but
+also demonstrates how to use multiple `Napi::Function`'s if you wish to provide multiple
+callback functions for more object-oriented code:
+
+```cpp
+#include <napi.h>
+
+#include <chrono>
+#include <thread>
+
+using namespace Napi;
+
+class EchoWorker : public AsyncProgressQueueWorker<uint32_t> {
+    public:
+        EchoWorker(Function& okCallback, Function& errorCallback, Function& progressCallback, std::string& echo)
+        : AsyncProgressQueueWorker(okCallback), echo(echo) {
+            // Set our function references to use them below
+            this->errorCallback.Reset(errorCallback, 1);
+            this->progressCallback.Reset(progressCallback, 1);
+        }
+
+        ~EchoWorker() {}
+        
+        // This code will be executed on the worker thread
+        void Execute(const ExecutionProgress& progress) {
+            // Need to simulate cpu heavy task to demonstrate that
+            // every call to Send() will trigger an OnProgress function call
+            for (uint32_t i = 0; i < 100; ++i) {
+              progress.Send(&i, 1);
+            }
+        }
+
+        void OnOK() {
+            HandleScope scope(Env());
+            // Call our onOkCallback in javascript with the data we were given originally
+            Callback().Call({String::New(Env(), echo)});
+        }
+        
+        void OnError(const Error &e) {
+            HandleScope scope(Env());
+            
+            // We call our callback provided in the constructor with 2 parameters
+            if (!this->errorCallback.IsEmpty()) {
+                // Call our onErrorCallback in javascript with the error message
+                this->errorCallback.Call(Receiver().Value(), {String::New(Env(), e.Message())});
+            }
+        }
+
+        void OnProgress(const uint32_t* data, size_t /* count */) {
+            HandleScope scope(Env());
+            
+            if (!this->progressCallback.IsEmpty()) {
+                // Call our onProgressCallback in javascript with each integer from 0 to 99 (inclusive)
+                // as this function is triggered from the above Send() calls
+                this->progressCallback.Call(Receiver().Value(), {Number::New(Env(), *data)});
+            }
+        }
+
+    private:
+        std::string echo;
+        FunctionReference progressCallback;
+        FunctionReference errorCallback;
+        
+};
+```
+
+The `EchoWorker`'s constructor calls the base class' constructor to pass in the
+callback that the `Napi::AsyncProgressQueueWorker` base class will store
+persistently. When the work on the `Napi::AsyncProgressQueueWorker::Execute`
+method is done the `Napi::AsyncProgressQueueWorker::OnOk` method is called and
+the results are returned 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::AsyncProgressQueueWorker`.
+
+```cpp
+#include <napi.h>
+
+// Include EchoWorker class
+// ..
+
+using namespace Napi;
+
+Value Echo(const CallbackInfo& info) {
+    // We need to validate the arguments here.
+    std::string in = info[0].As<String>();
+    Function errorCb = info[1].As<Function>();
+    Function okCb = info[2].As<Function>();
+    Function progressCb = info[3].As<Function>();
+    EchoWorker* wk = new EchoWorker(okCb, errorCb, progressCb, in);
+    wk->Queue();
+    return info.Env().Undefined();
+}
+
+// Register the native method for JS to access
+Object Init(Env env, Object exports)
+{
+    exports.Set(String::New(env, "echo"), Function::New(env, Echo));
+
+    return exports;
+}
+
+// Register our native addon
+NODE_API_MODULE(nativeAddon, Init)
+```
+
+The implementation of a `Napi::AsyncProgressQueueWorker` 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::AsyncProgressQueueWorker::Queue`
+method that will queue the created worker for execution.
+
+Lastly, the following Javascript (ES6+) code would be associated the above example:
+
+```js
+const { nativeAddon } = require('binding.node');
+
+const onErrorCallback = (msg) => {
+    // Use the data accordingly
+    // ...
+};
+
+const onOkCallback = (echo) => {
+    // Use the data accordingly
+    // ...
+};
+
+const onProgressCallback = (num) => {
+    // Use the data accordingly
+    // ...
+};
+
+// Call our native addon with the parameters of a string and three callback functions
+nativeAddon.echo("example", onErrorCallback, onOkCallback, onProgressCallback);
+```
+
+[`Napi::AsyncWorker`]: ./async_worker.md

package/vendor/node-addon-api/doc/bigint.md

@@ -0,0 +1,97 @@
+# BigInt
+
+Class `Napi::Bigint` inherits from class [`Napi::Value`][].
+
+A JavaScript BigInt value.
+
+## Methods
+
+### New
+
+```cpp
+static Napi::BigInt Napi::BigInt::New(Napi::Env env, int64_t value);
+static Napi::BigInt Napi::BigInt::New(Napi::Env env, uint64_t value);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::BigInt` object.
+ - `[in] value`: The value the JavaScript `BigInt` will contain
+
+These APIs convert the C `int64_t` and `uint64_t` types to the JavaScript
+`BigInt` type.
+
+```cpp
+static Napi::BigInt Napi::BigInt::New(Napi::Env env,
+                  int sign_bit,
+                  size_t word_count,
+                  const uint64_t* words);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::BigInt` object.
+ - `[in] sign_bit`: Determines if the resulting `BigInt` will be positive or negative.
+ - `[in] word_count`: The length of the words array.
+ - `[in] words`: An array of `uint64_t` little-endian 64-bit words.
+
+This API converts an array of unsigned 64-bit words into a single `BigInt`
+value.
+
+The resulting `BigInt` is calculated as: (–1)<sup>`sign_bit`</sup> (`words[0]`
+× (2<sup>64</sup>)<sup>0</sup> + `words[1]` × (2<sup>64</sup>)<sup>1</sup> + …)
+
+Returns a new JavaScript `BigInt`.
+
+### Constructor
+
+```cpp
+Napi::BigInt();
+```
+
+Returns a new empty JavaScript `Napi::BigInt`.
+
+### Int64Value
+
+```cpp
+int64_t Napi::BigInt::Int64Value(bool* lossless) const;
+```
+
+ - `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly.
+
+Returns the C `int64_t` primitive equivalent of the given JavaScript
+`BigInt`. If needed it will truncate the value, setting lossless to false.
+
+### Uint64Value
+
+```cpp
+uint64_t Napi::BigInt::Uint64Value(bool* lossless) const;
+```
+
+ - `[out] lossless`: Indicates whether the `BigInt` value was converted
+   losslessly.
+
+Returns the C `uint64_t` primitive equivalent of the given JavaScript
+`BigInt`. If needed it will truncate the value, setting lossless to false.
+
+### WordCount
+
+```cpp
+size_t Napi::BigInt::WordCount() const;
+```
+
+Returns the number of words needed to store this `BigInt` value.
+
+### ToWords
+
+```cpp
+void Napi::BigInt::ToWords(int* sign_bit, size_t* word_count, uint64_t* words);
+```
+
+ - `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive
+   or negative.
+ - `[in/out] word_count`: Must be initialized to the length of the words array.
+   Upon return, it will be set to the actual number of words that would be
+   needed to store this `BigInt`.
+ - `[out] words`: Pointer to a pre-allocated 64-bit word array.
+
+Returns a single `BigInt` value into a sign bit, 64-bit little-endian array,
+and the number of elements in the array.
+
+[`Napi::Value`]: ./value.md