{ "source": "doc/api/addons.markdown", "modules": [ { "textRaw": "Addons", "name": "addons", "desc": "
Addons are dynamically linked shared objects. They can provide glue to C and\nC++ libraries. The API (at the moment) is rather complex, involving\nknowledge of several libraries:\n\n
\nV8 JavaScript, a C++ library. Used for interfacing with JavaScript:\ncreating objects, calling functions, etc. Documented mostly in the\nv8.h
header file (deps/v8/include/v8.h
in the Node source\ntree), which is also available\nonline.
libuv, C event loop library.\nAnytime one needs to wait for a file descriptor to become readable,\nwait for a timer, or wait for a signal to be received one will need\nto interface with libuv. That is, if you perform any I/O, libuv will\nneed to be used.
\nInternal Node libraries. Most importantly is the node::ObjectWrap
\nclass 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.\nWhen compiling your module, you don't need to worry about linking to\nany of these libraries.\n\n
\nAll of the following examples are available for\ndownload and may be\nused as a starting-point for your own Addon.\n\n
\n", "modules": [ { "textRaw": "Hello world", "name": "hello_world", "desc": "To get started let's make a small Addon which is the C++ equivalent of\nthe following JavaScript code:\n\n
\nmodule.exports.hello = function() { return 'world'; };
\nFirst we create a file hello.cc
:\n\n
#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> Method(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n return scope.Close(String::New("world"));\n}\n\nvoid init(Handle<Object> exports) {\n exports->Set(String::NewSymbol("hello"),\n FunctionTemplate::New(Method)->GetFunction());\n}\n\nNODE_MODULE(hello, init)
\nNote that all Node addons must export an initialization function:\n\n
\nvoid Initialize (Handle<Object> exports);\nNODE_MODULE(module_name, Initialize)
\nThere is no semi-colon after NODE_MODULE
as it's not a function (see\nnode.h
).\n\n
The module_name
needs to match the filename of the final binary (minus the\n.node suffix).\n\n
The source code needs to be built into hello.node
, the binary Addon. To\ndo this we create a file called binding.gyp
which describes the configuration\nto build your module in a JSON-like format. This file gets compiled by\nnode-gyp.\n\n
{\n "targets": [\n {\n "target_name": "hello",\n "sources": [ "hello.cc" ]\n }\n ]\n}
\nThe next step is to generate the appropriate project build files for the\ncurrent platform. Use node-gyp configure
for that.\n\n
Now you will have either a Makefile
(on Unix platforms) or a vcxproj
file\n(on Windows) in the build/
directory. Next invoke the node-gyp build
\ncommand.\n\n
Now you have your compiled .node
bindings file! The compiled bindings end up\nin build/Release/
.\n\n
You can now use the binary addon in a Node project hello.js
by pointing\nrequire
to the recently built hello.node
module:\n\n
var addon = require('./build/Release/hello');\n\nconsole.log(addon.hello()); // 'world'
\nPlease see patterns below for further information or\n
\nhttps://github.com/arturadib/node-qt for an example in production.\n\n\n
\n", "type": "module", "displayName": "Hello world" }, { "textRaw": "Addon patterns", "name": "addon_patterns", "desc": "Below are some addon patterns to help you get started. Consult the online\nv8 reference for help with the various v8\ncalls, and v8's Embedder's Guide\nfor an explanation of several concepts used such as handles, scopes,\nfunction templates, etc.\n\n
\nIn order to use these examples you need to compile them using node-gyp
.\nCreate the following binding.gyp
file:\n\n
{\n "targets": [\n {\n "target_name": "addon",\n "sources": [ "addon.cc" ]\n }\n ]\n}
\nIn cases where there is more than one .cc
file, simply add the file name to\nthe sources
array, e.g.:\n\n
"sources": ["addon.cc", "myexample.cc"]
\nNow that you have your binding.gyp
ready, you can configure and build the\naddon:\n\n
$ node-gyp configure build
\n",
"modules": [
{
"textRaw": "Function arguments",
"name": "function_arguments",
"desc": "The following pattern illustrates how to read arguments from JavaScript\nfunction calls and return a result. This is the main and only needed source\naddon.cc
:\n\n
#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> Add(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n if (args.Length() < 2) {\n ThrowException(Exception::TypeError(\n String::New("Wrong number of arguments")));\n return scope.Close(Undefined(isolate));\n }\n\n if (!args[0]->IsNumber() || !args[1]->IsNumber()) {\n ThrowException(Exception::TypeError(String::New("Wrong arguments")));\n return scope.Close(Undefined(isolate));\n }\n\n Local<Number> num = Number::New(args[0]->NumberValue() +\n args[1]->NumberValue());\n return scope.Close(num);\n}\n\nvoid Init(Handle<Object> exports) {\n exports->Set(String::NewSymbol("add"),\n FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\nYou can test it with the following JavaScript snippet:\n\n
\nvar addon = require('./build/Release/addon');\n\nconsole.log( 'This should be eight:', addon.add(3,5) );
\n",
"type": "module",
"displayName": "Function arguments"
},
{
"textRaw": "Callbacks",
"name": "callbacks",
"desc": "You can pass JavaScript functions to a C++ function and execute them from\nthere. Here's addon.cc
:\n\n
#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> RunCallback(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n Local<Function> cb = Local<Function>::Cast(args[0]);\n const unsigned argc = 1;\n Local<Value> argv[argc] = { String::New("hello world") };\n cb->Call(Context::GetCurrent()->Global(), argc, argv);\n\n return scope.Close(Undefined(isolate));\n}\n\nvoid Init(Handle<Object> exports, Handle<Object> module) {\n module->Set(String::NewSymbol("exports"),\n FunctionTemplate::New(RunCallback)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\nNote that this example uses a two-argument form of Init()
that receives\nthe full module
object as the second argument. This allows the addon\nto completely overwrite exports
with a single function instead of\nadding the function as a property of exports
.\n\n
To test it run the following JavaScript snippet:\n\n
\nvar addon = require('./build/Release/addon');\n\naddon(function(msg){\n console.log(msg); // 'hello world'\n});
\n",
"type": "module",
"displayName": "Callbacks"
},
{
"textRaw": "Object factory",
"name": "object_factory",
"desc": "You can create and return new objects from within a C++ function with this\naddon.cc
pattern, which returns an object with property msg
that echoes\nthe string passed to createObject()
:\n\n
#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n Local<Object> obj = Object::New();\n obj->Set(String::NewSymbol("msg"), args[0]->ToString());\n\n return scope.Close(obj);\n}\n\nvoid Init(Handle<Object> exports, Handle<Object> module) {\n module->Set(String::NewSymbol("exports"),\n FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\nTo test it in JavaScript:\n\n
\nvar addon = require('./build/Release/addon');\n\nvar obj1 = addon('hello');\nvar obj2 = addon('world');\nconsole.log(obj1.msg+' '+obj2.msg); // 'hello world'
\n",
"type": "module",
"displayName": "Object factory"
},
{
"textRaw": "Function factory",
"name": "function_factory",
"desc": "This pattern illustrates how to create and return a JavaScript function that\nwraps a C++ function:\n\n
\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> MyFunction(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n return scope.Close(String::New("hello world"));\n}\n\nHandle<Value> CreateFunction(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);\n Local<Function> fn = tpl->GetFunction();\n\n // omit this to make it anonymous\n fn->SetName(String::NewSymbol("theFunction"));\n\n return scope.Close(fn);\n}\n\nvoid Init(Handle<Object> exports, Handle<Object> module) {\n module->Set(String::NewSymbol("exports"),\n FunctionTemplate::New(CreateFunction)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\nTo test:\n\n
\nvar addon = require('./build/Release/addon');\n\nvar fn = addon();\nconsole.log(fn()); // 'hello world'
\n",
"type": "module",
"displayName": "Function factory"
},
{
"textRaw": "Wrapping C++ objects",
"name": "wrapping_c++_objects",
"desc": "Here we will create a wrapper for a C++ object/class MyObject
that can be\ninstantiated in JavaScript through the new
operator. First prepare the main\nmodule addon.cc
:\n\n
#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nvoid InitAll(Handle<Object> exports) {\n MyObject::Init(exports);\n}\n\nNODE_MODULE(addon, InitAll)
\nThen in myobject.h
make your wrapper inherit from node::ObjectWrap
:\n\n
#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n static void Init(v8::Handle<v8::Object> exports);\n\n private:\n MyObject();\n ~MyObject();\n\n static v8::Handle<v8::Value> New(const v8::Arguments& args);\n static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n double counter_;\n};\n\n#endif
\nAnd in myobject.cc
implement the various methods that you want to expose.\nHere we expose the method plusOne
by adding it to the constructor's\nprototype:\n\n
#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nvoid MyObject::Init(Handle<Object> exports) {\n Isolate* isolate = Isolate::GetCurrent();\n\n // Prepare constructor template\n Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n tpl->SetClassName(String::NewSymbol("MyObject"));\n tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n // Prototype\n tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n FunctionTemplate::New(PlusOne)->GetFunction());\n\n Persistent<Function> constructor\n = Persistent<Function>::New(isolate, tpl->GetFunction());\n\n exports->Set(String::NewSymbol("MyObject"), constructor);\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n MyObject* obj = new MyObject();\n obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n obj->Wrap(args.This());\n\n return args.This();\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n obj->counter_ += 1;\n\n return scope.Close(Number::New(obj->counter_));\n}
\nTest it with:\n\n
\nvar addon = require('./build/Release/addon');\n\nvar obj = new addon.MyObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13
\n",
"type": "module",
"displayName": "Wrapping C++ objects"
},
{
"textRaw": "Factory of wrapped objects",
"name": "factory_of_wrapped_objects",
"desc": "This is useful when you want to be able to create native objects without\nexplicitly instantiating them with the new
operator in JavaScript, e.g.\n\n
var obj = addon.createObject();\n// instead of:\n// var obj = new addon.Object();
\nLet's register our createObject
method in addon.cc
:\n\n
#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n return scope.Close(MyObject::NewInstance(args));\n}\n\nvoid InitAll(Handle<Object> exports, Handle<Object> module) {\n MyObject::Init();\n\n module->Set(String::NewSymbol("exports"),\n FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\nIn myobject.h
we now introduce the static method NewInstance
that takes\ncare of instantiating the object (i.e. it does the job of new
in JavaScript):\n\n
#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n static void Init();\n static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n\n private:\n MyObject();\n ~MyObject();\n\n static v8::Persistent<v8::Function> constructor;\n static v8::Handle<v8::Value> New(const v8::Arguments& args);\n static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n double counter_;\n};\n\n#endif
\nThe implementation is similar to the above in myobject.cc
:\n\n
#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n Isolate* isolate = Isolate::GetCurrent();\n // Prepare constructor template\n Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n tpl->SetClassName(String::NewSymbol("MyObject"));\n tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n // Prototype\n tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n FunctionTemplate::New(PlusOne)->GetFunction());\n\n constructor = Persistent<Function>::New(isolate, tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n MyObject* obj = new MyObject();\n obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n obj->Wrap(args.This());\n\n return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n const unsigned argc = 1;\n Handle<Value> argv[argc] = { args[0] };\n Local<Object> instance = constructor->NewInstance(argc, argv);\n\n return scope.Close(instance);\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n obj->counter_ += 1;\n\n return scope.Close(Number::New(obj->counter_));\n}
\nTest it with:\n\n
\nvar createObject = require('./build/Release/addon');\n\nvar obj = createObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13\n\nvar obj2 = createObject(20);\nconsole.log( obj2.plusOne() ); // 21\nconsole.log( obj2.plusOne() ); // 22\nconsole.log( obj2.plusOne() ); // 23
\n",
"type": "module",
"displayName": "Factory of wrapped objects"
},
{
"textRaw": "Passing wrapped objects around",
"name": "passing_wrapped_objects_around",
"desc": "In addition to wrapping and returning C++ objects, you can pass them around\nby unwrapping them with Node's node::ObjectWrap::Unwrap
helper function.\nIn the following addon.cc
we introduce a function add()
that can take on two\nMyObject
objects:\n\n
#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n return scope.Close(MyObject::NewInstance(args));\n}\n\nHandle<Value> Add(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(\n args[0]->ToObject());\n MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(\n args[1]->ToObject());\n\n double sum = obj1->Val() + obj2->Val();\n return scope.Close(Number::New(sum));\n}\n\nvoid InitAll(Handle<Object> exports) {\n MyObject::Init();\n\n exports->Set(String::NewSymbol("createObject"),\n FunctionTemplate::New(CreateObject)->GetFunction());\n\n exports->Set(String::NewSymbol("add"),\n FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\nTo make things interesting we introduce a public method in myobject.h
so we\ncan probe private values after unwrapping the object:\n\n
#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n static void Init();\n static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n double Val() const { return val_; }\n\n private:\n MyObject();\n ~MyObject();\n\n static v8::Persistent<v8::Function> constructor;\n static v8::Handle<v8::Value> New(const v8::Arguments& args);\n double val_;\n};\n\n#endif
\nThe implementation of myobject.cc
is similar as before:\n\n
#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n Isolate* isolate = Isolate::GetCurrent();\n\n // Prepare constructor template\n Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n tpl->SetClassName(String::NewSymbol("MyObject"));\n tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n constructor = Persistent<Function>::New(isolate, tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n MyObject* obj = new MyObject();\n obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n obj->Wrap(args.This());\n\n return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n Isolate* isolate = Isolate::GetCurrent();\n HandleScope scope(isolate);\n\n const unsigned argc = 1;\n Handle<Value> argv[argc] = { args[0] };\n Local<Object> instance = constructor->NewInstance(argc, argv);\n\n return scope.Close(instance);\n}
\nTest it with:\n\n
\nvar addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject(10);\nvar obj2 = addon.createObject(20);\nvar result = addon.add(obj1, obj2);\n\nconsole.log(result); // 30
\n",
"type": "module",
"displayName": "Passing wrapped objects around"
}
],
"type": "module",
"displayName": "Addon patterns"
}
],
"type": "module",
"displayName": "Addons"
}
]
}