Node.js v25.0.0 ドキュメンテーション

コンテキストアウェアなアドオン#

Node.js アドオンが複数のコンテキストで複数回ロードされる必要がある環境があります。たとえば、Electron ランタイムは、単一のプロセスで Node.js の複数のインスタンスを実行します。各インスタンスには独自の require() キャッシュがあるため、各インスタンスは require() を介してロードされたときにネイティブアドオンが正しく動作する必要があります。これは、アドオンが複数の初期化をサポートする必要があることを意味します。

コンテキストアウェアなアドオンは、マクロ NODE_MODULE_INITIALIZER を使用して構築できます。これは、Node.js がアドオンをロードするときに見つけることを期待する関数の名前に展開されます。したがって、アドオンは次の例のように初期化できます

using namespace v8;

extern "C" NODE_MODULE_EXPORT void
NODE_MODULE_INITIALIZER(Local<Object> exports,
                        Local<Value> module,
                        Local<Context> context) {
  /* Perform addon initialization steps here. */
} copy

もう一つの選択肢は、マクロ NODE_MODULE_INIT() を使用することです。これもコンテキストアウェアなアドオンを構築します。特定のアドオン初期化関数の周りにアドオンを構築するために使用される NODE_MODULE() とは異なり、NODE_MODULE_INIT() は、そのような初期化子の宣言として機能し、その後に続く関数本体が続きます。

NODE_MODULE_INIT() の呼び出しに続く関数本体内では、次の3つの変数を使用できます

• Local<Object> exports,
• Local<Value> module、および
• Local<Context> context

コンテキストアウェアなアドオンを構築するには、安定性と正確性を確保するためにグローバル静的データを慎重に管理する必要があります。アドオンは複数回、場合によっては異なるスレッドからロードされる可能性があるため、アドオンに格納されているグローバル静的データは適切に保護され、JavaScript オブジェクトへの永続的な参照を含んではいけません。その理由は、JavaScript オブジェクトは1つのコンテキストでのみ有効であり、間違ったコンテキストや作成されたスレッドとは異なるスレッドからアクセスされると、クラッシュを引き起こす可能性が高いためです。

コンテキストアウェアなアドオンは、次の手順を実行することで、グローバルな静的データを回避するように構造化できます

• アドオンインスタンスごとのデータを保持するクラスを定義し、そのクラスに次の形式の静的メンバーを持たせます

  static void DeleteInstance(void* data) {
    // Cast `data` to an instance of the class and delete it.
  } copy

• アドオン初期化子でこのクラスのインスタンスをヒープに割り当てます。これは new キーワードを使用して実現できます。
• node::AddEnvironmentCleanupHook() を呼び出し、上記で作成したインスタンスと DeleteInstance() へのポインタを渡します。これにより、環境が破棄されるときにインスタンスが削除されることが保証されます。
• クラスのインスタンスを v8::External に格納し、
• ネイティブバックの JavaScript 関数を作成する v8::FunctionTemplate::New() または v8::Function::New() に v8::External を渡すことで、JavaScript に公開されるすべてのメソッドにその v8::External を渡します。v8::FunctionTemplate::New() または v8::Function::New() の3番目のパラメータは v8::External を受け入れ、v8::FunctionCallbackInfo::Data() メソッドを使用してネイティブコールバックで利用可能にします。

これにより、アドオンインスタンスごとのデータが、JavaScript から呼び出せる各バインディングに確実に届きます。アドオンインスタンスごとのデータは、アドオンが作成する可能性のある非同期コールバックにも渡す必要があります。

次の例は、コンテキストアウェアなアドオンの実装を示しています

#include <node.h>

using namespace v8;

class AddonData {
 public:
  explicit AddonData(Isolate* isolate):
      call_count(0) {
    // Ensure this per-addon-instance data is deleted at environment cleanup.
    node::AddEnvironmentCleanupHook(isolate, DeleteInstance, this);
  }

  // Per-addon data.
  int call_count;

  static void DeleteInstance(void* data) {
    delete static_cast<AddonData*>(data);
  }
};

