koffi 2.16.0-beta.2 → 2.16.1

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

@@ -1,290 +0,0 @@
-# ThreadSafeFunction
-
-The `Napi::ThreadSafeFunction` type provides APIs for threads to communicate
-with the addon's main thread to invoke JavaScript functions on their behalf.
-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::ThreadSafeFunction`.
-
-```cpp
-Napi::Function::ThreadSafeFunction();
-```
-
-### Constructor
-
-Creates a new instance of the `Napi::ThreadSafeFunction` object.
-
-```cpp
-Napi::ThreadSafeFunction::ThreadSafeFunction(napi_threadsafe_function tsfn);
-```
-
-- `tsfn`: The `napi_threadsafe_function` which is a handle for an existing
-  thread-safe function.
-
-Returns a non-empty `Napi::ThreadSafeFunction` instance. When using this
-constructor, only use the `Blocking(void*)` / `NonBlocking(void*)` overloads;
-the `Callback` and templated `data*` overloads should _not_ be used. See below
-for additional details.
-
-### New
-
-Creates a new instance of the `Napi::ThreadSafeFunction` 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,
-    const Function& callback,
-    const Object& resource,
-    ResourceString resourceName,
-    size_t maxQueueSize,
-    size_t initialThreadCount,
-    ContextType* context,
-    Finalizer finalizeCallback,
-    FinalizerDataType* data);
-```
-
-- `env`: The `napi_env` environment in which to construct the
-  `Napi::ThreadSafeFunction` object.
-- `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 retreived by calling `GetContext()`.
-- `[optional] finalizeCallback`: Function to call when the `ThreadSafeFunction`
-  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, DataType* data,
-  ContextType* hint)`, skipping `data` or `hint` if they are not provided. Can
-  be retrieved via `GetContext()`.
-- `[optional] data`: Data to be passed to `finalizeCallback`.
-
-Returns a non-empty `Napi::ThreadSafeFunction` instance.
-
-### Acquire
-
-Add 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::ThreadSafeFunction::Acquire() const
-```
-
-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
-
-Indicate 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 it may have been destroyed.
-
-```cpp
-napi_status Napi::ThreadSafeFunction::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
-
-"Abort" 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::ThreadSafeFunction::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.
-
-There are several overloaded implementations of `BlockingCall()` and
-`NonBlockingCall()` for use with optional parameters: skip the optional
-parameter for that specific overload.
-
-**These specific function overloads should only be used on a `ThreadSafeFunction`
-created via `ThreadSafeFunction::New`.**
-
-```cpp
-napi_status Napi::ThreadSafeFunction::BlockingCall(DataType* data, Callback callback) const
-
-napi_status Napi::ThreadSafeFunction::NonBlockingCall(DataType* data, Callback callback) const
-```
-
-- `[optional] data`: Data to pass to `callback`.
-- `[optional] callback`: C++ function that is invoked on the main thread. The
-  callback receives the `ThreadSafeFunction`'s JavaScript callback function to
-  call as an `Napi::Function` in its parameters and the `DataType*` data pointer
-  (if provided). Must implement `void operator()(Napi::Env env, Function
-  jsCallback, DataType* data)`, skipping `data` if not provided. It is not
-  necessary to call into JavaScript via `MakeCallback()` because Node-API runs
-  `callback` in a context appropriate for callbacks.
-
-**These specific function overloads should only be used on a `ThreadSafeFunction`
-created via `ThreadSafeFunction(napi_threadsafe_function)`.**
-
-```cpp
-napi_status Napi::ThreadSafeFunction::BlockingCall(void* data) const
-
-napi_status Napi::ThreadSafeFunction::NonBlockingCall(void* data) const
-```
-- `data`: Data to pass to `call_js_cb` specified when creating the thread-safe
-  function via `napi_create_threadsafe_function`.
-
-Returns one of:
-- `napi_ok`: The call 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 cannot accept more
-  calls.
-- `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 <thread>
-#include <napi.h>
-
-using namespace Napi;
-
-std::thread nativeThread;
-ThreadSafeFunction 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 ThreadSafeFunction
-  tsfn = ThreadSafeFunction::New(
-      env,
-      info[0].As<Function>(),  // JavaScript function called asynchronously
-      "Resource Name",         // Name
-      0,                       // Unlimited queue
-      1,                       // Only one thread will use this initially
-      []( Napi::Env ) {        // Finalizer used to clean threads up
-        nativeThread.join();
-      } );
-
-  // Create a native thread
-  nativeThread = std::thread( [count] {
-    auto callback = []( Napi::Env env, Function jsCallback, int* value ) {
-      // Transform native data into JS data, passing it to the provided
-      // `jsCallback` -- the TSFN's JavaScript function.
-      jsCallback.Call( {Number::New( env, *value )} );
-
-      // We're finished with the data.
-      delete value;
-    };
-
-    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, callback );
-      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);
-}
-
-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(function () {
-    console.log("JavaScript callback called with arguments", Array.from(arguments));
-}, 5);
-```
-
-When executed, the output will show the value of `clock()` five times at one
-second intervals:
-
-```
-JavaScript callback called with arguments [ 84745 ]
-JavaScript callback called with arguments [ 103211 ]
-JavaScript callback called with arguments [ 104516 ]
-JavaScript callback called with arguments [ 105104 ]
-JavaScript callback called with arguments [ 105691 ]
-```

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

