Add example showing multiple addon load

PR-URL: #69
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

Author: Gabriel Schulhof

multiple_load/napi/binding.gyp

@@ -0,0 +1,8 @@
+{
+  'targets': [
+    {
+      'target_name': 'multiple_load',
+      'sources': [ 'multiple_load.c' ]
+    }
+  ]
+}

multiple_load/napi/index.js

@@ -0,0 +1,40 @@
+// Example illustrating the case where a native addon is loaded multiple times.
+// This entire file is executed twice, concurrently - once on the main thread,
+// and once on a thread launched from the main thread.
+
+// We load the worker threads module, which allows us to launch multiple Node.js
+// environments, each in its own thread.
+const {
+  Worker, isMainThread
+} = require('worker_threads');
+
+// We load the native addon.
+const addon = require('bindings')('multiple_load');
+
+// The iteration count can be tweaked to ensure that the output from the two
+// threads is interleaved. Too few iterations and the output of one thread
+// follows the output of the other, not really illustrating the concurrency.
+const iterations = 1000;
+
+// This function is an idle loop that performs a random walk from 0 by calling
+// into the native addon to either increment or decrement the initial value.
+function useAddon(addon, prefix, iterations) {
+  if (iterations >= 0) {
+    if (Math.random() < 0.5) {
+      console.log(prefix + ': new value (decremented): ' + addon.decrement());
+    } else {
+      console.log(prefix + ': new value (incremented): ' + addon.increment());
+    }
+    setImmediate(() => useAddon(addon, prefix, --iterations));
+  }
+}
+
+if (isMainThread) {
+  // On the main thread, we launch a worker and wait for it to come online. Then
+  // we start the loop.
+  (new Worker(__filename)).on('online',
+      () => useAddon(addon, "Main thread", iterations));
+} else {
+  // On the secondary thread we immediately start the loop.
+  useAddon(addon, "Worker thread", iterations);
+}

multiple_load/napi/multiple_load.c

@@ -0,0 +1,136 @@
+#include <assert.h>
+#include <math.h>
+#include <stdlib.h>
+#include <node_api.h>
+
+// Structure containing information needed for as long as the addon exists. It
+// replaces the use of global static data with per-addon-instance data by
+// associating an instance of this structure with each instance of this addon
+// during addon initialization. The instance of this structure is then passed to
+// each binding the addon provides. Thus, the data stored in an instance of this
+// structure is available to each binding, just as global static data would be.
+typedef struct {
+  double value;
+} AddonData;
+
+// This is the actual, useful work performed: increment or decrement the value
+// stored per addon instance after passing it through a CPU-consuming but
+// otherwise useless calculation.
+static int ModifyAddonData(AddonData* data, double offset) {
+    // Expensively increment or decrement the value.
+    data->value = tan(atan(exp(log(sqrt(data->value * data->value))))) + offset;
+
+    // Round the value to the nearest integer.
+    data->value =
+        (double)(((int)data->value) +
+        (data->value - ((double)(int)data->value) > 0.5 ? 1 : 0));
+
+    // Return the value as an integer.
+    return (int)(data->value);
+}
+
+// This is boilerplate. The instance of the `AddonData` structure created during
+// addon initialization must be destroyed when the addon is unloaded. This
+// function will be called when the addon's `exports` object is garbage collected.
+static void DeleteAddonData(napi_env env, void* data, void* hint) {
+  // Avoid unused parameter warnings.
+  (void) env;
+  (void) hint;
+
+  // Free the per-addon-instance data.
+  free(data);
+}
+
+// This is also boilerplate. It creates and initializes an instance of the
+// `AddonData` structure and ties its lifecycle to that of the addon instance's
+// `exports` object. This means that the data will be available to this instance
+// of the addon for as long as the JavaScript engine keeps it alive.
+static AddonData* CreateAddonData(napi_env env, napi_value exports) {
+  AddonData* result = malloc(sizeof(*result));
+  result->value = 0.0;
+  assert(napi_wrap(env,
+                   exports,
+                   result,
+                   DeleteAddonData,
+                   NULL,
+                   NULL) == napi_ok);
+  return result;
+}
+
+// This function is called from JavaScript. It uses an expensive operation to
+// increment the value stored inside the `AddonData` structure by one.
+static napi_value Increment(napi_env env, napi_callback_info info) {
+  // Retrieve the per-addon-instance data.
+  AddonData* addon_data = NULL;
+  assert(napi_get_cb_info(env,
+                          info,
+                          NULL,
+                          NULL,
+                          NULL,
+                          ((void**)&addon_data)) == napi_ok);
+
+  // Increment the per-addon-instance value and create a new JavaScript integer
+  // from it.
+  napi_value result;
+  assert(napi_create_int32(env,
+                           ModifyAddonData(addon_data, 1.0),
+                           &result) == napi_ok);
+
+  // Return the JavaScript integer back to JavaScript.
+  return result;
+}
+
+// This function is called from JavaScript. It uses an expensive operation to
+// decrement the value stored inside the `AddonData` structure by one.
+static napi_value Decrement(napi_env env, napi_callback_info info) {
+  // Retrieve the per-addon-instance data.
+  AddonData* addon_data = NULL;
+  assert(napi_get_cb_info(env,
+                          info,
+                          NULL,
+                          NULL,
+                          NULL,
+                          ((void**)&addon_data)) == napi_ok);
+
+  // Decrement the per-addon-instance value and create a new JavaScript integer
+  // from it.
+  napi_value result;
+  assert(napi_create_int32(env,
+                           ModifyAddonData(addon_data, -1.0),
+                           &result) == napi_ok);
+
+  // Return the JavaScript integer back to JavaScript.
+  return result;
+}
+
+// Initialize the addon in such a way that it may be initialized multiple times
+// per process. The function body following this macro is provided the value
+// `env` which has type `napi_env` and the value `exports` which has type
+// `napi_value` and which refers to a JavaScript object that ultimately contains
+// the functions this addon wishes to expose. At the end, it must return a
+// `napi_value`. It may return `exports`, or it may create a new `napi_value`
+// and return that instead.
+NAPI_MODULE_INIT(/*env, exports*/) {
+  // Create a new instance of the per-instance-data that will be associated with
+  // the instance of the addon being initialized here and that will be destroyed
+  // along with the instance of the addon.
+  AddonData* addon_data = CreateAddonData(env, exports);
+
+  // Declare the bindings this addon provides. The data created above is given
+  // as the last initializer parameter, and will be given to the binding when it
+  // is called.
+  napi_property_descriptor bindings[] = {
+    {"increment", NULL, Increment, NULL, NULL, NULL, napi_enumerable, addon_data},
+    {"decrement", NULL, Decrement, NULL, NULL, NULL, napi_enumerable, addon_data}
+  };
+
+  // Expose the two bindings declared above to JavaScript.
+  assert(napi_define_properties(env,
+                                exports,
+                                sizeof(bindings) / sizeof(bindings[0]),
+                                bindings) == napi_ok);
+
+  // Return the `exports` object provided. It now has two new properties, which
+  // are the functions we wish to expose to JavaScript.
+  return exports;
+}