static void Method(const v8::FunctionCallbackInfo<v8::Value>& info) {
  // Retrieve the per-addon-instance data.
  AddonData* data =
      reinterpret_cast<AddonData*>(info.Data().As<External>()->Value());
  data->call_count++;
  info.GetReturnValue().Set((double)data->call_count);
}

// Initialize this addon to be context-aware.
NODE_MODULE_INIT(/* exports, module, context */) {
  Isolate* isolate = Isolate::GetCurrent();

  // Create a new instance of `AddonData` for this instance of the addon and
  // tie its life cycle to that of the Node.js environment.
  AddonData* data = new AddonData(isolate);

  // Wrap the data in a `v8::External` so we can pass it to the method we
  // expose.
  Local<External> external = External::New(isolate, data);

  // Expose the method `Method` to JavaScript, and make sure it receives the
  // per-addon-instance data we created above by passing `external` as the
  // third parameter to the `FunctionTemplate` constructor.
  exports->Set(context,
               String::NewFromUtf8(isolate, "method").ToLocalChecked(),
               FunctionTemplate::New(isolate, Method, external)
                  ->GetFunction(context).ToLocalChecked()).FromJust();
} copy

void AddEnvironmentCleanupHook(v8::Isolate* isolate,
                               void (*fun)(void* arg),
                               void* arg); copy

// addon.cc
#include <node.h>
#include <assert.h>
#include <stdlib.h>

using node::AddEnvironmentCleanupHook;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Object;

// Note: In a real-world application, do not rely on static/global data.
static char cookie[] = "yum yum";
static int cleanup_cb1_called = 0;
static int cleanup_cb2_called = 0;

static void cleanup_cb1(void* arg) {
  Isolate* isolate = static_cast<Isolate*>(arg);
  HandleScope scope(isolate);
  Local<Object> obj = Object::New(isolate);
  assert(!obj.IsEmpty());  // assert VM is still alive
  assert(obj->IsObject());
  cleanup_cb1_called++;
}

static void cleanup_cb2(void* arg) {
  assert(arg == static_cast<void*>(cookie));
  cleanup_cb2_called++;
}

static void sanity_check(void*) {
  assert(cleanup_cb1_called == 1);
  assert(cleanup_cb2_called == 1);
}

// Initialize this addon to be context-aware.
NODE_MODULE_INIT(/* exports, module, context */) {
  Isolate* isolate = Isolate::GetCurrent();

  AddEnvironmentCleanupHook(isolate, sanity_check, nullptr);
  AddEnvironmentCleanupHook(isolate, cleanup_cb2, cookie);
  AddEnvironmentCleanupHook(isolate, cleanup_cb1, isolate);
} copy

// test.js
require('./build/Release/addon'); copy

ビルド#

ソースコードが書かれたら、それをバイナリの addon.node ファイルにコンパイルする必要があります。そのためには、プロジェクトのトップレベルに binding.gyp というファイルを作成し、JSON ライクな形式でモジュールのビルド構成を記述します。このファイルは、Node.js アドオンをコンパイルするために特別に書かれたツールである node-gyp によって使用されます。

{
  "targets": [
    {
      "target_name": "addon",
      "sources": [ "hello.cc" ]
    }
  ]
} copy

node-gyp ユーティリティのバージョンは、npm の一部として Node.js にバンドルされて配布されています。このバージョンは開発者が直接使用するために提供されているものではなく、npm install コマンドを使用してアドオンをコンパイルおよびインストールする機能をサポートすることのみを目的としています。node-gyp を直接使用したい開発者は、npm install -g node-gyp コマンドを使用してインストールできます。プラットフォーム固有の要件など、詳細については node-gyp の インストール手順を参照してください。

binding.gyp ファイルが作成されたら、node-gyp configure を使用して現在のプラットフォームに適したプロジェクトビルドファイルを生成します。これにより、build/ ディレクトリに Makefile (Unix プラットフォーム) または vcxproj ファイル (Windows) が生成されます。

次に、node-gyp build コマンドを呼び出して、コンパイル済みの addon.node ファイルを生成します。これは build/Release/ ディレクトリに置かれます。

npm install を使用して Node.js アドオンをインストールする場合、npm はバンドルされているバージョンの node-gyp を使用してこれと同じ一連のアクションを実行し、ユーザーのプラットフォーム用にコンパイルされたバージョンのアドオンをオンデマンドで生成します。

