libuvを用いた非同期処理を含むNode.js Native Addon入門

概要

Motivation

Node.jsのNative Extensionの解説記事はたくさんあるのですが、情報が古かったり、公式のドキュメントもやや使いづらかったりするので、今回の記事を執筆する運びとなりました。

この記事が目標としていること

動くサンプルを通じて、Native Addonを作るための最低限の要素に触れ、C++の知識があれば大抵のものは作れるようになります（なるはずです）

最低限の要素とは以下の4つです。

• JavaScript - C++の橋渡し
• V8のAPIの基本的な操作（配列操作、オブジェクトの操作を含む）
• 内部にC++のオブジェクトを持ったJavaScriptのオブジェクトの作成
• 非同期処理

ついでに実現できること

V8がどう動いているのかがほんの少しわかります。

バージョン情報

• Mac OS X 10.12.6
• Node.js v9.3.0

リポジトリ

1. はじめの一歩

まずは、C++の関数を呼び出してNodeの文字列を作成し、JSの世界に返すだけのサンプルから入ります。ほぼ公式のドキュメントのままです。

とりあえずビルドツールを準備する

npmとnodeはインストール済みであるとします。

$ npm install -g node-gyp

はじめに何を作るか

これと等価なNodeモジュールを作成します。

module.exports.hello = () => "world";

実装

その壱

function Hello() {
  return "world";
}

まずは、上記JavaScriptの関数に対応するコードをC++で書いてみましょう。

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

全体が型がv8::FunctionCallbackInfo<v8::Value>のargsを引数にとる関数になっています。引数argsからは、JS側で指定した関数の引数を受け取ることができ、またargs.GetReturnValue().Set を呼び出してやると、関数の返り値を設定することができます。

その弐

module.exports.hello = Hello

次に上記コードに対応するC++のコードを書いてみます。

void init(Local<Object> exports) {
  NODE_SET_METHOD(exports, "hello", Hello);
}

NODE_SET_METHODというマクロのふりをした関数がよしなにやってくれます（昔はマクロだったらしい）。v8::Local<v8::Object>はV8オブジェクトへのポインタを意味し、適当なタイミングでGCの対象となります。

マクロの中身をちょっと覗いてやるとこんな感じになっています。v8::HandleScope handle_scope(isolate)を書いてやることによって、関数を抜ける時、HandleScopeのデストラクタが呼ばれたタイミングで、Local型で宣言された変数がGCの対象となるようになります。

inline void NODE_SET_METHOD(v8::Local<v8::Object> recv,
                            const char* name,
                            v8::FunctionCallback callback) {
  v8::Isolate* isolate = v8::Isolate::GetCurrent();
  v8::HandleScope handle_scope(isolate);
  v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New(isolate,
                                                                callback);
  v8::Local<v8::Function> fn = t->GetFunction();
  v8::Local<v8::String> fn_name = v8::String::NewFromUtf8(isolate, name);
  fn->SetName(fn_name);
  recv->Set(fn_name, fn);
}

上では大雑把な解説を書きましたが、実際には上のHello関数の型（void Hello(const FunctionCallbackInfo<Value>& args)）をもつ関数は、v8::FunctionTemplate::Newの引数となることができて、v8::Local<v8::FunctionTemplate>のGetFunctionを呼んでやると、V8上の関数になります。

その参

壱および弐がNodeモジュールとして機能するために最後の仕上げが必要です。

NODE_MODULE(NODE_GYP_MODULE_NAME, init)

マクロです

その肆

C++の部分を全部をまとめるとこのようなコードになります。

#include <node.h>

namespace demo {

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

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

void init(Local<Object> exports) {
  NODE_SET_METHOD(exports, "hello", Hello);
}

// このマクロの後にはセミコロンは不要
NODE_MODULE(NODE_GYP_MODULE_NAME, init)

}  // namespace demo

その伍

Makefileに相当するものをまだ書いてないので、node-gypがきちんと動くように、binding.gypを書いてやります。

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

以上で実装は完了です。node-gyp configureした後にnode-gyp buildを行うことで、以下のJavaScriptのコードが期待したとおりに動くようになります。

const addon = require('./build/Release/addon');
console.log(addon.hello());  // world

解説

Isolateについて

Isolateを用いることで、実行中のJavaScriptのスコープを得ることができます。後にも出てきますが、HandleScopeがよしなにメモリ管理を行ってくれます。

Isolateについてもう少し詳しく

Isolateを経由して現在のスコープを取得することができますが、Isolate自体は独立したV8のランタイムを示すものです。スコープの制御の他に、ヒープ管理機構や、ガベージコレクタも含みます。同時に一つのスレッドしかIsoateにアクセスすることはできませんが、複数のスレッドから操作することができます。

