node-addon-api 1.6.1 → 1.7.1

package/napi.h

@@ -1,9 +1,10 @@
 #ifndef SRC_NAPI_H_
 #define SRC_NAPI_H_
 
-#include "node_api.h"
+#include <node_api.h>
 #include <functional>
 #include <initializer_list>
+#include <memory>
 #include <string>
 #include <vector>
 
@@ -38,6 +39,64 @@ static_assert(sizeof(char16_t) == sizeof(wchar_t), "Size mismatch between char16
   #define NAPI_NOEXCEPT noexcept
 #endif
 
+#ifdef NAPI_CPP_EXCEPTIONS
+
+// When C++ exceptions are enabled, Errors are thrown directly. There is no need
+// to return anything after the throw statements. The variadic parameter is an
+// optional return value that is ignored.
+// We need _VOID versions of the macros to avoid warnings resulting from
+// leaving the NAPI_THROW_* `...` argument empty.
+
+#define NAPI_THROW(e, ...)  throw e
+#define NAPI_THROW_VOID(e)  throw e
+
+#define NAPI_THROW_IF_FAILED(env, status, ...)           \
+  if ((status) != napi_ok) throw Napi::Error::New(env);
+
+#define NAPI_THROW_IF_FAILED_VOID(env, status)           \
+  if ((status) != napi_ok) throw Napi::Error::New(env);
+
+#else // NAPI_CPP_EXCEPTIONS
+
+// When C++ exceptions are disabled, Errors are thrown as JavaScript exceptions,
+// which are pending until the callback returns to JS.  The variadic parameter
+// is an optional return value; usually it is an empty result.
+// We need _VOID versions of the macros to avoid warnings resulting from
+// leaving the NAPI_THROW_* `...` argument empty.
+
+#define NAPI_THROW(e, ...)                               \
+  do {                                                   \
+    (e).ThrowAsJavaScriptException();                    \
+    return __VA_ARGS__;                                  \
+  } while (0)
+
+#define NAPI_THROW_VOID(e)                               \
+  do {                                                   \
+    (e).ThrowAsJavaScriptException();                    \
+    return;                                              \
+  } while (0)
+
+#define NAPI_THROW_IF_FAILED(env, status, ...)           \
+  if ((status) != napi_ok) {                             \
+    Napi::Error::New(env).ThrowAsJavaScriptException();  \
+    return __VA_ARGS__;                                  \
+  }
+
+#define NAPI_THROW_IF_FAILED_VOID(env, status)           \
+  if ((status) != napi_ok) {                             \
+    Napi::Error::New(env).ThrowAsJavaScriptException();  \
+    return;                                              \
+  }
+
+#endif // NAPI_CPP_EXCEPTIONS
+
+#define NAPI_FATAL_IF_FAILED(status, location, message)  \
+  do {                                                   \
+    if ((status) != napi_ok) {                           \
+      Napi::Error::Fatal((location), (message));         \
+    }                                                    \
+  } while (0)
+
 ////////////////////////////////////////////////////////////////////////////////
 /// N-API C++ Wrapper Classes
 ///
@@ -601,7 +660,7 @@ namespace Napi {
       uint32_t index ///< Property / element index
     );
 
-    Array GetPropertyNames(); ///< Get all property names
+    Array GetPropertyNames() const; ///< Get all property names
 
     /// Defines a property on the object.
     void DefineProperty(
@@ -633,12 +692,12 @@ namespace Napi {
   public:
     static External New(napi_env env, T* data);
 
-    // Finalizer must implement operator() accepting a T* and returning void.
+    // Finalizer must implement `void operator()(Env env, T* data)`.
     template <typename Finalizer>
     static External New(napi_env env,
                         T* data,
                         Finalizer finalizeCallback);
-    // Finalizer must implement operator() accepting a T* and Hint* and returning void.
+    // Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
     template <typename Finalizer, typename Hint>
     static External New(napi_env env,
                         T* data,
@@ -686,8 +745,7 @@ namespace Napi {
       size_t byteLength,         ///< Length of the external buffer to be used by the array,
                                  ///  in bytes
       Finalizer finalizeCallback ///< Function to be called when the array buffer is destroyed;
-                                 ///  must implement `operator()`, accept a `void*` (which is the
-                                 ///  data buffer pointer), and return `void`
+                                 ///  must implement `void operator()(Env env, void* externalData)`
     );
 
     /// Creates a new ArrayBuffer instance, using an external buffer with specified byte length.
@@ -698,8 +756,7 @@ namespace Napi {
       size_t byteLength,          ///< Length of the external buffer to be used by the array,
                                   ///  in bytes
       Finalizer finalizeCallback, ///< Function to be called when the array buffer is destroyed;
-                                  ///  must implement `operator()`, accept a `void*` (which is the
-                                  ///  data buffer pointer) and `Hint*`, and return `void`
+                                  ///  must implement `void operator()(Env env, void* externalData, Hint* hint)`
       Hint* finalizeHint          ///< Hint (second parameter) to be passed to the finalize callback
     );
 
@@ -969,12 +1026,12 @@ namespace Napi {
     static Buffer<T> New(napi_env env, size_t length);
     static Buffer<T> New(napi_env env, T* data, size_t length);
 
-    // Finalizer must implement operator() accepting a T* and returning void.
+    // Finalizer must implement `void operator()(Env env, T* data)`.
     template <typename Finalizer>
     static Buffer<T> New(napi_env env, T* data,
                          size_t length,
                          Finalizer finalizeCallback);
-    // Finalizer must implement operator() accepting a T* and Hint* and returning void.
+    // Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
     template <typename Finalizer, typename Hint>
     static Buffer<T> New(napi_env env, T* data,
                          size_t length,
@@ -1722,6 +1779,7 @@ namespace Napi {
 
     void Queue();
     void Cancel();
+    void SuppressDestruct();
 
     ObjectReference& Receiver();
     FunctionReference& Callback();
@@ -1743,9 +1801,18 @@ namespace Napi {
                          const char* resource_name,
                          const Object& resource);
 
+    explicit AsyncWorker(Napi::Env env);
+    explicit AsyncWorker(Napi::Env env,
+                         const char* resource_name);
+    explicit AsyncWorker(Napi::Env env,
+                         const char* resource_name,
+                         const Object& resource);
+
     virtual void Execute() = 0;
     virtual void OnOK();
     virtual void OnError(const Error& e);
+    virtual void Destroy();
+    virtual std::vector<napi_value> GetResult(Napi::Env env);
 
     void SetError(const std::string& error);
 
@@ -1760,7 +1827,210 @@ namespace Napi {
     ObjectReference _receiver;
     FunctionReference _callback;
     std::string _error;
+    bool _suppress_destruct;
+  };
+
+  #if (NAPI_VERSION > 3)
+  class ThreadSafeFunction {
+  public:
+    // This API may only be called from the main thread.
+    template <typename ResourceString>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename ContextType>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  ContextType* context);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename Finalizer>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  Finalizer finalizeCallback);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename Finalizer,
+              typename FinalizerDataType>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  Finalizer finalizeCallback,
+                                  FinalizerDataType* data);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename ContextType, typename Finalizer>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  ContextType* context,
+                                  Finalizer finalizeCallback);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename ContextType,
+              typename Finalizer, typename FinalizerDataType>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  ContextType* context,
+                                  Finalizer finalizeCallback,
+                                  FinalizerDataType* data);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  const Object& resource,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename ContextType>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  const Object& resource,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  ContextType* context);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename Finalizer>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  const Object& resource,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  Finalizer finalizeCallback);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename Finalizer,
+              typename FinalizerDataType>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  const Object& resource,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  Finalizer finalizeCallback,
+                                  FinalizerDataType* data);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename ContextType, typename Finalizer>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  const Object& resource,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  ContextType* context,
+                                  Finalizer finalizeCallback);
+
+    // This API may only be called from the main thread.
+    template <typename ResourceString, typename ContextType,
+              typename Finalizer, typename FinalizerDataType>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  const Object& resource,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  ContextType* context,
+                                  Finalizer finalizeCallback,
+                                  FinalizerDataType* data);
+
+    ThreadSafeFunction();
+    ThreadSafeFunction(napi_threadsafe_function tsFunctionValue);
+
+    ThreadSafeFunction(ThreadSafeFunction&& other);
+    ThreadSafeFunction& operator=(ThreadSafeFunction&& other);
+
+    // This API may be called from any thread.
+    napi_status BlockingCall() const;
+
+    // This API may be called from any thread.
+    template <typename Callback>
+    napi_status BlockingCall(Callback callback) const;
+
+    // This API may be called from any thread.
+    template <typename DataType, typename Callback>
+    napi_status BlockingCall(DataType* data, Callback callback) const;
+
+    // This API may be called from any thread.
+    napi_status NonBlockingCall() const;
+
+    // This API may be called from any thread.
+    template <typename Callback>
+    napi_status NonBlockingCall(Callback callback) const;
+
+    // This API may be called from any thread.
+    template <typename DataType, typename Callback>
+    napi_status NonBlockingCall(DataType* data, Callback callback) const;
+
+    // This API may be called from any thread.
+    napi_status Acquire() const;
+
+    // This API may be called from any thread.
+    napi_status Release();
+
+    // This API may be called from any thread.
+    napi_status Abort();
+
+    struct ConvertibleContext
+    {
+      template <class T>
+      operator T*() { return static_cast<T*>(context); }
+      void* context;
+    };
+
+    // This API may be called from any thread.
+    ConvertibleContext GetContext() const;
+
+  private:
+    using CallbackWrapper = std::function<void(Napi::Env, Napi::Function)>;
+
+    template <typename ResourceString, typename ContextType,
+              typename Finalizer, typename FinalizerDataType>
+    static ThreadSafeFunction New(napi_env env,
+                                  const Function& callback,
+                                  const Object& resource,
+                                  ResourceString resourceName,
+                                  size_t maxQueueSize,
+                                  size_t initialThreadCount,
+                                  ContextType* context,
+                                  Finalizer finalizeCallback,
+                                  FinalizerDataType* data,
+                                  napi_finalize wrapper);
+
+    napi_status CallInternal(CallbackWrapper* callbackWrapper,
+                        napi_threadsafe_function_call_mode mode) const;
+
+    static void CallJS(napi_env env,
+                       napi_value jsCallback,
+                       void* context,
+                       void* data);
+
+    std::unique_ptr<napi_threadsafe_function> _tsfn;
   };