multiple_load/napi/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "multiple_load",
+  "version": "0.0.0",
+  "description": "Multiple load example",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "test": "node --experimental-worker index.js"
+  },
+  "engines": {
+    "node": ">= 10.10.0"
+  },
+  "gypfile": true,
+  "dependencies": {
+    "bindings": "~1.2.1"
+  }
+}

multiple_load/node_10/binding.gyp

@@ -0,0 +1,8 @@
+{
+  'targets': [
+    {
+      'target_name': 'multiple_load',
+      'sources': [ 'multiple_load.cc' ]
+    }
+  ]
+}

multiple_load/node_10/index.js

@@ -0,0 +1,40 @@
+// Example illustrating the case where a native addon is loaded multiple times.
+// This entire file is executed twice, concurrently - once on the main thread,
+// and once on a thread launched from the main thread.
+
+// We load the worker threads module, which allows us to launch multiple Node.js
+// environments, each in its own thread.
+const {
+  Worker, isMainThread
+} = require('worker_threads');
+
+// We load the native addon.
+const addon = require('bindings')('multiple_load');
+
+// The iteration count can be tweaked to ensure that the output from the two
+// threads is interleaved. Too few iterations and the output of one thread
+// follows the output of the other, not really illustrating the concurrency.
+const iterations = 1000;
+
+// This function is an idle loop that performs a random walk from 0 by calling
+// into the native addon to either increment or decrement the initial value.
+function useAddon(addon, prefix, iterations) {
+  if (iterations >= 0) {
+    if (Math.random() < 0.5) {
+      console.log(prefix + ': new value (decremented): ' + addon.decrement());
+    } else {
+      console.log(prefix + ': new value (incremented): ' + addon.increment());
+    }
+    setImmediate(() => useAddon(addon, prefix, --iterations));
+  }
+}
+
+if (isMainThread) {
+  // On the main thread, we launch a worker and wait for it to come online. Then
+  // we start the loop.
+  (new Worker(__filename)).on('online',
+      () => useAddon(addon, "Main thread", iterations));
+} else {
+  // On the secondary thread we immediately start the loop.
+  useAddon(addon, "Worker thread", iterations);
+}

multiple_load/node_10/multiple_load.cc