ところが、IsolateだけではV8のランタイムとしては成立せず、Contextというものも準備する必要があります。Contextはルートオブジェクトを用意してくれます。たとえば、iframeの内部などはContextを分けて制御しています。

また、iframeの例からもわかるように、Isolateの内部には複数のContextが存在することができ、かつ、Isolateが排他ロック制御を行ってくれるおかげで、別々のContextに含まれるObjectは簡単にかつ安全に共有することができます。

さらにIsolateについて

https://github.com/v8/v8/wiki/Embedder's-Guide に書いてあります。

V8をゼロからまるっと動かすサンプルもあります。
https://github.com/v8/v8/blob/master/samples/hello-world.cc

完全なサンプル

https://github.com/kentrino/native-node-addon-samples の./hello_world 以下にあります

2. つぎ

JavaScriptの世界から値を受け取って、C++側で利用してみましょう。

何を作るか

function printEverything() {
  if (typeof arguments.length < 2) {
    throw new TypeError("Wrong number of arguments.");
  }
  if (typeof arguments[0] !== "number") {
    throw new TypeError("Argument #1 must be a number.");
  }

  if (typeof arguments[1] !== "string") {
    throw new TypeError("Argument #2 must be a string.");
  }
  console.log(`${arguments[0]}, ${arguments[1]}`);
}

module.exports.printEverything = printEverything;

とだいたい等価なモジュールを作ってみましょう（実際は配列とオブジェクトも引数にとり、それらを表示する関数になっています）

• 引数の数、型のチェックがあること
• 例外を投げているところ

が新しい要素です。先程扱っていないところだけを紹介します。

引数の数、型チェックを行う

  if (args.Length() < 2) {
    //
  }

  if (!args[0]->IsNumber()) {
    //
  }

  if (!args[1]->IsString()) {
    //
  }

このようにして、引数の数をみたり、型チェックを行ったりすることができます。

V8の例外を投げる

    isolate->ThrowException(Exception::TypeError(String::NewFromUtf8(isolate, "Argument #2 must be string.")));

V8の値からC++で扱いやすい形に変換する

数値の場合

  double number = args[0]->NumberValue();

文字列の場合

  String::Utf8Value string(args[1]);
  std::string cpp_string = std::string(*string);

配列の場合

  Local<Array> array = Local<Array>::Cast(args[2]);
  std::vector<double> vec;
  unsigned int length = array->Length();
  for (unsigned int i = 0; i < length; i++) {
    if (!array->Get(i)->IsNumber()) {
      isolate->ThrowException(Exception::TypeError(String::NewFromUtf8(isolate, "Argument #3 must consist only of number.")));
    }
    vec.push_back((double)Local<Number>::Cast(array->Get(i))->NumberValue());
  }

オブジェクトの場合

  std::map<std::string, std::string> mp;

  Local<Context> context = isolate->GetCurrentContext();
  Local<Array> props = object->GetOwnPropertyNames(context).ToLocalChecked();
  unsigned int length = props->Length();
  for(unsigned int i = 0; i < length; ++i) {
    Local<Value> local_key = props->Get(i);
    Local<Value> local_val = object->Get(context, local_key).ToLocalChecked();
    if (!local_key->IsString() || !local_val->IsString()) {
      isolate->ThrowException(Exception::TypeError(String::NewFromUtf8(isolate, "Argument #4 must have type of { [key: string]: string; }.")));      
    }
    std::string key = *String::Utf8Value(local_key);
    std::string val = *String::Utf8Value(local_val);
    mp[key] = val;
  }

完全なサンプル

https://github.com/kentrino/native-node-addon-samples の./print_everything 以下にあります。

3. さらにつぎ

今度は、C++のオブジェクトを内部に含んだJavaScriptのオブジェクトを作ってみましょう。実用的なNative Addonを作るために必ず必要となってくるテクニックです。

何を作るか

helloプロパティを呼ぶとworldが返ってくるフレンドリーなスタッククラスを作ってみます。

const h = new HelloStack();
h.hello;   // "world"
h.push(3);
h.pop();   // 3

実装

自前のV8オブジェクトを作るクラスの概要

実際にはV8オブジェクトの内部に収まるクラスを作成します。
クラス定義では、node::ObjectWrapを継承します。

#include <node_object_wrap.h>

class HelloStack : public node::ObjectWrap {
 public:
  // コンストラクタをヒープにロードして、呼び出せるようにする
  // プロトタイプの関数のセット、インスタンスが内部にC++のフィールドを持っていることはここで宣言する
  static void LoadConstructor(v8::Isolate* isolate);

