koffi 2.16.0-beta.2 → 2.16.0

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

@@ -1,306 +0,0 @@
-# TypedThreadSafeFunction
-
-The `Napi::TypedThreadSafeFunction` type provides APIs for threads to
-communicate with the addon's main thread to invoke JavaScript functions on their
-behalf. The type is a three-argument templated class, each argument representing
-the type of:
-- `ContextType = std::nullptr_t`: The thread-safe function's context. By
-  default, a TSFN has no context.
-- `DataType = void*`: The data to use in the native callback. By default, a TSFN
-  can accept any data type.
-- `Callback = void(*)(Napi::Env, Napi::Function jsCallback, ContextType*,
-  DataType*)`: The callback to run for each item added to the queue. If no
-  `Callback` is given, the API will call the function `jsCallback` with no
-  arguments.
-
-Documentation can be found for an [overview of the API](threadsafe.md), as well
-as [differences between the two thread-safe function
-APIs](threadsafe.md#implementation-differences).
-
-## Methods
-
-### Constructor
-
-Creates a new empty instance of `Napi::TypedThreadSafeFunction`.
-
-```cpp
-Napi::Function::TypedThreadSafeFunction<ContextType, DataType, Callback>::TypedThreadSafeFunction();
-```
-
-### Constructor
-
-Creates a new instance of the `Napi::TypedThreadSafeFunction` object.
-
-```cpp
-Napi::TypedThreadSafeFunction<ContextType, DataType, Callback>::TypedThreadSafeFunction(napi_threadsafe_function tsfn);
-```
-
-- `tsfn`: The `napi_threadsafe_function` which is a handle for an existing
-  thread-safe function.
-
-Returns a non-empty `Napi::TypedThreadSafeFunction` instance. To ensure the API
-statically handles the correct return type for `GetContext()` and
-`[Non]BlockingCall()`, pass the proper template arguments to
-`Napi::TypedThreadSafeFunction`.
-
-### New
-
-Creates a new instance of the `Napi::TypedThreadSafeFunction` object. The `New`
-function has several overloads for the various optional parameters: skip the
-optional parameter for that specific overload.
-
-```cpp
-New(napi_env env,
-    CallbackType callback,
-    const Object& resource,
-    ResourceString resourceName,
-    size_t maxQueueSize,
-    size_t initialThreadCount,
-    ContextType* context,
-    Finalizer finalizeCallback,
-    FinalizerDataType* data = nullptr);
-```
-
-- `env`: The `napi_env` environment in which to construct the
-  `Napi::ThreadSafeFunction` object.
-- `[optional] callback`: The `Function` to call from another thread.
-- `[optional] resource`: An object associated with the async work that will be
-  passed to possible async_hooks init hooks.
-- `resourceName`: A JavaScript string to provide an identifier for the kind of
-  resource that is being provided for diagnostic information exposed by the
-  async_hooks API.
-- `maxQueueSize`: Maximum size of the queue. `0` for no limit.
-- `initialThreadCount`: The initial number of threads, including the main
-  thread, which will be making use of this function.
-- `[optional] context`: Data to attach to the resulting `ThreadSafeFunction`. It
-  can be retrieved via `GetContext()`.
-- `[optional] finalizeCallback`: Function to call when the
-  `TypedThreadSafeFunction` is being destroyed.  This callback will be invoked
-  on the main thread when the thread-safe function is about to be destroyed. It
-  receives the context and the finalize data given during construction (if
-  given), and provides an opportunity for cleaning up after the threads e.g. by
-  calling `uv_thread_join()`. It is important that, aside from the main loop
-  thread, there be no threads left using the thread-safe function after the
-  finalize callback completes. Must implement `void operator()(Env env,
-  FinalizerDataType* data, ContextType* hint)`.
-- `[optional] data`: Data to be passed to `finalizeCallback`.
-
-Returns a non-empty `Napi::TypedThreadSafeFunction` instance.
-
-Depending on the targeted `NAPI_VERSION`, the API has different implementations
-for `CallbackType callback`.
-
-When targeting version 4, `callback` may be:
-- of type `const Function&`
-- not provided as a parameter, in which case the API creates a new no-op
-  `Function`
-
-When targeting version 5+, `callback` may be:
-- of type `const Function&`
-- of type `std::nullptr_t`
-- not provided as a parameter, in which case the API passes `std::nullptr`
-
-### Acquire
-
-Adds a thread to this thread-safe function object, indicating that a new thread
-will start making use of the thread-safe function.
-
-```cpp
-napi_status Napi::TypedThreadSafeFunction<ContextType, DataType, Callback>::Acquire()
-```
-
-Returns one of:
-- `napi_ok`: The thread has successfully acquired the thread-safe function for
-  its use.
-- `napi_closing`: The thread-safe function has been marked as closing via a
-  previous call to `Abort()`.
-
-### Release
-
-Indicates that an existing thread will stop making use of the thread-safe
-function. A thread should call this API when it stops making use of this
-thread-safe function. Using any thread-safe APIs after having called this API
-has undefined results in the current thread, as the thread-safe function may
-have been destroyed.
-
-```cpp
-napi_status Napi::TypedThreadSafeFunction<ContextType, DataType, Callback>::Release() const
-```
-
-Returns one of:
-- `napi_ok`: The thread-safe function has been successfully released.
-- `napi_invalid_arg`: The thread-safe function's thread-count is zero.
-- `napi_generic_failure`: A generic error occurred when attempting to release the
-  thread-safe function.
-
-### Abort
-
-"Aborts" the thread-safe function. This will cause all subsequent APIs
-associated with the thread-safe function except `Release()` to return
-`napi_closing` even before its reference count reaches zero. In particular,
-`BlockingCall` and `NonBlockingCall()` will return `napi_closing`, thus
-informing the threads that it is no longer possible to make asynchronous calls
-to the thread-safe function. This can be used as a criterion for terminating the
-thread. Upon receiving a return value of `napi_closing` from a thread-safe
-function call a thread must make no further use of the thread-safe function
-because it is no longer guaranteed to be allocated.
-
-```cpp
-napi_status Napi::TypedThreadSafeFunction<ContextType, DataType, Callback>::Abort() const
-```
-
-Returns one of:
-- `napi_ok`: The thread-safe function has been successfully aborted.
-- `napi_invalid_arg`: The thread-safe function's thread-count is zero.
-- `napi_generic_failure`: A generic error occurred when attempting to abort the
-  thread-safe function.
-
-### BlockingCall / NonBlockingCall
-
-Calls the Javascript function in either a blocking or non-blocking fashion.
-- `BlockingCall()`: the API blocks until space becomes available in the queue.
-  Will never block if the thread-safe function was created with a maximum queue
-  size of `0`.
-- `NonBlockingCall()`: will return `napi_queue_full` if the queue was full,
-  preventing data from being successfully added to the queue.
-
-```cpp
-napi_status Napi::TypedThreadSafeFunction<ContextType, DataType, Callback>::BlockingCall(DataType* data = nullptr) const
-
-napi_status Napi::TypedThreadSafeFunction<ContextType, DataType, Callback>::NonBlockingCall(DataType* data = nullptr) const
-```
-
-- `[optional] data`: Data to pass to the callback which was passed to
-  `TypedThreadSafeFunction::New()`.
-
-Returns one of:
-- `napi_ok`: `data` was successfully added to the queue.
-- `napi_queue_full`: The queue was full when trying to call in a non-blocking
-  method.
-- `napi_closing`: The thread-safe function is aborted and no further calls can
-  be made.
-- `napi_invalid_arg`: The thread-safe function is closed.
-- `napi_generic_failure`: A generic error occurred when attempting to add to the
-  queue.
-
-
-## Example
-
-```cpp
-#include <chrono>
-#include <napi.h>
-#include <thread>
-
-using namespace Napi;
-
-using Context = Reference<Value>;
-using DataType = int;
-void CallJs(Napi::Env env, Function callback, Context *context, DataType *data);
-using TSFN = TypedThreadSafeFunction<Context, DataType, CallJs>;
-using FinalizerDataType = void;
-
-std::thread nativeThread;
-TSFN tsfn;
-
-Value Start(const CallbackInfo &info) {
-  Napi::Env env = info.Env();
-
-  if (info.Length() < 2) {
-    throw TypeError::New(env, "Expected two arguments");
-  } else if (!info[0].IsFunction()) {
-    throw TypeError::New(env, "Expected first arg to be function");
-  } else if (!info[1].IsNumber()) {
-    throw TypeError::New(env, "Expected second arg to be number");
-  }
-
-  int count = info[1].As<Number>().Int32Value();
-
-  // Create a new context set to the receiver (ie, `this`) of the function call
-  Context *context = new Reference<Value>(Persistent(info.This()));
-
-  // Create a ThreadSafeFunction
-  tsfn = TSFN::New(
-      env,
-      info[0].As<Function>(), // JavaScript function called asynchronously
-      "Resource Name",        // Name
-      0,                      // Unlimited queue
-      1,                      // Only one thread will use this initially
-      context,
-      [](Napi::Env, FinalizerDataType *,
-         Context *ctx) { // Finalizer used to clean threads up
-        nativeThread.join();
-        delete ctx;
-      });
-
-  // Create a native thread
-  nativeThread = std::thread([count] {
-    for (int i = 0; i < count; i++) {
-      // Create new data
-      int *value = new int(clock());
-
-      // Perform a blocking call
-      napi_status status = tsfn.BlockingCall(value);
-      if (status != napi_ok) {
-        // Handle error
-        break;
-      }
-
-      std::this_thread::sleep_for(std::chrono::seconds(1));
-    }
-
-    // Release the thread-safe function
-    tsfn.Release();
-  });
-
-  return Boolean::New(env, true);
-}
-
-// Transform native data into JS data, passing it to the provided
-// `callback` -- the TSFN's JavaScript function.
-void CallJs(Napi::Env env, Function callback, Context *context,
-            DataType *data) {
-  // Is the JavaScript environment still available to call into, eg. the TSFN is
-  // not aborted
-  if (env != nullptr) {
-    // On Node-API 5+, the `callback` parameter is optional; however, this example
-    // does ensure a callback is provided.
-    if (callback != nullptr) {
-      callback.Call(context->Value(), {Number::New(env, *data)});
-    }
-  }
-  if (data != nullptr) {
-    // We're finished with the data.
-    delete data;
-  }
-}
-
-Napi::Object Init(Napi::Env env, Object exports) {
-  exports.Set("start", Function::New(env, Start));
-  return exports;
-}
-
-NODE_API_MODULE(clock, Init)
-```
-
-The above code can be used from JavaScript as follows:
-
-```js
-const { start } = require('bindings')('clock');
-
-start.call(new Date(), function (clock) {
-    const context = this;
-    console.log(context, clock);
-}, 5);
-```
-
-When executed, the output will show the value of `clock()` five times at one
-second intervals, prefixed with the TSFN's context -- `start`'s receiver (ie,
-`new Date()`):
-
-```
-2020-08-18T21:04:25.116Z 49824
-2020-08-18T21:04:25.116Z 62493
-2020-08-18T21:04:25.116Z 62919
-2020-08-18T21:04:25.116Z 63228
-2020-08-18T21:04:25.116Z 63531
-```

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

@@ -1,368 +0,0 @@
-# Value
-
-`Napi::Value` is the C++ manifestation of a JavaScript value. It is the base
-class upon which other JavaScript values such as `Napi::Number`,
-`Napi::Boolean`, `Napi::String`, and `Napi::Object` are based. It represents a
-JavaScript value of an unknown type. It is a thin wrapper around the Node-API
-datatype `napi_value`. Methods on this class can be used to check the JavaScript
-type of the underlying Node-API `napi_value` and also to convert to C++ types.
-
-## Constructors
-
-### Empty Constructor
-
-```cpp
-Napi::Value::Value();
-```
-
-Creates a new *empty* `Napi::Value` instance.
-
-### Constructor
-
-```cpp
-Napi::Value::Value(napi_env env, napi_value value);
-```
-
-- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value`
-object.
-- `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`.
-value` may be any of:
-  - `bool`
-  - Any integer type
-  - Any floating point type
-  - `const char*` (encoded using UTF-8, null-terminated)
-  - `const char16_t*` (encoded using UTF-16-LE, null-terminated)
-  - `std::string` (encoded using UTF-8)
-  - `std::u16string`
-  - `Napi::Value`
-  - `napi_value`
-
-## Operators
-
-### operator napi_value
-
-```cpp
-Napi::Value::operator napi_value() const;
-```
-
-Returns the underlying Node-API `napi_value`. If the instance is _empty_, this
-returns `nullptr`.
-
-### operator ==
-
-```cpp
-bool Napi::Value::operator ==(const Napi::Value& other) const;
-```
-
-Returns `true` if this value strictly equals another value, or `false`
-otherwise.
-
-### operator !=
-
-```cpp
-bool Napi::Value::operator !=(const Napi::Value& other) const;
-```
-
-Returns `false` if this value strictly equals another value, or `true`
-otherwise.
-
-## Methods
-
-### As
-
-```cpp
-template <typename T> T Napi::Value::As() const;
-```
-
-Casts to another type of `Napi::Value`, when the actual type is known or
-assumed.
-
-This conversion does not coerce the type. Calling any methods inappropriate for
-the actual value type will throw `Napi::Error`. When C++ exceptions are
-disabled, the thrown error will not be reflected before control returns to
-JavaScript.
-
-In order to enforce expected type, use `Napi::Value::Is*()` methods to check
-the type before calling `Napi::Value::As()`, or compile with definition
-`NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` to enforce type checks.
-
-### UnsafeAs
-
-```cpp
-template <typename T> T Napi::Value::UnsafeAs() const;
-```
-
-Casts to another type of `Napi::Value`, when the actual type is known or
-assumed.
-
-This conversion does not coerce the type. This does not check the type even if
-`NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` is defined. This indicates intentional
-unsafe type cast. Use `Napi::Value::As()` if possible.
-
-### Env
-
-```cpp
-Napi::Env Napi::Value::Env() const;
-```
-
-Returns the `Napi::Env` environment this value is associated with. See
-[`Napi::Env`](env.md) for more details about environments.
-
-### From
-
-```cpp
-template <typename T>
-static Napi::Value Napi::Value::From(napi_env env, const T& value);
-```
-
-- `[in] env`: The `napi_env` environment in which to create the `Napi::Value`
-object.
-- `[in] value`: The Node-API primitive value from which to create the `Napi::Value`
-object.
-
-Returns a `Napi::Value` object from an Node-API primitive value.
-
-This method is used to convert from a C++ type to a JavaScript value.
-Here, `value` may be any of:
-- `bool` - returns a `Napi::Boolean`.
-- Any integer type - returns a `Napi::Number`.
-- Any floating point type - returns a `Napi::Number`.
-- `const char*` (encoded using UTF-8, null-terminated) - returns a
-`Napi::String`.
-- `const char16_t*` (encoded using UTF-16-LE, null-terminated) - returns a
-`Napi::String`.
-- `std::string` (encoded using UTF-8) - returns a `Napi::String`.
-- `std::u16string` - returns a `Napi::String`.
-- `Napi::Value` - returns a `Napi::Value`.
-- `Napi_value` - returns a `Napi::Value`.
-
-### IsArray
-
-```cpp
-bool Napi::Value::IsArray() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false`
-otherwise.
-
-### IsArrayBuffer
-
-```cpp
-bool Napi::Value::IsArrayBuffer() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or
-`false` otherwise.
-
-### IsBigInt
-
-```cpp
-bool Napi::Value::IsBigInt() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::BigInt` or `false`
-otherwise.
-
-### IsBoolean
-
-```cpp
-bool Napi::Value::IsBoolean() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `true` or JavaScript
-`false`, or `false` if the value is not a `Napi::Boolean` value in JavaScript.
-
-### IsBuffer
-
-```cpp
-bool Napi::Value::IsBuffer() const;
-```
-
-Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false`
-otherwise.
-
-### IsDataView
-```cpp
-bool Napi::Value::IsDataView() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::DataView` or
-`false` otherwise.
-
-### IsDate
-
-```cpp
-bool Napi::Value::IsDate() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Date` or `false`
-otherwise.
-
-### IsEmpty
-
-```cpp
-bool Napi::Value::IsEmpty() const;
-```
-
-Returns `true` if the value is uninitialized.
-
-An empty `Napi::Value` is invalid, and most attempts to perform an operation on
-an empty `Napi::Value` will result in an exception. An empty `Napi::Value` is
-distinct from JavaScript `null` or `undefined`, which are valid values.
-
-When C++ exceptions are disabled at compile time, a method with a `Napi::Value`
-return type may return an empty `Napi::Value` to indicate a pending exception.
-Thus, when C++ exceptions are not being used, callers should check the result of
-`Env::IsExceptionPending` before attempting to use the value.
-
-### IsExternal
-```cpp
-bool Napi::Value::IsExternal() const;
-```
-
-Returns `true` if the underlying value is a Node-API external object or `false`
-otherwise.
-
-### IsFunction
-
-```cpp
-bool Napi::Value::IsFunction() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::Function` or
-`false` otherwise.
-
-### IsNull
-
-```cpp
-bool Napi::Value::IsNull() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `null` or `false`
-otherwise.
-
-### IsNumber
-
-```cpp
-bool Napi::Value::IsNumber() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false`
-otherwise.
-
-### IsObject
-
-```cpp
-bool Napi::Value::IsObject() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false`
-otherwise.
-
-### IsPromise
-
-```cpp
-bool Napi::Value::IsPromise() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::Promise` or
-`false` otherwise.
-
-### IsString
-
-```cpp
-bool Napi::Value::IsString() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::String` or `false`
-otherwise.
-
-### IsSymbol
-
-```cpp
-bool Napi::Value::IsSymbol() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false`
-otherwise.
-
-### IsTypedArray
-
-```cpp
-bool Napi::Value::IsTypedArray() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or
-`false` otherwise.
-
-### IsUndefined
-
-```cpp
-bool Napi::Value::IsUndefined() const;
-```
-
-Returns `true` if the underlying value is a JavaScript `undefined` or `false`
-otherwise.
-
-### StrictEquals
-
-```cpp
-bool Napi::Value::StrictEquals(const Napi::Value& other) const;
-```
-- `[in] other`: The `Napi::Value` object to be compared.
-
-Returns a `bool` indicating if this `Napi::Value` strictly equals another
-`Napi::Value`.
-
-### ToBoolean
-
-```cpp
-Napi::Boolean Napi::Value::ToBoolean() const;
-```
-
-Returns a `Napi::Boolean` representing the `Napi::Value`.
-
-This is a wrapper around `napi_coerce_to_boolean`. This will throw a JavaScript
-exception if the coercion fails. If C++ exceptions are not being used, callers
-should check the result of `Env::IsExceptionPending` before attempting to use
-the returned value.
-
-### ToNumber
-
-```cpp
-Napi::Number Napi::Value::ToNumber() const;
-```
-
-Returns the `Napi::Value` coerced to a JavaScript number.
-
-### ToObject
-
-```cpp
-Napi::Object Napi::Value::ToObject() const;
-```
-
-Returns the `Napi::Value` coerced to a JavaScript object.
-
-### ToString
-
-```cpp
-Napi::String Napi::Value::ToString() const;
-```
-
-Returns the `Napi::Value` coerced to a JavaScript string.
-
-### Type
-
-```cpp
-napi_valuetype Napi::Value::Type() const;
-```
-
-Returns the `napi_valuetype` type of the `Napi::Value`.
-
-[`Napi::Boolean`]: ./boolean.md
-[`Napi::BigInt`]: ./bigint.md
-[`Napi::Date`]: ./date.md
-[`Napi::External`]: ./external.md
-[`Napi::Name`]: ./name.md
-[`Napi::Number`]: ./number.md
-[`Napi::Object`]: ./object.md

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

@@ -1,43 +0,0 @@
-# VersionManagement
-
-The `Napi::VersionManagement` class contains methods that allow information
-to be retrieved about the version of Node-API and Node.js. In some cases it is
-important to make decisions based on different versions of the system.
-
-## Methods
-
-### GetNapiVersion
-
-Retrieves the highest Node-API version supported by Node.js runtime.
-
-```cpp
-static uint32_t Napi::VersionManagement::GetNapiVersion(Napi::BasicEnv env);
-```
-
-- `[in] env`: The environment in which the API is invoked under.
-
-Returns the highest Node-API version supported by Node.js runtime.
-
-### GetNodeVersion
-
-Retrieves information about Node.js version present on the system. All the
-information is stored in the `napi_node_version` structure that is defined as
-shown below:
-
-```cpp
-typedef struct {
-  uint32_t major;
-  uint32_t minor;
-  uint32_t patch;
-  const char* release;
-} napi_node_version;
-````
-
-```cpp
-static const napi_node_version* Napi::VersionManagement::GetNodeVersion(Napi::BasicEnv env);
-```
-
-- `[in] env`: The environment in which the API is invoked under.
-
-Returns the structure a pointer to the structure `napi_node_version` populated by
-the version information of Node.js runtime.