+  #endif
 
   // Memory management.
   class MemoryManagement {

package/package.json

@@ -3,6 +3,8 @@
     "url": "https://github.com/nodejs/node-addon-api/issues"
   },
   "contributors": [
+    "Abhishek Kumar Singh (https://github.com/abhi11210646)",
+    "Alba Mendez (https://github.com/jmendeth)",
     "Andrew Petersen (https://github.com/kirbysayshi)",
     "Anisha Rohra (https://github.com/anisha-rohra)",
     "Anna Henningsen (https://github.com/addaleax)",
@@ -10,6 +12,8 @@
     "Arunesh Chandra (https://github.com/aruneshchandra)",
     "Ben Berman (https://github.com/rivertam)",
     "Benjamin Byholm (https://github.com/kkoopa)",
+    "Bill Gallafent (https://github.com/gallafent)",
+    "Bruce A. MacNaughton (https://github.com/bmacnaughton)",
     "Cory Mickelson (https://github.com/corymickelson)",
     "David Halls (https://github.com/davedoesdev)",
     "Dongjin Na (https://github.com/nadongguri)",
@@ -17,13 +21,16 @@
     "Gabriel Schulhof (https://github.com/gabrielschulhof)",
     "Gus Caplan (https://github.com/devsnek)",
     "Hitesh Kanwathirtha (https://github.com/digitalinfinity)",
+    "Jake Barnes (https://github.com/DuBistKomisch)",
     "Jake Yoon (https://github.com/yjaeseok)",
     "Jason Ginchereau (https://github.com/jasongin)",
     "Jim Schlight (https://github.com/jschlight)",
     "Jinho Bang (https://github.com/romandev)",
     "joshgarde (https://github.com/joshgarde)",
+    "Kevin Eady (https://github.com/KevinEady)",
     "Konstantin Tarkus (https://github.com/koistya)",
     "Kyle Farnung (https://github.com/kfarnung)",
+    "Luciano Martorella (https://github.com/lmartorella)",
     "Matteo Collina (https://github.com/mcollina)",
     "Michael Dawson (https://github.com/mhdawson)",
     "Michele Campus (https://github.com/kYroL01)",
@@ -32,9 +39,14 @@
     "Nick Soggin (https://github.com/iSkore)",
     "Philipp Renoth (https://github.com/DaAitch)",
     "Rolf Timmermans (https://github.com/rolftimmermans)",
+    "Ross Weir (https://github.com/ross-weir)",
+    "Ryuichi Okumura (https://github.com/okuryu)",
     "Sampson Gao (https://github.com/sampsongao)",
+    "Sam Roberts (https://github.com/sam-github)",
     "Taylor Woll (https://github.com/boingoing)",
-    "Thomas Gentilhomme (https://github.com/fraxken)"
+    "Thomas Gentilhomme (https://github.com/fraxken)",
+    "Tux3 (https://github.com/tux3)",
+    "Yohei Kishimoto (https://github.com/morokosi)"
   ],
   "dependencies": {},
   "description": "Node.js API (N-API)",