@@ -1,59 +0,0 @@
-# TypeError
-
-The `Napi::TypeError` class is a representation of the JavaScript `TypeError` that is
-thrown when an operand or argument passed to a function is incompatible with the
-type expected by the operator or function.
-
-The `Napi::TypeError` class inherits its behaviors from the `Napi::Error` class (for more info
-see: [`Napi::Error`](error.md)).
-
-For more details about error handling refer to the section titled [Error handling](error_handling.md).
-
-## Methods
-
-### New
-
-Creates a new instance of the `Napi::TypeError` object.
-
-```cpp
-Napi::TypeError::New(Napi::Env env, const char* message);
-```
-
-- `[in] Env`: The environment in which to construct the `Napi::TypeError` object.
-- `[in] message`: Null-terminated string to be used as the message for the `Napi::TypeError`.
-
-Returns an instance of a `Napi::TypeError` object.
-
-### New
-
-Creates a new instance of a `Napi::TypeError` object.
-
-```cpp
-Napi::TypeError::New(Napi::Env env, const std::string& message);
-```
-
-- `[in] Env`: The environment in which to construct the `Napi::TypeError` object.
-- `[in] message`: Reference string to be used as the message for the `Napi::TypeError`.
-
-Returns an instance of a `Napi::TypeError` object.
-
-### Constructor
-
-Creates a new empty instance of a `Napi::TypeError`.
-
-```cpp
-Napi::TypeError::TypeError();
-```
-
-### Constructor
-
-Initializes a `Napi::TypeError` instance from an existing JavaScript error object.
-
-```cpp
-Napi::TypeError::TypeError(napi_env env, napi_value value);
-```
-
-- `[in] Env`: The environment in which to construct the `Napi::TypeError` object.
-- `[in] value`: The `Napi::Error` reference to wrap.
-
-Returns an instance of a `Napi::TypeError` object.

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

@@ -1,40 +0,0 @@
-# TypeTaggable
-
-Class `Napi::TypeTaggable` inherits from class [`Napi::Value`][].
-
-The `Napi::TypeTaggable` class is the base class for [`Napi::Object`][] and
-[`Napi::External`][]. It adds type-tagging capabilities to both. It is an
-abstract-only base class.
-
-### TypeTag()
-
-```cpp
-void Napi::TypeTaggable::TypeTag(const napi_type_tag* type_tag) const;
-```
-
-- `[in] type_tag`: The tag with which this object or external is to be marked.
-
-The `Napi::TypeTaggable::TypeTag()` method associates the value of the
-`type_tag` pointer with this JavaScript object or external.
-`Napi::TypeTaggable::CheckTypeTag()` can then be used to compare the tag that
-was attached with one owned by the add-on to ensure that this object or external
-has the right type.
-
-### CheckTypeTag()
-
-```cpp
-bool Napi::TypeTaggable::CheckTypeTag(const napi_type_tag* type_tag) const;
-```
-
-- `[in] type_tag`: The tag with which to compare any tag found on this object or
-  external.
-
-The `Napi::TypeTaggable::CheckTypeTag()` method compares the pointer given as
-`type_tag` with any that can be found on this JavaScript object or external. If
-no tag is found or if a tag is found but it does not match `type_tag`, then the
-return value is `false`. If a tag is found and it matches `type_tag`, then the
-return value is `true`.
-
-[`Napi::Value`]: ./value.md
-[`Napi::Object`]: ./object.md
-[`Napi::External`]: ./external.md

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