  // インスタンスを作成する。下記のConstructorを直接JavaScript側から叩くことができないので、この関数で仲介する
  static void CreateNewInstance(const v8::FunctionCallbackInfo<v8::Value>& args);

  // プロトタイプ関数の実装
  static void Push(const v8::FunctionCallbackInfo<v8::Value>& args);
  static void Pop(const v8::FunctionCallbackInfo<v8::Value>& args);

  // スタックの内部実装で使うvector
  std::vector<double> stack_;

 private:
  explicit HelloStack();
  ~HelloStack();

  // Constructorの実装。プロパティhelloの作成はここで行う
  static void Constructor(const v8::FunctionCallbackInfo<v8::Value>& args);

  // V8ヒープにのっているコンストラクタ
  static v8::Persistent<v8::Function> constructor;
};

モジュール作成部分

Init時にHelloStack::LoadConstructorを呼んでいます。

void CreateNewInstance(const FunctionCallbackInfo<Value>& args) {
  HelloStack::CreateNewInstance(args);
}

void Init(Local<Object> exports, Local<Object> module) {
  HelloStack::LoadConstructor(exports->GetIsolate());

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

NODE_MODULE(NODE_GYP_MODULE_NAME, Init);

}  // namespace demo

個々の実装

InstanceTemplate はインスタンス化されたときの形状を指定します。

void HelloStack::LoadConstructor(Isolate* isolate) {
  HandleScope scope(isolate);
  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, Constructor);
  tpl->SetClassName(String::NewFromUtf8(isolate, "HelloStack"));
  // V8のオブジェクトには、JavaScriptから見えない内部フィールドを持たせることができ、今回の場合、
  // C++のオブジェクトをラップしたV8オブジェクトを作るので1以上である必要がある *1
  tpl->InstanceTemplate()->SetInternalFieldCount(1);

  // プロトタイプの関数を定義する
  NODE_SET_PROTOTYPE_METHOD(tpl, "push", Push);
  NODE_SET_PROTOTYPE_METHOD(tpl, "pop", Pop);

  HelloStack::constructor.Reset(isolate, tpl->GetFunction());
}

*1 Assertion failed: (handle->InternalFieldCount() > 0), function Wrap, file .../include/node/node_object_wrap.h, line 77. が起こる

void HelloStack::Constructor(const FunctionCallbackInfo<Value>& args) {
  Isolate* isolate = args.GetIsolate();
  HandleScope scope(isolate);

  // new演算子 or Local<Function>#NewInstanceによる呼び出しの場合
  if (args.IsConstructCall()) {
    HelloStack* obj = new HelloStack();
    Local<Object> that = args.This();

    that->Set(String::NewFromUtf8(isolate, "hello"), String::NewFromUtf8(isolate, "world"));

    obj->Wrap(that);
    args.GetReturnValue().Set(that);
    return;
  }
}

解説

　マクロとかの中身

NODE_SET_PROTOTYPE_METHOD の実装です。先程のNODE_SET_METHODとほぼ同じことをしていますね（レシーバーが適切かどうかを判定するためのSignatureを設定していますが、どのように機能するのかは調べきれていません）。PrototypeTemplateはSomeObject.prototype と同義です。

inline void NODE_SET_PROTOTYPE_METHOD(v8::Local<v8::FunctionTemplate> recv, const char* name, v8::FunctionCallback callback) {
  v8::Isolate* isolate = v8::Isolate::GetCurrent();
  v8::HandleScope handle_scope(isolate);
  v8::Local<v8::Signature> s = v8::Signature::New(isolate, recv);
  v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New(isolate, callback, v8::Local<v8::Value>(), s);
  v8::Local<v8::String> fn_name = v8::String::NewFromUtf8(isolate, name);
  t->SetClassName(fn_name);
  recv->PrototypeTemplate()->Set(fn_name, t);
}

obj->Wrap の中身です。きちんとMakeWeak()されているので、V8オブジェクトの破棄時にV8がHelloStackをGCしてくれます。

  inline void Wrap(v8::Local<v8::Object> handle) {
    assert(persistent().IsEmpty());
    assert(handle->InternalFieldCount() > 0);
    handle->SetAlignedPointerInInternalField(0, this);
    persistent().Reset(v8::Isolate::GetCurrent(), handle);
    MakeWeak();
  }

Persistentなオブジェクトについて

