node-addon-api 3.0.2 → 3.1.0

package/napi.h

@@ -822,6 +822,11 @@ namespace Napi {
 
     void* Data();        ///< Gets a pointer to the data buffer.
     size_t ByteLength(); ///< Gets the length of the array buffer in bytes.
+
+#if NAPI_VERSION >= 7
+    bool IsDetached() const;
+    void Detach();
+#endif  // NAPI_VERSION >= 7
   };
 
   /// A JavaScript typed-array value with unknown array type.
@@ -2244,6 +2249,196 @@ namespace Napi {
     napi_threadsafe_function _tsfn;
   };
 
+  // A TypedThreadSafeFunction by default has no context (nullptr) and can
+  // accept any type (void) to its CallJs.
+  template <typename ContextType = std::nullptr_t,
+            typename DataType = void,
+            void (*CallJs)(Napi::Env, Napi::Function, ContextType*, DataType*) =
+                nullptr>
+  class TypedThreadSafeFunction {
+   public:
+    // This API may only be called from the main thread.
+    // Helper function that returns nullptr if running N-API 5+, otherwise a
+    // non-empty, no-op Function. This provides the ability to specify at
+    // compile-time a callback parameter to `New` that safely does no action
+    // when targeting _any_ N-API version.
+#if NAPI_VERSION > 4
+    static std::nullptr_t EmptyFunctionFactory(Napi::Env env);
+#else
+    static Napi::Function EmptyFunctionFactory(Napi::Env env);
+#endif
+    static Napi::Function FunctionOrEmpty(Napi::Env env,
+                                          Napi::Function& callback);
+
+#if NAPI_VERSION > 4
+    // This API may only be called from the main thread.
+    // Creates a new threadsafe function with:
+    //   Callback [missing] Resource [missing] Finalizer [missing]
+    template <typename ResourceString>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+        napi_env env,
+        ResourceString resourceName,
+        size_t maxQueueSize,
+        size_t initialThreadCount,
+        ContextType* context = nullptr);
+
+    // This API may only be called from the main thread.
+    // Creates a new threadsafe function with:
+    //   Callback [missing] Resource [passed] Finalizer [missing]
+    template <typename ResourceString>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+        napi_env env,
+        const Object& resource,
+        ResourceString resourceName,
+        size_t maxQueueSize,
+        size_t initialThreadCount,
+        ContextType* context = nullptr);
+
+    // This API may only be called from the main thread.
+    // Creates a new threadsafe function with:
+    //   Callback [missing] Resource [missing] Finalizer [passed]
+    template <typename ResourceString,
+              typename Finalizer,
+              typename FinalizerDataType = void>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+        napi_env env,
+        ResourceString resourceName,
+        size_t maxQueueSize,
+        size_t initialThreadCount,
+        ContextType* context,
+        Finalizer finalizeCallback,
+        FinalizerDataType* data = nullptr);
+
+    // This API may only be called from the main thread.
+    // Creates a new threadsafe function with:
+    //   Callback [missing] Resource [passed] Finalizer [passed]
+    template <typename ResourceString,
+              typename Finalizer,
+              typename FinalizerDataType = void>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+        napi_env env,
+        const Object& resource,
+        ResourceString resourceName,
+        size_t maxQueueSize,
+        size_t initialThreadCount,
+        ContextType* context,
+        Finalizer finalizeCallback,
+        FinalizerDataType* data = nullptr);
+#endif
+
+    // This API may only be called from the main thread.
+    // Creates a new threadsafe function with:
+    //   Callback [passed] Resource [missing] Finalizer [missing]
+    template <typename ResourceString>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+        napi_env env,
+        const Function& callback,
+        ResourceString resourceName,
+        size_t maxQueueSize,
+        size_t initialThreadCount,
+        ContextType* context = nullptr);
+
+    // This API may only be called from the main thread.
+    // Creates a new threadsafe function with:
+    //   Callback [passed] Resource [passed] Finalizer [missing]
+    template <typename ResourceString>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+        napi_env env,
+        const Function& callback,
+        const Object& resource,
+        ResourceString resourceName,
+        size_t maxQueueSize,
+        size_t initialThreadCount,
+        ContextType* context = nullptr);
+
+    // This API may only be called from the main thread.
+    // Creates a new threadsafe function with:
+    //   Callback [passed] Resource [missing] Finalizer [passed]
+    template <typename ResourceString,
+              typename Finalizer,
+              typename FinalizerDataType = void>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+        napi_env env,
+        const Function& callback,
+        ResourceString resourceName,
+        size_t maxQueueSize,
+        size_t initialThreadCount,
+        ContextType* context,
+        Finalizer finalizeCallback,
+        FinalizerDataType* data = nullptr);
+
+    // This API may only be called from the main thread.
+    // Creates a new threadsafe function with:
+    //   Callback [passed] Resource [passed] Finalizer [passed]
+    template <typename CallbackType,
+              typename ResourceString,
+              typename Finalizer,
+              typename FinalizerDataType>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+        napi_env env,
+        CallbackType callback,
+        const Object& resource,
+        ResourceString resourceName,
+        size_t maxQueueSize,
+        size_t initialThreadCount,
+        ContextType* context,
+        Finalizer finalizeCallback,
+        FinalizerDataType* data = nullptr);
+
+    TypedThreadSafeFunction<ContextType, DataType, CallJs>();
+    TypedThreadSafeFunction<ContextType, DataType, CallJs>(
+        napi_threadsafe_function tsFunctionValue);
+
+    operator napi_threadsafe_function() const;
+
+    // This API may be called from any thread.
+    napi_status BlockingCall(DataType* data = nullptr) const;
+
+    // This API may be called from any thread.
+    napi_status NonBlockingCall(DataType* data = nullptr) const;
+
+    // This API may only be called from the main thread.
+    void Ref(napi_env env) const;
+
+    // This API may only be called from the main thread.
+    void Unref(napi_env env) 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();
+
+    // This API may be called from any thread.
+    ContextType* GetContext() const;
+
+   private:
+    template <typename ResourceString,
+              typename Finalizer,
+              typename FinalizerDataType>
+    static TypedThreadSafeFunction<ContextType, DataType, CallJs> 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);
+
+    static void CallJsInternal(napi_env env,
+                               napi_value jsCallback,
+                               void* context,
+                               void* data);
+
+   protected:
+    napi_threadsafe_function _tsfn;
+  };
   template <typename DataType>
   class AsyncProgressWorkerBase : public AsyncWorker {
     public:

package/package-support.json

@@ -0,0 +1,21 @@
+{
+  "versions": [
+    {
+      "version": "*",
+      "target": {
+        "node": "active"
+      },
+      "response": {
+        "type": "time-permitting",
+        "paid": false,
+        "contact": {
+          "name": "node-addon-api team",
+          "url": "https://github.com/nodejs/node-addon-api/issues"
+        }
+      },
+      "backing": [ { "project": "https://github.com/nodejs" },
+                   { "foundation": "https://openjsf.org/" }
+      ]
+    }
+  ]
+}

package/package.json

@@ -51,6 +51,10 @@
       "name": "Bill Gallafent",
       "url": "https://github.com/gallafent"
     },