ビルドされると、バイナリアドオンは Node.js 内から require() にビルドされた addon.node モジュールを指し示すことで使用できます

// hello.js
const addon = require('./build/Release/addon');

console.log(addon.hello());
// Prints: 'world' copy

コンパイルされたアドオンバイナリへの正確なパスは、コンパイル方法によって異なる可能性があるため (例: ./build/Debug/ にある場合がある)、アドオンは bindings パッケージを使用してコンパイルされたモジュールをロードできます。

bindings パッケージの実装はアドオンモジュールの検索方法においてより洗練されていますが、本質的には次のような try…catch パターンを使用しています

try {
  return require('./build/Release/addon.node');
} catch (err) {
  return require('./build/Debug/addon.node');
} copy

Node.js に含まれるライブラリへのリンク#

Node.js は、V8、libuv、OpenSSL などの静的リンクライブラリを使用します。すべてのアドオンは V8 にリンクする必要があり、他の依存関係のいずれにもリンクできます。通常、これは適切な #include <...> ステートメント (例: #include <v8.h>) を含めるだけで、node-gyp が適切なヘッダーを自動的に見つけます。ただし、注意すべき点がいくつかあります

• node-gyp が実行されると、Node.js の特定のリリ​​ースバージョンを検出し、完全なソースの tarball またはヘッダーのみをダウンロードします。完全なソースがダウンロードされた場合、アドオンは Node.js の依存関係の完全なセットにアクセスできます。ただし、Node.js のヘッダーのみがダウンロードされた場合は、Node.js によってエクスポートされたシンボルのみが利用可能になります。

• node-gyp は、ローカルの Node.js ソースイメージを指す --nodedir フラグを使用して実行できます。このオプションを使用すると、アドオンは依存関係の完全なセットにアクセスできます。

require() を使ったアドオンの読み込み#

コンパイルされたアドオンバイナリのファイル名拡張子は .node です (.dll や .so ではありません)。require() 関数は、.node ファイル拡張子を持つファイルを探し、それらを動的リンクライブラリとして初期化するように書かれています。

require() を呼び出すとき、.node 拡張子は通常省略でき、Node.js はそれでもアドオンを見つけて初期化します。ただし、注意点として、Node.js はまず同じベース名を共有するモジュールまたは JavaScript ファイルを見つけてロードしようとします。たとえば、バイナリ addon.node と同じディレクトリに addon.js ファイルがある場合、require('addon') は addon.js ファイルを優先し、代わりにそれをロードします。

関数の引数#

アドオンは通常、Node.js 内で実行されている JavaScript からアクセスできるオブジェクトと関数を公開します。JavaScript から関数が呼び出されると、入力引数と戻り値は C/C++ コードとの間でマッピングされる必要があります。

次の例は、JavaScript から渡された関数引数を読み取り、結果を返す方法を示しています

// addon.cc
#include <node.h>

namespace demo {

using v8::Exception;
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::String;
using v8::Value;

// This is the implementation of the "add" method
// Input arguments are passed using the
// const FunctionCallbackInfo<Value>& args struct
void Add(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();

  // Check the number of arguments passed.
  if (args.Length() < 2) {
    // Throw an Error that is passed back to JavaScript
    isolate->ThrowException(Exception::TypeError(
        String::NewFromUtf8(isolate,
                            "Wrong number of arguments").ToLocalChecked()));
    return;
  }

  // Check the argument types
  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {
    isolate->ThrowException(Exception::TypeError(
        String::NewFromUtf8(isolate,
                            "Wrong arguments").ToLocalChecked()));
    return;
  }

  // Perform the operation
  double value =
      args[0].As<Number>()->Value() + args[1].As<Number>()->Value();
  Local<Number> num = Number::New(isolate, value);

  // Set the return value (using the passed in
  // FunctionCallbackInfo<Value>&)
  args.GetReturnValue().Set(num);
}

void Init(Local<Object> exports) {
  NODE_SET_METHOD(exports, "add", Add);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Init)

}  // namespace demo copy

コンパイルされると、アドオンの例は Node.js 内から require して使用できます