@@ -43,6 +55,7 @@
   },
   "directories": {},
   "homepage": "https://github.com/nodejs/node-addon-api",
+  "keywords": ["n-api", "napi", "addon", "native", "bindings", "c", "c++", "nan", "node-addon-api"],
   "license": "MIT",
   "main": "index.js",
   "name": "node-addon-api",
@@ -55,7 +68,11 @@
   "scripts": {
     "pretest": "node-gyp rebuild -C test",
     "test": "node test",
+    "predev": "node-gyp rebuild -C test --debug",
+    "dev": "node test",
+    "predev:incremental": "node-gyp configure build -C test --debug",
+    "dev:incremental": "node test",
     "doc": "doxygen doc/Doxyfile"
   },
-  "version": "1.6.1"
+  "version": "1.7.1"
 }

package/tools/README.md

@@ -25,7 +25,7 @@ Here is the list of things that can be fixed easily.
 
 
 ### Major Reconstructions
-The implementation of `Napi::ObjectWrap` is significantly different from NAN's. `Napi::ObjectWrap` takes a pointer to the wrapped object and creates a reference to the wrapped object inside ObjectWrap constructor. `Napi::ObjectWrap` also associated wrapped object's instance methods to Javascript module instead of static methods like NAN.
+The implementation of `Napi::ObjectWrap` is significantly different from NAN's. `Napi::ObjectWrap` takes a pointer to the wrapped object and creates a reference to the wrapped object inside ObjectWrap constructor. `Napi::ObjectWrap` also associates wrapped object's instance methods to Javascript module instead of static methods like NAN.
 
 So if you use Nan::ObjectWrap in your module, you will need to execute the following steps.
 
@@ -39,7 +39,7 @@ and define it as
   ...
 }
 ```
-This way, the `Napi::ObjectWrap` constructor will be invoked after the object has been instanciated and `Napi::ObjectWrap` can use the `this` pointer to create reference to the wrapped object.
+This way, the `Napi::ObjectWrap` constructor will be invoked after the object has been instantiated and `Napi::ObjectWrap` can use the `this` pointer to create a reference to the wrapped object.
 
   2. Move your original constructor code into the new constructor. Delete your original constructor.
   3. In your class initialization function, associate native methods in the following way. The `&` character before methods is required because they are not static methods but instance methods.