+    {
+      "name": "blagoev",
+      "url": "https://github.com/blagoev"
+    },
     {
       "name": "Bruce A. MacNaughton",
       "url": "https://github.com/bmacnaughton"
@@ -63,6 +67,10 @@
       "name": "Daniel Bevenius",
       "url": "https://github.com/danbev"
     },
+    {
+      "name": "Darshan Sen",
+      "url": "https://github.com/RaisinTen"
+    },
     {
       "name": "David Halls",
       "url": "https://github.com/davedoesdev"
@@ -75,6 +83,10 @@
       "name": "Dongjin Na",
       "url": "https://github.com/nadongguri"
     },
+    {
+      "name": "Ferdinand Holzer",
+      "url": "https://github.com/fholzer"
+    },
     {
       "name": "Eric Bickle",
       "url": "https://github.com/ebickle"
@@ -91,6 +103,10 @@
       "name": "Gus Caplan",
       "url": "https://github.com/devsnek"
     },
+    {
+      "name": "Helio Frota",
+      "url": "https://github.com/helio-frota"
+    },
     {
       "name": "Hitesh Kanwathirtha",
       "url": "https://github.com/digitalinfinity"
@@ -139,6 +155,10 @@
       "name": "Kevin Eady",
       "url": "https://github.com/KevinEady"
     },
+    {
+      "name": "kidneysolo",
+      "url": "https://github.com/kidneysolo"
+    },
     {
       "name": "Koki Nishihara",
       "url": "https://github.com/Nishikoh"
@@ -163,6 +183,10 @@
       "name": "Luciano Martorella",
       "url": "https://github.com/lmartorella"
     },