// test.js
const addon = require('./build/Release/addon');

console.log('This should be eight:', addon.add(3, 5)); copy

コールバック#

アドオン内で JavaScript 関数を C++ 関数に渡し、そこから実行するのは一般的な慣行です。次の例は、そのようなコールバックを呼び出す方法を示しています

// addon.cc
#include <node.h>

namespace demo {

using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::Null;
using v8::Object;
using v8::String;
using v8::Value;

void RunCallback(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  Local<Context> context = isolate->GetCurrentContext();
  Local<Function> cb = Local<Function>::Cast(args[0]);
  const unsigned argc = 1;
  Local<Value> argv[argc] = {
      String::NewFromUtf8(isolate,
                          "hello world").ToLocalChecked() };
  cb->Call(context, Null(isolate), argc, argv).ToLocalChecked();
}

void Init(Local<Object> exports, Local<Object> module) {
  NODE_SET_METHOD(module, "exports", RunCallback);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Init)

}  // namespace demo copy

この例では、2番目の引数として完全な module オブジェクトを受け取る 2 引数形式の Init() を使用しています。これにより、アドオンは exports のプロパティとして関数を追加するのではなく、exports を単一の関数で完全に上書きできます。

テストするには、次の JavaScript を実行します

// test.js
const addon = require('./build/Release/addon');

addon((msg) => {
  console.log(msg);
// Prints: 'hello world'
}); copy

この例では、コールバック関数は同期的に呼び出されます。

オブジェクトファクトリ#

次の例に示すように、アドオンは C++ 関数内から新しいオブジェクトを作成して返すことができます。createObject() に渡された文字列をエコーする msg プロパティを持つオブジェクトが作成されて返されます

// addon.cc
#include <node.h>

namespace demo {

using v8::Context;
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;

void CreateObject(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  Local<Context> context = isolate->GetCurrentContext();

  Local<Object> obj = Object::New(isolate);
  obj->Set(context,
           String::NewFromUtf8(isolate,
                               "msg").ToLocalChecked(),
                               args[0]->ToString(context).ToLocalChecked())
           .FromJust();

  args.GetReturnValue().Set(obj);
}

void Init(Local<Object> exports, Local<Object> module) {
  NODE_SET_METHOD(module, "exports", CreateObject);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Init)

}  // namespace demo copy

JavaScript でテストするには

// test.js
const addon = require('./build/Release/addon');

const obj1 = addon('hello');
const obj2 = addon('world');
console.log(obj1.msg, obj2.msg);
// Prints: 'hello world' copy

関数ファクトリ#

もう一つの一般的なシナリオは、C++ 関数をラップする JavaScript 関数を作成し、それらを JavaScript に返すことです

// addon.cc
#include <node.h>

namespace demo {

using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;

void MyFunction(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  args.GetReturnValue().Set(String::NewFromUtf8(
      isolate, "hello world").ToLocalChecked());
}

void CreateFunction(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();

  Local<Context> context = isolate->GetCurrentContext();
  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, MyFunction);
  Local<Function> fn = tpl->GetFunction(context).ToLocalChecked();

  // omit this to make it anonymous
  fn->SetName(String::NewFromUtf8(
      isolate, "theFunction").ToLocalChecked());

  args.GetReturnValue().Set(fn);
}

void Init(Local<Object> exports, Local<Object> module) {
  NODE_SET_METHOD(module, "exports", CreateFunction);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Init)

}  // namespace demo copy

テストするには

// test.js
const addon = require('./build/Release/addon');

const fn = addon();
console.log(fn());
// Prints: 'hello world' copy

C++ オブジェクトのラップ#

JavaScript の new 演算子を使用して新しいインスタンスを作成できるように、C++ のオブジェクト/クラスをラップすることも可能です

// addon.cc
#include <node.h>
#include "myobject.h"

namespace demo {

using v8::Local;
using v8::Object;

void InitAll(Local<Object> exports) {
  MyObject::Init(exports);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)

}  // namespace demo copy

次に、myobject.h では、ラッパークラスが node::ObjectWrap を継承します

// myobject.h
#ifndef MYOBJECT_H
#define MYOBJECT_H

#include <node.h>
#include <node_object_wrap.h>