LocalのオブジェクトはHandleScopeのデストラクタが呼ばれるタイミングで（= C++の関数を抜けるタイミングで）GCの対象となりますが、Persistentのオブジェクトは明示的に.Reset() を呼ばない限りGCされることはありません

完全なサンプル

https://github.com/kentrino/native-node-addon-samples の./hello_stack 以下にあります

4. ラスト

いよいよlibuvを用いた非同期処理を含んだ、Native Addonの作成にうつります。今回はフィボナッチ数列を計算してくれる、こんな感じに動作するモジュールを作ります。

computeFibonacci(10, console.log); // 55

実装

わかりやすいところから始めます。

フィボナッチ数列を計算するところ

std::string ComputeFibonacci(int number) {
  int i;
  long long a, b, c;
  a = 1;
  b = 1;
  if (number == 1) return std::to_string(a);
  if (number == 2) return std::to_string(b);
  for (i = 0; i < number - 2; ++i) {
    c = a + b;
    a = b;
    b = c;
  }
  return std::to_string(c);
}

まずはデータから

class AsyncWork {
  public:
    // フィボナッチ数列の計算が終わったあと、JavaScriptの世界へ渡す処理
    // PersistentにしておかないとGCされてしまう
    v8::Persistent<v8::Function> callback;

    // フィボナッチ数列の何項目か
    int number;

    // フィボナッチ数列の計算結果を詰める
    std::string result;

    // あとでメモリを解放するために突っ込んである
    uv_work_t uv_request;
};

データ型をみると、ある程度処理の様子が想像できると思います。

非同期処理のキューに詰めるところ

uv_work_t型の&work->uv_requestをこのように指定してやります。uv_work_tは内部のフィールドにdataを保持しており、ここに処理するべき内容を突っ込んでやります。
DoWorkがキューのイベントの非同期処理を行う関数で、AfterWorkでは非同期処理終了後の処理を渡しています。

uv_queue_work(uv_default_loop(), &work->uv_request, (uv_work_cb)DoWork, (uv_after_work_cb)AfterWork);

他の部分と合わせるとこんな感じになります。

void ComputeFibonacciAsync(const FunctionCallbackInfo<Value> &args) {
  Isolate *isolate = Isolate::GetCurrent();
  HandleScope scope(isolate);

  int number = (args[0]->NumberValue());
  // JavaScriptのコールバック関数
  Local<Function> cb_local = Local<Function>::Cast(args[1]);

  AsyncWork *work = new AsyncWork;
  work->uv_request.data = work;
  work->callback.Reset(isolate, cb_local);
  work->number = number;

  uv_queue_work(uv_default_loop(), &work->uv_request, (uv_work_cb)DoWork, (uv_after_work_cb)AfterWork);
}

DoWork

キューのイベントを処理するところです。簡単ですね。

static void DoWork(uv_work_t *req) {
  AsyncWork *work = static_cast<AsyncWork *>(req->data);
  std::string result = ComputeFibonacci(work->number);
  work->result = result;
}

AfterWork

非同期処理終了後の処理になります。work から、result を取り出し、その結果をJavaScriptのコールバックに渡してやります。

static void AfterWork(uv_work_t *req, int status) {
  Isolate *isolate = Isolate::GetCurrent();
  HandleScope scope(isolate);

  AsyncWork *work = static_cast<AsyncWork *>(req->data);
  Local<String> result = String::NewFromUtf8(isolate, work->result.c_str());

  const unsigned argc = 1;
  Local<Value> argv[argc] = {result};
  Local<Function> cb = Local<Function>::New(isolate, work->callback);
  cb->Call(isolate->GetCurrentContext()->Global(), argc, argv);
  work->callback.Reset();

  delete work;
}

完全なサンプル

https://github.com/kentrino/native-node-addon-samples の./async_fibonacci 以下にあります

GMPを使ったバージョン

上のサンプルだとlong longの範囲でしか計算できないので、GMPを使った任意精度版も用意しました。

https://github.com/kentrino/native-node-addon-samples の./gmp_async_fibonacci 以下にあります

GMPのインストール

$ brew install gmp

その他

NAN(https://github.com/nodejs/nan) を使ったものだが優れたサンプルが豊富にある。

参考

• https://github.com/nikhilm/uvbook
• https://github.com/v8/v8/wiki/Embedder's%20Guide
• https://nodejs.org/api/addons.html
• https://mattn.kaoriya.net/software/lang/c/20110325015245.htm
• https://stackoverflow.com/questions/19383724/what-exactly-is-the-difference-between-v8isolate-and-v8context
• https://nodeaddons.com/how-not-to-access-node-js-from-c-worker-threads/

質問・マサカリ

まで気軽にお声掛けください。