@@ -1,78 +0,0 @@
-# TypedArray
-
-Class `Napi::TypedArray` inherits from class [`Napi::Object`][].
-
-The `Napi::TypedArray` class corresponds to the
-[JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
-class.
-
-## Methods
-
-### Constructor
-
-Initializes an empty instance of the `Napi::TypedArray` class.
-
-```cpp
-Napi::TypedArray::TypedArray();
-```
-
-### Constructor
-
-Initializes a wrapper instance of an existing `Napi::TypedArray` instance.
-
-```cpp
-Napi::TypedArray::TypedArray(napi_env env, napi_value value);
-```
-
-- `[in] env`: The environment in which to create the `Napi::TypedArray` instance.
-- `[in] value`: The `Napi::TypedArray` reference to wrap.
-
-### TypedArrayType
-
-```cpp
-napi_typedarray_type Napi::TypedArray::TypedArrayType() const;
-```
-
-Returns the type of this instance.
-
-### ArrayBuffer
-
-```cpp
-Napi::ArrayBuffer Napi::TypedArray::ArrayBuffer() const;
-```
-
-Returns the backing array buffer.
-
-### ElementSize
-
-```cpp
-uint8_t Napi::TypedArray::ElementSize() const;
-```
-
-Returns the size of one element, in bytes.
-
-### ElementLength
-
-```cpp
-size_t Napi::TypedArray::ElementLength() const;
-```
-
-Returns the number of elements.
-
-### ByteOffset
-
-```cpp
-size_t Napi::TypedArray::ByteOffset() const;
-```
-
-Returns the offset into the `Napi::ArrayBuffer` where the array starts, in bytes.
-
-### ByteLength
-
-```cpp
-size_t Napi::TypedArray::ByteLength() const;
-```
-
-Returns the length of the array, in bytes.
-
-[`Napi::Object`]: ./object.md

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

@@ -1,137 +0,0 @@
-# TypedArrayOf
-
-Class `Napi::TypedArrayOf<T>` inherits from class [`Napi::TypedArray`][].
-
-The `Napi::TypedArrayOf` class corresponds to the various
-[JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
-classes.
-
-## Typedefs
-
-The common JavaScript `TypedArray` types are pre-defined for each of use:
-
-```cpp
-using Int8Array = Napi::TypedArrayOf<int8_t>;
-using Uint8Array = Napi::TypedArrayOf<uint8_t>;
-using Int16Array = Napi::TypedArrayOf<int16_t>;
-using Uint16Array = Napi::TypedArrayOf<uint16_t>;
-using Int32Array = Napi::TypedArrayOf<int32_t>;
-using Uint32Array = Napi::TypedArrayOf<uint32_t>;
-using Float32Array = Napi::TypedArrayOf<float>;
-using Float64Array = Napi::TypedArrayOf<double>;
-```
-
-The one exception is the `Uint8ClampedArray` which requires explicit
-initialization:
-
-```cpp
-Uint8Array::New(env, length, napi_uint8_clamped_array)
-```
-
-Note that while it's possible to create a "clamped" array the _clamping_
-behavior is only applied in JavaScript.
-
-## Methods
-
-### New
-
-Allocates a new `Napi::TypedArray` instance with a given length. The underlying
-`Napi::ArrayBuffer` is allocated automatically to the desired number of elements.
-
-The array type parameter can normally be omitted (because it is inferred from
-the template parameter T), except when creating a "clamped" array.
-
-```cpp
-static Napi::TypedArrayOf Napi::TypedArrayOf::New(napi_env env,
-                        size_t elementLength,
-                        napi_typedarray_type type);
-```
-
-- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` instance.
-- `[in] elementLength`: The length to be allocated, in elements.
-- `[in] type`: The type of array to allocate (optional).
-
-Returns a new `Napi::TypedArrayOf` instance.
-
-### New
-
-Wraps the provided `Napi::ArrayBuffer` into a new `Napi::TypedArray` instance.
-
-The array `type` parameter can normally be omitted (because it is inferred from
-the template parameter `T`), except when creating a "clamped" array.
-
-```cpp
-static Napi::TypedArrayOf Napi::TypedArrayOf::New(napi_env env,
-                        size_t elementLength,
-                        Napi::ArrayBuffer arrayBuffer,
-                        size_t bufferOffset,
-                        napi_typedarray_type type);
-```
-
-- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` instance.
-- `[in] elementLength`: The length to array, in elements.
-- `[in] arrayBuffer`: The backing `Napi::ArrayBuffer` instance.
-- `[in] bufferOffset`: The offset into the `Napi::ArrayBuffer` where the array starts,
-                       in bytes.
-- `[in] type`: The type of array to allocate (optional).
-
-Returns a new `Napi::TypedArrayOf` instance.
-
-### Constructor
-
-Initializes an empty instance of the `Napi::TypedArrayOf` class.
-
-```cpp
-Napi::TypedArrayOf::TypedArrayOf();
-```
-
-### Constructor
-
-Initializes a wrapper instance of an existing `Napi::TypedArrayOf` object.
-
-```cpp
-Napi::TypedArrayOf::TypedArrayOf(napi_env env, napi_value value);
-```
-
-- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` object.
-- `[in] value`: The `Napi::TypedArrayOf` reference to wrap.
-
-### operator []
-
-```cpp
-T& Napi::TypedArrayOf::operator [](size_t index);
-```
-
-- `[in] index: The element index into the array.
-
-Returns the element found at the given index.
-
-### operator []
-
-```cpp
-const T& Napi::TypedArrayOf::operator [](size_t index) const;
-```
-
-- `[in] index: The element index into the array.
-
-Returns the element found at the given index.
-
-### Data
-
-```cpp
-T* Napi::TypedArrayOf::Data() const;
-```
-
-Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the
-start of the array.
-
-### Data
-
-```cpp
-const T* Napi::TypedArrayOf::Data() const
-```
-
-Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the
-start of the array.
-
-[`Napi::TypedArray`]: ./typed_array.md