node-addon-api 3.0.2 → 3.1.0

package/doc/threadsafe_function.md

@@ -1,41 +1,10 @@
 # ThreadSafeFunction
 
-JavaScript functions can normally only be called from a native addon's main
-thread. If an addon creates additional threads, then node-addon-api functions
-that require a `Napi::Env`, `Napi::Value`, or `Napi::Reference` must not be
-called from those threads.
-
-When an addon has additional threads and JavaScript functions need to be invoked
-based on the processing completed by those threads, those threads must
-communicate with the addon's main thread so that the main thread can invoke the
-JavaScript function on their behalf. The thread-safe function APIs provide an
-easy way to do this.
-
-These APIs provide the type `Napi::ThreadSafeFunction` as well as APIs to
-create, destroy, and call objects of this type.
-`Napi::ThreadSafeFunction::New()` creates a persistent reference that holds a
-JavaScript function which can be called from multiple threads. The calls happen
-asynchronously. This means that values with which the JavaScript callback is to
-be called will be placed in a queue, and, for each value in the queue, a call
-will eventually be made to the JavaScript function.
-
-`Napi::ThreadSafeFunction` objects are destroyed when every thread which uses
-the object has called `Release()` or has received a return status of
-`napi_closing` in response to a call to `BlockingCall()` or `NonBlockingCall()`.
-The queue is emptied before the `Napi::ThreadSafeFunction` is destroyed. It is
-important that `Release()` be the last API call made in conjunction with a given
-`Napi::ThreadSafeFunction`, because after the call completes, there is no
-guarantee that the `Napi::ThreadSafeFunction` is still allocated. For the same
-reason it is also important that no more use be made of a thread-safe function
-after receiving a return value of `napi_closing` in response to a call to
-`BlockingCall()` or `NonBlockingCall()`. Data associated with the
-`Napi::ThreadSafeFunction` can be freed in its `Finalizer` callback which was
-passed to `ThreadSafeFunction::New()`.
-
-Once the number of threads making use of a `Napi::ThreadSafeFunction` reaches
-zero, no further threads can start making use of it by calling `Acquire()`. In
-fact, all subsequent API calls associated with it, except `Release()`, will
-return an error value of `napi_closing`.
+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
 
@@ -92,7 +61,8 @@ New(napi_env env,
 - `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`.
+- `[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
@@ -101,8 +71,8 @@ New(napi_env env,
   `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,
-  Context* hint)`, skipping `data` or `hint` if they are not provided.
-  Can be retreived via `GetContext()`.
+  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.
@@ -110,7 +80,7 @@ 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. 
+will start making use of the thread-safe function.
 
 ```cpp
 napi_status Napi::ThreadSafeFunction::Acquire()
@@ -118,7 +88,7 @@ napi_status Napi::ThreadSafeFunction::Acquire()
 
 Returns one of:
 - `napi_ok`: The thread has successfully acquired the thread-safe function
-for its use. 
+for its use.
 - `napi_closing`: The thread-safe function has been marked as closing via a
 previous call to `Abort()`.
 
@@ -136,7 +106,7 @@ napi_status Napi::ThreadSafeFunction::Release()
 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 attemping to release
+- `napi_generic_failure`: A generic error occurred when attempting to release
 the thread-safe function.
 
 ### Abort
@@ -158,7 +128,7 @@ napi_status Napi::ThreadSafeFunction::Abort()
 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 attemping to abort
+- `napi_generic_failure`: A generic error occurred when attempting to abort
 the thread-safe function.
 
 ### BlockingCall / NonBlockingCall
@@ -210,7 +180,7 @@ Returns one of:
 - `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 attemping to add to the
+- `napi_generic_failure`: A generic error occurred when attempting to add to the
   queue.
 
 ## Example
@@ -258,10 +228,10 @@ Value Start( const CallbackInfo& info )
   // 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 
+      // 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;
     };

package/doc/typed_threadsafe_function.md

@@ -0,0 +1,307 @@
+# 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 retreived 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 targetted `NAPI_VERSION`, the API has different implementations
+for `CallbackType callback`.
+
+When targetting 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 targetting 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()
+```
+
+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 attemping 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()
+```
+
+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 attemping 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 attemping 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 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 N-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/doc/version_management.md

@@ -20,8 +20,8 @@ Returns the highest N-API version supported by Node.js runtime.
 
 ### GetNodeVersion
 
-Retrives information about Node.js version present on the system. All the
-information is stored in the `napi_node_version` structrue that is defined as
+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