Addons

    • V8 JavaScript, a C++ library. Used for interfacing with JavaScript:
      creating objects, calling functions, etc. Documented mostly in the
      header file (deps/v8/include/v8.h in the Node source
      tree), which is also available
      online.

    • , C event loop library.
      Anytime one needs to wait for a file descriptor to become readable,
      wait for a timer, or wait for a signal to be received one will need
      to interface with libuv. That is, if you perform any I/O, libuv will
      need to be used.

    • Internal Node libraries. Most importantly is the node::ObjectWrap
      class which you will likely want to derive from.

    • Others. Look in deps/ for what else is available.

    Node statically compiles all its dependencies into the executable.
    When compiling your module, you don’t need to worry about linking to
    any of these libraries.

    All of the following examples are available for
    download and may be
    used as a starting-point for your own Addon.

    To get started let’s make a small Addon which is the C++ equivalent of
    the following JavaScript code:

    First we create a file hello.cc:

    1. // hello.cc
    2. #include <node.h>
    3. using namespace v8;
    4. void Method(const FunctionCallbackInfo<Value>& args) {
    5. Isolate* isolate = Isolate::GetCurrent();
    6. HandleScope scope(isolate);
    7. args.GetReturnValue().Set(String::NewFromUtf8(isolate, "world"));
    8. }
    9. void init(Handle<Object> exports) {
    10. NODE_SET_METHOD(exports, "hello", Method);
    11. }
    12. NODE_MODULE(addon, init)

    Note that all Node addons must export an initialization function:

    1. void Initialize (Handle<Object> exports);
    2. NODE_MODULE(module_name, Initialize)

    There is no semi-colon after NODE_MODULE as it’s not a function (see
    node.h).

    The module_name needs to match the filename of the final binary (minus the
    .node suffix).

    The source code needs to be built into addon.node, the binary Addon. To
    do this we create a file called binding.gyp which describes the configuration
    to build your module in a JSON-like format. This file gets compiled by
    .

    1. {
    2. "targets": [
    3. {
    4. "target_name": "addon",
    5. "sources": [ "hello.cc" ]
    6. }
    7. ]
    8. }

    The next step is to generate the appropriate project build files for the
    current platform. Use node-gyp configure for that.

    Now you have your compiled .node bindings file! The compiled bindings end up
    in build/Release/.

    You can now use the binary addon in a Node project hello.js by pointing
    require to the recently built hello.node module:

    1. // hello.js
    2. var addon = require('./build/Release/addon');
    3. console.log(addon.hello()); // 'world'

    Please see patterns below for further information or
    https://github.com/arturadib/node-qt for an example in production.

    Addon patterns

    Below are some addon patterns to help you get started. Consult the online
    v8 reference for help with the various v8
    calls, and v8’s
    for an explanation of several concepts used such as handles, scopes,
    function templates, etc.

    In order to use these examples you need to compile them using node-gyp.
    Create the following binding.gyp file:

    1. {
    2. "targets": [
    3. {
    4. "target_name": "addon",
    5. "sources": [ "addon.cc" ]
    6. }
    7. ]
    8. }

    In cases where there is more than one .cc file, simply add the file name to
    the sources array, e.g.:

    1. "sources": ["addon.cc", "myexample.cc"]

    Now that you have your binding.gyp ready, you can configure and build the
    addon:

    1. $ node-gyp configure build

    The following pattern illustrates how to read arguments from JavaScript
    function calls and return a result. This is the main and only needed source
    addon.cc:

    1. // addon.cc
    2. #include <node.h>
    3. using namespace v8;
    4. void Add(const FunctionCallbackInfo<Value>& args) {
    5. Isolate* isolate = Isolate::GetCurrent();
    6. HandleScope scope(isolate);
    7. if (args.Length() < 2) {
    8. isolate->ThrowException(Exception::TypeError(
    9. String::NewFromUtf8(isolate, "Wrong number of arguments")));
    10. return;
    11. }
    12. if (!args[0]->IsNumber() || !args[1]->IsNumber()) {
    13. isolate->ThrowException(Exception::TypeError(
    14. String::NewFromUtf8(isolate, "Wrong arguments")));
    15. return;
    16. }
    17. double value = args[0]->NumberValue() + args[1]->NumberValue();
    18. Local<Number> num = Number::New(isolate, value);
    19. args.GetReturnValue().Set(num);
    20. }
    21. void Init(Handle<Object> exports) {
    22. NODE_SET_METHOD(exports, "add", Add);
    23. }
    24. NODE_MODULE(addon, Init)

    You can test it with the following JavaScript snippet:

    Callbacks

    You can pass JavaScript functions to a C++ function and execute them from
    there. Here’s addon.cc:

    1. // addon.cc
    2. #include <node.h>
    3. using namespace v8;
    4. void RunCallback(const FunctionCallbackInfo<Value>& args) {
    5. Isolate* isolate = Isolate::GetCurrent();
    6. HandleScope scope(isolate);
    7. Local<Function> cb = Local<Function>::Cast(args[0]);
    8. const unsigned argc = 1;
    9. Local<Value> argv[argc] = { String::NewFromUtf8(isolate, "hello world") };
    10. cb->Call(isolate->GetCurrentContext()->Global(), argc, argv);
    11. }
    12. void Init(Handle<Object> exports, Handle<Object> module) {
    13. NODE_SET_METHOD(module, "exports", RunCallback);
    14. }
    15. NODE_MODULE(addon, Init)

    Note that this example uses a two-argument form of Init() that receives
    the full module object as the second argument. This allows the addon
    to completely overwrite exports with a single function instead of
    adding the function as a property of exports.

    To test it run the following JavaScript snippet:

    1. // test.js
    2. var addon = require('./build/Release/addon');
    3. addon(function(msg){
    4. console.log(msg); // 'hello world'
    5. });

    You can create and return new objects from within a C++ function with this
    addon.cc pattern, which returns an object with property msg that echoes
    the string passed to createObject():

    1. // addon.cc
    2. #include <node.h>
    3. using namespace v8;
    4. void CreateObject(const FunctionCallbackInfo<Value>& args) {
    5. Isolate* isolate = Isolate::GetCurrent();
    6. HandleScope scope(isolate);
    7. Local<Object> obj = Object::New(isolate);
    8. obj->Set(String::NewFromUtf8(isolate, "msg"), args[0]->ToString());
    9. args.GetReturnValue().Set(obj);
    10. }
    11. NODE_SET_METHOD(module, "exports", CreateObject);
    12. }
    13. NODE_MODULE(addon, Init)
    1. // test.js
    2. var obj1 = addon('hello');
    3. var obj2 = addon('world');
    4. console.log(obj1.msg+' '+obj2.msg); // 'hello world'

    Function factory

    This pattern illustrates how to create and return a JavaScript function that
    wraps a C++ function:

    1. // addon.cc
    2. #include <node.h>
    3. using namespace v8;
    4. void MyFunction(const FunctionCallbackInfo<Value>& args) {
    5. Isolate* isolate = Isolate::GetCurrent();
    6. HandleScope scope(isolate);
    7. args.GetReturnValue().Set(String::NewFromUtf8(isolate, "hello world"));
    8. }
    9. void CreateFunction(const FunctionCallbackInfo<Value>& args) {
    10. Isolate* isolate = Isolate::GetCurrent();
    11. HandleScope scope(isolate);
    12. Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, MyFunction);
    13. Local<Function> fn = tpl->GetFunction();
    14. // omit this to make it anonymous
    15. fn->SetName(String::NewFromUtf8(isolate, "theFunction"));
    16. args.GetReturnValue().Set(fn);
    17. }
    18. void Init(Handle<Object> exports, Handle<Object> module) {
    19. NODE_SET_METHOD(module, "exports", CreateFunction);
    20. }
    21. NODE_MODULE(addon, Init)

    To test:

    1. // test.js
    2. var addon = require('./build/Release/addon');
    3. var fn = addon();
    4. console.log(fn()); // 'hello world'

    Here we will create a wrapper for a C++ object/class MyObject that can be
    instantiated in JavaScript through the new operator. First prepare the main
    module addon.cc:

    1. // addon.cc
    2. #include <node.h>
    3. #include "myobject.h"
    4. using namespace v8;
    5. void InitAll(Handle<Object> exports) {
    6. MyObject::Init(exports);
    7. }
    8. NODE_MODULE(addon, InitAll)

    Then in myobject.h make your wrapper inherit from node::ObjectWrap:

    1. // myobject.h
    2. #ifndef MYOBJECT_H
    3. #define MYOBJECT_H
    4. #include <node.h>
    5. #include <node_object_wrap.h>
    6. class MyObject : public node::ObjectWrap {
    7. public:
    8. static void Init(v8::Handle<v8::Object> exports);
    9. private:
    10. explicit MyObject(double value = 0);
    11. ~MyObject();
    12. static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
    13. static void PlusOne(const v8::FunctionCallbackInfo<v8::Value>& args);
    14. static v8::Persistent<v8::Function> constructor;
    15. double value_;
    16. };
    17. #endif

    And in myobject.cc implement the various methods that you want to expose.
    Here we expose the method plusOne by adding it to the constructor’s
    prototype:

    Test it with:

    1. // test.js
    2. var addon = require('./build/Release/addon');
    3. var obj = new addon.MyObject(10);
    4. console.log( obj.plusOne() ); // 11
    5. console.log( obj.plusOne() ); // 12
    6. console.log( obj.plusOne() ); // 13

    Factory of wrapped objects

    This is useful when you want to be able to create native objects without
    explicitly instantiating them with the new operator in JavaScript, e.g.

    1. var obj = addon.createObject();
    2. // instead of:
    3. // var obj = new addon.Object();

    Let’s register our createObject method in addon.cc:

    1. // addon.cc
    2. #include <node.h>
    3. #include "myobject.h"
    4. using namespace v8;
    5. void CreateObject(const FunctionCallbackInfo<Value>& args) {
    6. Isolate* isolate = Isolate::GetCurrent();
    7. HandleScope scope(isolate);
    8. MyObject::NewInstance(args);
    9. }
    10. void InitAll(Handle<Object> exports, Handle<Object> module) {
    11. MyObject::Init();
    12. NODE_SET_METHOD(module, "exports", CreateObject);
    13. }
    14. NODE_MODULE(addon, InitAll)

    In myobject.h we now introduce the static method NewInstance that takes
    care of instantiating the object (i.e. it does the job of new in JavaScript):

    1. // myobject.h
    2. #ifndef MYOBJECT_H
    3. #define MYOBJECT_H
    4. #include <node.h>
    5. #include <node_object_wrap.h>
    6. class MyObject : public node::ObjectWrap {
    7. public:
    8. static void Init();
    9. static void NewInstance(const v8::FunctionCallbackInfo<v8::Value>& args);
    10. private:
    11. explicit MyObject(double value = 0);
    12. ~MyObject();
    13. static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
    14. static void PlusOne(const v8::FunctionCallbackInfo<v8::Value>& args);
    15. static v8::Persistent<v8::Function> constructor;
    16. double value_;
    17. };
    18. #endif

    The implementation is similar to the above in myobject.cc:

    1. // myobject.cc
    2. #include <node.h>
    3. #include "myobject.h"
    4. using namespace v8;
    5. Persistent<Function> MyObject::constructor;
    6. MyObject::MyObject(double value) : value_(value) {
    7. MyObject::~MyObject() {
    8. }
    9. void MyObject::Init() {
    10. Isolate* isolate = Isolate::GetCurrent();
    11. // Prepare constructor template
    12. Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New);
    13. tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject"));
    14. tpl->InstanceTemplate()->SetInternalFieldCount(1);
    15. // Prototype
    16. NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne);
    17. constructor.Reset(isolate, tpl->GetFunction());
    18. }
    19. void MyObject::New(const FunctionCallbackInfo<Value>& args) {
    20. Isolate* isolate = Isolate::GetCurrent();
    21. HandleScope scope(isolate);
    22. if (args.IsConstructCall()) {
    23. // Invoked as constructor: `new MyObject(...)`
    24. double value = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
    25. MyObject* obj = new MyObject(value);
    26. obj->Wrap(args.This());
    27. args.GetReturnValue().Set(args.This());
    28. } else {
    29. // Invoked as plain function `MyObject(...)`, turn into construct call.
    30. const int argc = 1;
    31. Local<Value> argv[argc] = { args[0] };
    32. Local<Function> cons = Local<Function>::New(isolate, constructor);
    33. args.GetReturnValue().Set(cons->NewInstance(argc, argv));
    34. }
    35. }
    36. void MyObject::NewInstance(const FunctionCallbackInfo<Value>& args) {
    37. Isolate* isolate = Isolate::GetCurrent();
    38. HandleScope scope(isolate);
    39. const unsigned argc = 1;
    40. Handle<Value> argv[argc] = { args[0] };
    41. Local<Function> cons = Local<Function>::New(isolate, constructor);
    42. Local<Object> instance = cons->NewInstance(argc, argv);
    43. args.GetReturnValue().Set(instance);
    44. }
    45. void MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {
    46. Isolate* isolate = Isolate::GetCurrent();
    47. HandleScope scope(isolate);
    48. MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.Holder());
    49. obj->value_ += 1;
    50. args.GetReturnValue().Set(Number::New(isolate, obj->value_));
    51. }

    Test it with:

    1. // test.js
    2. var createObject = require('./build/Release/addon');
    3. var obj = createObject(10);
    4. console.log( obj.plusOne() ); // 11
    5. console.log( obj.plusOne() ); // 12
    6. console.log( obj.plusOne() ); // 13
    7. var obj2 = createObject(20);
    8. console.log( obj2.plusOne() ); // 21
    9. console.log( obj2.plusOne() ); // 22
    10. console.log( obj2.plusOne() ); // 23

    In addition to wrapping and returning C++ objects, you can pass them around
    by unwrapping them with Node’s node::Unwrap helper function.
    In the following addon.cc we introduce a function add() that can take on two
    MyObject objects:

    1. // addon.cc
    2. #include <node.h>
    3. #include <node_object_wrap.h>
    4. #include "myobject.h"
    5. using namespace v8;
    6. void CreateObject(const FunctionCallbackInfo<Value>& args) {
    7. Isolate* isolate = Isolate::GetCurrent();
    8. HandleScope scope(isolate);
    9. MyObject::NewInstance(args);
    10. }
    11. void Add(const FunctionCallbackInfo<Value>& args) {
    12. Isolate* isolate = Isolate::GetCurrent();
    13. HandleScope scope(isolate);
    14. MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(
    15. args[0]->ToObject());
    16. MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(
    17. args[1]->ToObject());
    18. double sum = obj1->value() + obj2->value();
    19. args.GetReturnValue().Set(Number::New(isolate, sum));
    20. }
    21. void InitAll(Handle<Object> exports) {
    22. MyObject::Init();
    23. NODE_SET_METHOD(exports, "createObject", CreateObject);
    24. NODE_SET_METHOD(exports, "add", Add);
    25. }
    26. NODE_MODULE(addon, InitAll)

    To make things interesting we introduce a public method in myobject.h so we
    can probe private values after unwrapping the object:

    1. // myobject.h
    2. #ifndef MYOBJECT_H
    3. #define MYOBJECT_H
    4. #include <node.h>
    5. #include <node_object_wrap.h>
    6. class MyObject : public node::ObjectWrap {
    7. public:
    8. static void Init();
    9. static void NewInstance(const v8::FunctionCallbackInfo<v8::Value>& args);
    10. inline double value() const { return value_; }
    11. private:
    12. explicit MyObject(double value = 0);
    13. ~MyObject();
    14. static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
    15. static v8::Persistent<v8::Function> constructor;
    16. double value_;
    17. };
    18. #endif

    Test it with:

    1. // test.js
    2. var addon = require('./build/Release/addon');
    3. var obj1 = addon.createObject(10);
    4. var obj2 = addon.createObject(20);
    5. var result = addon.add(obj1, obj2);
    6. console.log(result); // 30