namespace demo {

class MyObject : public node::ObjectWrap {
 public:
  static void Init(v8::Local<v8::Object> exports);

 private:
  explicit MyObject(double value = 0);
  ~MyObject();

  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void PlusOne(const v8::FunctionCallbackInfo<v8::Value>& args);

  double value_;
};

}  // namespace demo

#endif copy

myobject.cc で、公開する様々なメソッドを実装します。次のコードでは、メソッド plusOne() をコンストラクタのプロトタイプに追加することで公開しています

// myobject.cc
#include "myobject.h"

namespace demo {

using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::ObjectTemplate;
using v8::String;
using v8::Value;

MyObject::MyObject(double value) : value_(value) {
}

MyObject::~MyObject() {
}

void MyObject::Init(Local<Object> exports) {
  Isolate* isolate = Isolate::GetCurrent();
  Local<Context> context = isolate->GetCurrentContext();

  Local<ObjectTemplate> addon_data_tpl = ObjectTemplate::New(isolate);
  addon_data_tpl->SetInternalFieldCount(1);  // 1 field for the MyObject::New()
  Local<Object> addon_data =
      addon_data_tpl->NewInstance(context).ToLocalChecked();

  // Prepare constructor template
  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New, addon_data);
  tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject").ToLocalChecked());
  tpl->InstanceTemplate()->SetInternalFieldCount(1);

  // Prototype
  NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne);

  Local<Function> constructor = tpl->GetFunction(context).ToLocalChecked();
  addon_data->SetInternalField(0, constructor);
  exports->Set(context, String::NewFromUtf8(
      isolate, "MyObject").ToLocalChecked(),
      constructor).FromJust();
}

void MyObject::New(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  Local<Context> context = isolate->GetCurrentContext();

  if (args.IsConstructCall()) {
    // Invoked as constructor: `new MyObject(...)`
    double value = args[0]->IsUndefined() ?
        0 : args[0]->NumberValue(context).FromMaybe(0);
    MyObject* obj = new MyObject(value);
    obj->Wrap(args.This());
    args.GetReturnValue().Set(args.This());
  } else {
    // Invoked as plain function `MyObject(...)`, turn into construct call.
    const int argc = 1;
    Local<Value> argv[argc] = { args[0] };
    Local<Function> cons =
        args.Data().As<Object>()->GetInternalField(0)
            .As<Value>().As<Function>();
    Local<Object> result =
        cons->NewInstance(context, argc, argv).ToLocalChecked();
    args.GetReturnValue().Set(result);
  }
}

void MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();

  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
  obj->value_ += 1;

  args.GetReturnValue().Set(Number::New(isolate, obj->value_));
}

}  // namespace demo copy

この例をビルドするには、myobject.cc ファイルを binding.gyp に追加する必要があります

{
  "targets": [
    {
      "target_name": "addon",
      "sources": [
        "addon.cc",
        "myobject.cc"
      ]
    }
  ]
} copy

次でテストします

// test.js
const addon = require('./build/Release/addon');

const obj = new addon.MyObject(10);
console.log(obj.plusOne());
// Prints: 11
console.log(obj.plusOne());
// Prints: 12
console.log(obj.plusOne());
// Prints: 13 copy

ラッパーオブジェクトのデストラクタは、オブジェクトがガベージコレクションされるときに実行されます。デストラクタのテストには、ガベージコレクションを強制的に実行できるようにするコマンドラインフラグがあります。これらのフラグは、基盤となる V8 JavaScript エンジンによって提供されます。それらはいつでも変更または削除される可能性があります。それらは Node.js または V8 によって文書化されておらず、テスト以外で使用すべきではありません。

プロセスまたはワーカースレッドのシャットダウン中、デストラクタは JS エンジンによって呼び出されません。したがって、リソースリークを避けるために、これらのオブジェクトを追跡し、適切な破棄を保証するのはユーザーの責任です。

ラップされたオブジェクトのファクトリ#

あるいは、ファクトリパターンを使用して、JavaScript の new 演算子を使ったオブジェクトインスタンスの明示的な作成を避けることも可能です

const obj = addon.createObject();
// instead of:
// const obj = new addon.Object(); copy

