test: add barebones new tsfn test for use in docs

Author: KevinEady

test/binding.cc

@@ -50,6 +50,7 @@ Object InitThreadSafeFunctionUnref(Env env);
 Object InitThreadSafeFunction(Env env);
 Object InitThreadSafeFunctionExCall(Env env);
 Object InitThreadSafeFunctionExContext(Env env);
+Object InitThreadSafeFunctionExExample(Env env);
 Object InitThreadSafeFunctionExSimple(Env env);
 Object InitThreadSafeFunctionExThreadSafe(Env env);
 #endif
@@ -111,6 +112,7 @@ Object Init(Env env, Object exports) {
   exports.Set("threadsafe_function", InitThreadSafeFunction(env));
   exports.Set("threadsafe_function_ex_call", InitThreadSafeFunctionExCall(env));
   exports.Set("threadsafe_function_ex_context", InitThreadSafeFunctionExContext(env));
+  exports.Set("threadsafe_function_ex_example", InitThreadSafeFunctionExExample(env));
   exports.Set("threadsafe_function_ex_simple", InitThreadSafeFunctionExSimple(env));
   exports.Set("threadsafe_function_ex_threadsafe", InitThreadSafeFunctionExThreadSafe(env));
 #endif

test/binding.gyp

@@ -37,6 +37,7 @@
         'run_script.cc',
         'threadsafe_function_ex/call.cc',
         'threadsafe_function_ex/context.cc',
+        'threadsafe_function_ex/example.cc',
         'threadsafe_function_ex/simple.cc',
         'threadsafe_function_ex/threadsafe.cc',
         'threadsafe_function/threadsafe_function_ctx.cc',

test/index.js

@@ -44,6 +44,7 @@ let testModules = [
   'run_script',
   'threadsafe_function_ex/call',
   'threadsafe_function_ex/context',
+  'threadsafe_function_ex/example',
   'threadsafe_function_ex/simple',
   'threadsafe_function_ex/threadsafe',
   'threadsafe_function/threadsafe_function_ctx',
@@ -80,6 +81,7 @@ if (napiVersion < 4) {
   testModules.splice(testModules.indexOf('threadsafe_function/threadsafe_function'), 1);
   testModules.splice(testModules.indexOf('threadsafe_function_ex/call'), 1);
   testModules.splice(testModules.indexOf('threadsafe_function_ex/context'), 1);
+  testModules.splice(testModules.indexOf('threadsafe_function_ex/example'), 1);
   testModules.splice(testModules.indexOf('threadsafe_function_ex/simple'), 1);
   testModules.splice(testModules.indexOf('threadsafe_function_ex/threadsafe'), 1);
 }

test/threadsafe_function_ex/example.cc

@@ -0,0 +1,103 @@
+/**
+ * This test is programmatically represents the example shown in
+ * `doc/threadsafe_function_ex.md`
+ */
+
+#include "napi.h"
+
+#if (NAPI_VERSION > 3)
+
+using namespace Napi;
+
+namespace {
+
+// Context of our TSFN.
+struct Context {};
+
+// Data passed (as pointer) to ThreadSafeFunctionEx::[Non]BlockingCall
+using DataType = int;
+
+// Callback function
+static void Callback(Napi::Env env, Napi::Function jsCallback, Context *context,
+                     DataType *data) {
+  // Check that the threadsafe function has not been finalized. Node calls this
+  // callback for items remaining on the queue once finalization has completed.
+  if (!(env == nullptr || jsCallback == nullptr)) {
+  }
+  if (data != nullptr) {
+    delete data;
+  }
+}
+
+// Full type of our ThreadSafeFunctionEx
+using TSFN = ThreadSafeFunctionEx<Context, DataType, Callback>;
+
+// A JS-accessible wrap that holds a TSFN.
+class TSFNWrap : public ObjectWrap<TSFNWrap> {
+
+public:
+  static Object Init(Napi::Env env, Object exports);
+  TSFNWrap(const CallbackInfo &info);
+
+private:
+  Napi::Value Start(const CallbackInfo &info);
+  Napi::Value Release(const CallbackInfo &info);
+};
+
+/**
+ * @brief Initialize `TSFNWrap` on the environment.
+ *
+ * @param env
+ * @param exports
+ * @return Object
+ */
+Object TSFNWrap::Init(Napi::Env env, Object exports) {
+  Function func = DefineClass(env, "TSFNWrap",
+                              {InstanceMethod("start", &TSFNWrap::Start),
+                               InstanceMethod("release", &TSFNWrap::Release)});
+
+  exports.Set("TSFNWrap", func);
+  return exports;
+}
+
+/**
+ * @brief Construct a new TSFNWrap::TSFNWrap object
+ *
+ * @param info
+ */
+TSFNWrap::TSFNWrap(const CallbackInfo &info) : ObjectWrap<TSFNWrap>(info) {}
+} // namespace
+
+/**
+ * @brief Instance method `TSFNWrap#start`
+ *
+ * @param info
+ * @return undefined
+ */
+Napi::Value TSFNWrap::Start(const CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  return env.Undefined();
+};
+
+/**
+ * @brief Instance method `TSFNWrap#release`
+ *
+ * @param info
+ * @return undefined
+ */
+Napi::Value TSFNWrap::Release(const CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  return env.Undefined();
+};
+
+/**
+ * @brief Module initialization function
+ *
+ * @param env
+ * @return Object
+ */
+Object InitThreadSafeFunctionExExample(Env env) {
+  return TSFNWrap::Init(env, Object::New(env));
+}
+
+#endif

test/threadsafe_function_ex/example.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * This test is programmatically represents the example shown in
+ * `doc/threadsafe_function_ex.md`
+ */
+
+const assert = require('assert');
+const buildType = process.config.target_defaults.default_configuration;
+
+module.exports = Promise.all([
+  test(require(`../build/${buildType}/binding.node`)),
+  test(require(`../build/${buildType}/binding_noexcept.node`))
+]);
+
+async function test(binding) {
+  const tsfn = new binding.threadsafe_function_ex_example.TSFNWrap();
+  await tsfn.start();
+  await tsfn.release();
+}