+    {
+      "name": "mastergberry",
+      "url": "https://github.com/mastergberry"
+    },
     {
       "name": "Mathias Küsel",
       "url": "https://github.com/mathiask88"
@@ -187,6 +211,10 @@
       "name": "Mikhail Cheshkov",
       "url": "https://github.com/mcheshkov"
     },
+    {
+      "name": "nempoBu4",
+      "url": "https://github.com/nempoBu4"
+    },
     {
       "name": "Nicola Del Gobbo",
       "url": "https://github.com/NickNaso"
@@ -195,6 +223,10 @@
       "name": "Nick Soggin",
       "url": "https://github.com/iSkore"
     },
+    {
+      "name": "Nikolai Vavilov",
+      "url": "https://github.com/seishun"
+    },
     {
       "name": "Nurbol Alpysbayev",
       "url": "https://github.com/anurbol"
@@ -258,14 +290,20 @@
     {
       "name": "Yulong Wang",
       "url": "https://github.com/fs-eire"
+    },
+    {
+      "name": "Ziqiu Zhao",
+      "url": "https://github.com/ZzqiZQute"
     }
   ],
   "dependencies": {},
   "description": "Node.js API (N-API)",
   "devDependencies": {
     "benchmark": "^2.1.4",
-    "fs-extra": "^9.0.1",
     "bindings": "^1.5.0",
+    "clang-format": "^1.4.0",
+    "fs-extra": "^9.0.1",
+    "pre-commit": "^1.2.2",
     "safe-buffer": "^5.1.1"
   },
   "directories": {},
@@ -300,7 +338,11 @@
     "dev": "node test",
     "predev:incremental": "node-gyp configure build -C test --debug",
     "dev:incremental": "node test",
-    "doc": "doxygen doc/Doxyfile"
+    "doc": "doxygen doc/Doxyfile",
+    "lint": "node tools/clang-format.js",
+    "lint:fix": "git-clang-format '*.h', '*.cc'"
   },
-  "version": "3.0.2"
+  "pre-commit": "lint",
+  "version": "3.1.0",
+  "support": true
 }

package/tools/README.md

@@ -1,4 +1,10 @@
-# Migration Script
+# Tools
+
+## clang-format
+
+The clang-format checking tools is designed to check changed lines of code compared to given git-refs.
+
+## Migration Script
 
 The migration tool is designed to reduce repetitive work in the migration process. However, the script is not aiming to convert every thing for you. There are usually some small fixes and major reconstruction required.
 
@@ -42,7 +48,7 @@ and define it as
 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.
+  3. In your class initialization function, associate native methods in the following way.
 ```
 Napi::FunctionReference constructor;
 

package/tools/clang-format.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+const spawn = require('child_process').spawnSync;
+const path = require('path');
+
+const filesToCheck = ['*.h', '*.cc'];
+const CLANG_FORMAT_START = process.env.CLANG_FORMAT_START || 'master';
+
+function main(args) {
+  let clangFormatPath = path.dirname(require.resolve('clang-format'));
+  const options = ['--binary=node_modules/.bin/clang-format', '--style=file'];
+
+  const gitClangFormatPath = path.join(clangFormatPath,
+    'bin/git-clang-format');
+  const result = spawn('python', [
+    gitClangFormatPath,
+    ...options,
+    '--diff',
+    CLANG_FORMAT_START,
+    'HEAD',
+    ...filesToCheck
+  ], { encoding: 'utf-8' });
+
+  if (result.error) {
+    console.error('Error running git-clang-format:', result.error);
+    return 2;
+  }
+
+  const clangFormatOutput = result.stdout.trim();
+  if (clangFormatOutput !== '' &&
+      clangFormatOutput !== ('no modified files to format') &&
+      clangFormatOutput !== ('clang-format did not modify any files')) {
+    console.error(clangFormatOutput);
+    const fixCmd = '"npm run lint:fix"';
+    console.error(`
+      ERROR: please run ${fixCmd} to format changes in your commit
+        Note that when running the command locally, please keep your local
+        master branch and working branch up to date with nodejs/node-addon-api
+        to exclude un-related complains.
+        Or you can run "env CLANG_FORMAT_START=upstream/master ${fixCmd}".`);
+    return 1;
+  }
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}