まず、createObject() メソッドを addon.cc に実装します

// addon.cc
#include <node.h>
#include "myobject.h"

namespace demo {

using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;

void CreateObject(const FunctionCallbackInfo<Value>& args) {
  MyObject::NewInstance(args);
}

void InitAll(Local<Object> exports, Local<Object> module) {
  MyObject::Init();

  NODE_SET_METHOD(module, "exports", CreateObject);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)

}  // namespace demo copy

myobject.h では、オブジェクトのインスタンス化を処理するために静的メソッド NewInstance() が追加されます。このメソッドは、JavaScript で new を使用する代わりになります

// myobject.h
#ifndef MYOBJECT_H
#define MYOBJECT_H

#include <node.h>
#include <node_object_wrap.h>

namespace demo {

class MyObject : public node::ObjectWrap {
 public:
  static void Init();
  static void NewInstance(const v8::FunctionCallbackInfo<v8::Value>& args);

 private:
  explicit MyObject(double value = 0);
  ~MyObject();

  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void PlusOne(const v8::FunctionCallbackInfo<v8::Value>& args);
  static v8::Global<v8::Function> constructor;
  double value_;
};

}  // namespace demo

#endif copy

myobject.cc の実装は、前の例と似ています

// myobject.cc
#include <node.h>
#include "myobject.h"

namespace demo {

using node::AddEnvironmentCleanupHook;
using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::Global;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::String;
using v8::Value;

// Warning! This is not thread-safe, this addon cannot be used for worker
// threads.
Global<Function> MyObject::constructor;

MyObject::MyObject(double value) : value_(value) {
}

MyObject::~MyObject() {
}

void MyObject::Init() {
  Isolate* isolate = Isolate::GetCurrent();
  // Prepare constructor template
  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New);
  tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject").ToLocalChecked());
  tpl->InstanceTemplate()->SetInternalFieldCount(1);

  // Prototype
  NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne);

  Local<Context> context = isolate->GetCurrentContext();
  constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());

  AddEnvironmentCleanupHook(isolate, [](void*) {
    constructor.Reset();
  }, nullptr);
}

void MyObject::New(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  Local<Context> context = isolate->GetCurrentContext();

  if (args.IsConstructCall()) {
    // Invoked as constructor: `new MyObject(...)`
    double value = args[0]->IsUndefined() ?
        0 : args[0]->NumberValue(context).FromMaybe(0);
    MyObject* obj = new MyObject(value);
    obj->Wrap(args.This());
    args.GetReturnValue().Set(args.This());
  } else {
    // Invoked as plain function `MyObject(...)`, turn into construct call.
    const int argc = 1;
    Local<Value> argv[argc] = { args[0] };
    Local<Function> cons = Local<Function>::New(isolate, constructor);
    Local<Object> instance =
        cons->NewInstance(context, argc, argv).ToLocalChecked();
    args.GetReturnValue().Set(instance);
  }
}

void MyObject::NewInstance(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();

  const unsigned argc = 1;
  Local<Value> argv[argc] = { args[0] };
  Local<Function> cons = Local<Function>::New(isolate, constructor);
  Local<Context> context = isolate->GetCurrentContext();
  Local<Object> instance =
      cons->NewInstance(context, argc, argv).ToLocalChecked();

  args.GetReturnValue().Set(instance);
}

void MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();

  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
  obj->value_ += 1;

  args.GetReturnValue().Set(Number::New(isolate, obj->value_));
}

}  // namespace demo copy

もう一度、この例をビルドするには、myobject.cc ファイルを binding.gyp に追加する必要があります

{
  "targets": [
    {
      "target_name": "addon",
      "sources": [
        "addon.cc",
        "myobject.cc"
      ]
    }
  ]
} copy

次でテストします

// test.js
const createObject = require('./build/Release/addon');

const obj = createObject(10);
console.log(obj.plusOne());
// Prints: 11
console.log(obj.plusOne());
// Prints: 12
console.log(obj.plusOne());
// Prints: 13

const obj2 = createObject(20);
console.log(obj2.plusOne());
// Prints: 21
console.log(obj2.plusOne());
// Prints: 22
console.log(obj2.plusOne());
// Prints: 23 copy