@@ -0,0 +1,117 @@
+#include <node.h>
+#include <math.h>
+
+using namespace v8;
+
+// Class containing information needed for as long as the addon exists. It
+// replaces the use of global static data with per-addon-instance data by
+// associating an instance of this class with each instance of this addon during
+// addon initialization. The instance of this class is then passed to each
+// binding the addon provides. Thus, the data stored in an instance of this
+// class is available to each binding, just as global static data would be.
+class AddonData {
+ public:
+  // This is the actual, useful work performed: increment or decrement the value
+  // stored per addon instance after passing it through a CPU-consuming but
+  // otherwise useless calculation. Round the result to the nearest integer.
+  int GetNewValue(double offset) {
+    // Expensively increment or decrement the value.
+    value = tan(atan(exp(log(sqrt(value * value))))) + offset;
+
+    // Round the value to the nearest integer.
+    value =
+        (double)(((int)value) + (value - ((double)(int)value) > 0.5 ? 1 : 0));
+
+    // Return the value as an integer.
+    return (int)value;
+  }
+
+  // This is boilerplate. It creates a new instance of this class and wraps it
+  // into a v8::External. The isolate and the exports are necessary, because we
+  // want the instance of this class to be destroyed along with the exports
+  // object when the addon is eventually unloaded.
+  static Local<Value> New(Isolate* isolate, Local<Object> exports) {
+    return External::New(isolate, new AddonData(isolate, exports));
+  }
+
+ private:
+  // This is the actual, useful payload carried by an instance of this class.
+  // A double value is kept around for as long as an instance of this addon is
+  // loaded, and is incremented or decremented whenever the addon receives a
+  // call from JavaScript.
+  double value;
+
+  explicit AddonData(Isolate* isolate, Local<Object> exports):
+      // The payload is initialized here. The rest of the constructor is
+      // boilerplate that ensures that the instance of this addon data is
+      // destroyed along with the instance of this addon (`exports`).
+      value(0.0) {
+    exports_persistent.Reset(isolate, exports);
+    exports_persistent.SetWeak(this, DeleteMe, WeakCallbackType::kParameter);
+  }
+
+  // The rest of the class definition is boilerplate.
+
+  // The persistent reference must be reset before the instance of this class is
+  // destroyed, otherwise memory will leak on the V8 side.
+  ~AddonData() {
+    exports_persistent.Reset();
+  }
+
+  // This static function will be called when the addon instance is unloaded. It
+  // merely destroys the per-addon-instance data.
+  static void DeleteMe(const WeakCallbackInfo<AddonData>& info) {
+    delete info.GetParameter();
+  }
+
+  Persistent<Object> exports_persistent;
+};
+
+// Function called from JavaScript to increment the value stored in this addon.
+void Increment(const FunctionCallbackInfo<Value>& info) {
+  // Retrieve the per-addon-instance data.
+  AddonData* addon_data =
+      static_cast<AddonData*>(info.Data().As<External>()->Value());
+
+  info.GetReturnValue()
+      .Set(Number::New(info.GetIsolate(), addon_data->GetNewValue(1.0)));
+}
+
+// Function called from JavaScript to decrement the value stored in this addon.
+void Decrement(const FunctionCallbackInfo<Value>& info) {
+  // Retrieve the per-addon-instance data.
+  AddonData* addon_data =
+      static_cast<AddonData*>(info.Data().As<External>()->Value());
+
+  info.GetReturnValue()
+      .Set(Number::New(info.GetIsolate(), addon_data->GetNewValue(-1.0)));
+}
+
+// Initialize the addon in such a way that it may be initialized multiple times
+// per process. The function body following this macro is provided the value
+// `exports` of type `Local<Object>`, the value `module` of type
+// `Local<Object>`, and `context` of type `Local<Context>`. It may either define
+// new properties on the `exports` object, or define the property named
+// "exports" on the `module` object.
+NODE_MODULE_INIT(/*exports, module, context*/) {
+  Isolate* isolate = context->GetIsolate();
+
+  // Create a new instance of the addon data that will be associated with this
+  // instance of the addon, and that will be freed along with this instance of
+  // the addon.
+  Local<Value> addon_data = AddonData::New(isolate, exports);
+
+  // Export the functions we wish to make available to JavaScript.
+
+  exports->Set(context,
+      String::NewFromUtf8(isolate, "increment", NewStringType::kNormal)
+          .ToLocalChecked(),
+      FunctionTemplate::New(isolate, Increment, addon_data)
+          ->GetFunction(context).ToLocalChecked()).FromJust();
+
+  exports->Set(context,
+      String::NewFromUtf8(isolate, "decrement", NewStringType::kNormal)
+          .ToLocalChecked(),
+      FunctionTemplate::New(isolate, Decrement, addon_data)
+          ->GetFunction(context).ToLocalChecked()).FromJust();
+}

multiple_load/node_10/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "multiple_load",
+  "version": "0.0.0",
+  "description": "Multiple load example",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "test": "node --experimental-worker index.js"
+  },
+  "engines": {
+    "node": ">= 10.10.0"
+  },
+  "gypfile": true,
+  "dependencies": {
+    "bindings": "~1.2.1"
+  }
+}