ラップされたオブジェクトの受け渡し#

C++ オブジェクトをラップして返すだけでなく、Node.js ヘルパー関数 node::ObjectWrap::Unwrap でアンラップすることにより、ラップされたオブジェクトを受け渡すことが可能です。次の例は、2つの MyObject オブジェクトを入力引数として受け取ることができる関数 add() を示しています

// addon.cc
#include <node.h>
#include <node_object_wrap.h>
#include "myobject.h"

namespace demo {

using v8::Context;
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::String;
using v8::Value;

void CreateObject(const FunctionCallbackInfo<Value>& args) {
  MyObject::NewInstance(args);
}

void Add(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  Local<Context> context = isolate->GetCurrentContext();

  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(
      args[0]->ToObject(context).ToLocalChecked());
  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(
      args[1]->ToObject(context).ToLocalChecked());

  double sum = obj1->value() + obj2->value();
  args.GetReturnValue().Set(Number::New(isolate, sum));
}

void InitAll(Local<Object> exports) {
  MyObject::Init();

  NODE_SET_METHOD(exports, "createObject", CreateObject);
  NODE_SET_METHOD(exports, "add", Add);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)

}  // namespace demo copy

myobject.h では、オブジェクトをアンラップした後にプライベートな値にアクセスできるように、新しい public メソッドが追加されます。

// myobject.h
#ifndef MYOBJECT_H
#define MYOBJECT_H

#include <node.h>
#include <node_object_wrap.h>

namespace demo {

class MyObject : public node::ObjectWrap {
 public:
  static void Init();
  static void NewInstance(const v8::FunctionCallbackInfo<v8::Value>& args);
  inline double value() const { return value_; }

 private:
  explicit MyObject(double value = 0);
  ~MyObject();

  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
  static v8::Global<v8::Function> constructor;
  double value_;
};

}  // namespace demo

#endif copy

myobject.cc の実装は、前のバージョンと似ています

// myobject.cc
#include <node.h>
#include "myobject.h"

namespace demo {

using node::AddEnvironmentCleanupHook;
using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::Global;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;

// Warning! This is not thread-safe, this addon cannot be used for worker
// threads.
Global<Function> MyObject::constructor;

MyObject::MyObject(double value) : value_(value) {
}

MyObject::~MyObject() {
}

void MyObject::Init() {
  Isolate* isolate = Isolate::GetCurrent();
  // Prepare constructor template
  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New);
  tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject").ToLocalChecked());
  tpl->InstanceTemplate()->SetInternalFieldCount(1);

  Local<Context> context = isolate->GetCurrentContext();
  constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());

  AddEnvironmentCleanupHook(isolate, [](void*) {
    constructor.Reset();
  }, nullptr);
}

void MyObject::New(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  Local<Context> context = isolate->GetCurrentContext();

  if (args.IsConstructCall()) {
    // Invoked as constructor: `new MyObject(...)`
    double value = args[0]->IsUndefined() ?
        0 : args[0]->NumberValue(context).FromMaybe(0);
    MyObject* obj = new MyObject(value);
    obj->Wrap(args.This());
    args.GetReturnValue().Set(args.This());
  } else {
    // Invoked as plain function `MyObject(...)`, turn into construct call.
    const int argc = 1;
    Local<Value> argv[argc] = { args[0] };
    Local<Function> cons = Local<Function>::New(isolate, constructor);
    Local<Object> instance =
        cons->NewInstance(context, argc, argv).ToLocalChecked();
    args.GetReturnValue().Set(instance);
  }
}

void MyObject::NewInstance(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();

  const unsigned argc = 1;
  Local<Value> argv[argc] = { args[0] };
  Local<Function> cons = Local<Function>::New(isolate, constructor);
  Local<Context> context = isolate->GetCurrentContext();
  Local<Object> instance =
      cons->NewInstance(context, argc, argv).ToLocalChecked();

  args.GetReturnValue().Set(instance);
}

}  // namespace demo copy

次でテストします

// test.js
const addon = require('./build/Release/addon');

const obj1 = addon.createObject(10);
const obj2 = addon.createObject(20);
const result = addon.add(obj1, obj2);

console.log(result);
// Prints: 30 copy