https://nodejs.org/docs/latest/api/addons.html
Node.js Addons are dynamically-linked shared objects, written in C or C++, that can be loaded into Node.js using the
At the moment, the method for implementing Addons is rather complicated, involving knowledge of several components and APIs :
-
V8: the C++ library Node.js currently uses to provide the JavaS
cript implementation. V8 provides the mechanisms for creating objects, calling functions, etc. V8's API is documented mostly in the de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >v8.h de> header file ( de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >deps/v8/include/v8.h de> in the Node.js source tree), which is also available on line. -
libuv: The C library that implements the Node.js event loop, its worker threads and all of the asynchronous behaviors of the platform. It also serves as a cross-platform abstraction library, giving easy, POSIX-like access across all major operating systems to many common system tasks, such as interacting with the filesystem, sockets, timers and system events. libuv also provides a pthreads-like threading abstraction that may be used to power more sophisticated asynchronous Addons that need to move beyond the standard event loop. Addon authors are encouraged to think about how to avoid blocking the event loop with I/O or other time-intensive tasks by off-loading work via libuv to non-blocking system operations, worker threads or a custom use of libuv's threads.
-
Internal Node.js libraries. Node.js itself exports a number of C/C++ APIs that Addons can use — the most imp
ortant of which is the de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >node::ObjectWrap de> class. -
Node.js includes a number of other statically linked libraries including OpenSSL. These other libraries are located in the
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >deps/ de> directory in the Node.js source tree. On ly the V8 and OpenSSL symbols are purposefully re-exported by Node.js and may be used to various extents by Addons. See Linking to Node.js' own dependencies for additional information.
All of the following examples are available for download and may be used as a starting-point for your own Addon.
Hello world#
This "Hello world" example is a simple Addon, written in C++, that is the equivalent of the following JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >module.exports.hello = () => 'world'; de>
First, create the file
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// hello.cc #include <node.h> namespace demo { using v8::FunctionCallbackInfo; using v8::Isolate; using v8::Local; using v8::Object; using v8::String; using v8::Value; void Method(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", Method); } NODE_MODULE(addon, init) } // namespace demo de>
Note that all Node.js Addons must export an initialization function following the pattern:
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >void Initialize(Local<Object> exports); NODE_MODULE(module_name, Initialize) de>
There is no semi-colon after
The
In the
Building#
On
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >{ "targets": [ { "target_name": "addon", "sources": [ "hello.cc" ] } ] } de>
Note: A version of the
On
Next, invoke the
When using
On
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// hello.js const addon = require('./build/Release/addon'); console.log(addon.hello()); // Prints: 'world' de>
Please see the examples below for further information or https://github.com/arturadib/node-qt for an example in production.
Because the exact path to the compiled Addon binary can vary depending on how it is compiled (i.e. sometimes it may be in
Note that while the
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >try { return require('./build/Release/addon.node'); } catch (err) { return require('./build/Debug/addon.node'); } de>
Linking to Node.js' own dependencies#
Node.js uses a number of statically linked libraries such as V8, libuv and OpenSSL. All Addons are required to link to V8 and may link to any of the other dependencies as well. Typically, this is as simple as including the appropriate
-
When
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >node-gyp de> runs, it will detect the specific release version of Node.js and download either the full source tarball or just the headers. If the full source is downloaded, Addons will have complete access to the full set of Node.js dependencies. However, if on ly the Node.js headers are downloaded, then on ly the symbols exported by Node.js will be available. -
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >node-gyp de> can be run using the de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >--nodedir de> flag pointing at a local Node.js source image. Using this option, the Addon will have access to the full set of dependencies.
Loading Addons using require()#
The filename extension of the compiled Addon binary is
When calling
Native Abstractions for Node.js#
Each of the examples illustrated in this document make direct use of the Node.js and V8 APIs for implementing Addons. It is imp
The Native Abstractions for Node.js (or
Addon examples#
Following are some example Addons intended to help developers get started. The examples make use of the V8 APIs. Refer to the on
Each of these examples using the following
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >{ "targets": [ { "target_name": "addon", "sources": [ "addon.cc" ] } ] } de>
In cases where there is more than on
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >"sources": ["addon.cc", "myexample.cc"] de>
On
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >$ node-gyp configure build de>
Function arguments#
Addons will typically expose objects and functions that can be accessed from JavaS
The following example illustrates how to read function arguments passed from JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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 JavaS cript isolate->ThrowException(Exception::TypeError( String::NewFromUtf8(isolate, "Wrong number of arguments"))); return; } // Check the argument types if (!args[0]->IsNumber() || !args[1]->IsNumber()) { isolate->ThrowException(Exception::TypeError( String::NewFromUtf8(isolate, "Wrong arguments"))); return; } // Perform the operation double value = args[0]->NumberValue() + args[1]->NumberValue(); 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(addon, Init) } // namespace demo de>
On
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// test.js const addon = require('./build/Release/addon'); console.log('This should be eight:', addon.add(3, 5)); de>
Callbacks#
It is common practice within Addons to pass JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// addon.cc #include <node.h> namespace demo { 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<Function> cb = Local<Function>::Cast(args[0]); const unsigned argc = 1; Local<Value> argv[argc] = { String::NewFromUtf8(isolate, "hello world") }; cb->Call(Null(isolate), argc, argv); } void Init(Local<Object> exports, Local<Object> module) { NODE_SET_METHOD(module, "exports", RunCallback); } NODE_MODULE(addon, Init) } // namespace demo de>
Note that this example uses a two-argument form of
To test it, run the following JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// test.js const addon = require('./build/Release/addon'); addon((msg) => { console.log(msg); // Prints: 'hello world' }); de>
Note that, in this example, the callback function is invoked synchronously.
Object factory#
Addons can create and return new objects from within a C++ function as illustrated in the following example. An object is created and returned with a property
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// addon.cc #include <node.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) { Isolate* isolate = args.GetIsolate(); Local<Object> obj = Object::New(isolate); obj->Set(String::NewFromUtf8(isolate, "msg"), args[0]->ToString()); args.GetReturnValue().Set(obj); } void Init(Local<Object> exports, Local<Object> module) { NODE_SET_METHOD(module, "exports", CreateObject); } NODE_MODULE(addon, Init) } // namespace demo de>
To test it in JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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' de>
Function factory#
Another common scenario is creating JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// addon.cc #include <node.h> namespace demo { 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")); } void CreateFunction(const FunctionCallbackInfo<Value>& args) { Isolate* isolate = args.GetIsolate(); Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, MyFunction); Local<Function> fn = tpl->GetFunction(); // omit this to make it anonymous fn->SetName(String::NewFromUtf8(isolate, "theFunction")); args.GetReturnValue().Set(fn); } void Init(Local<Object> exports, Local<Object> module) { NODE_SET_METHOD(module, "exports", CreateFunction); } NODE_MODULE(addon, Init) } // namespace demo de>
To test:
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// test.js const addon = require('./build/Release/addon'); const fn = addon(); console.log(fn()); // Prints: 'hello world' de>
Wrapping C++ objects#
It is also possible to wrap C++ objects/classes in a way that allows new instances to be created using the JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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(addon, InitAll) } // namespace demo de>
Then, in
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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); static v8::Persistent<v8::Function> constructor; double value_; }; } // namespace demo #endif de>
In
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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::Persistent; using v8::String; using v8::Value; Persistent<Function> MyObject::constructor; MyObject::MyObject(double value) : value_(value) { } MyObject::~MyObject() { } void MyObject::Init(Local<Object> exports) { Isolate* isolate = exports->GetIsolate(); // Prepare constructor template Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New); tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject")); tpl->InstanceTemplate()->SetInternalFieldCount(1); // Prototype NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne); constructor.Reset(isolate, tpl->GetFunction()); exports->Set(String::NewFromUtf8(isolate, "MyObject"), tpl->GetFunction()); } void MyObject::New(const FunctionCallbackInfo<Value>& args) { Isolate* isolate = args.GetIsolate(); if (args.IsConstructCall()) { // Invoked as constructor: `new MyObject(...)` double value = args[0]->IsUndefined() ? 0 : args[0]->NumberValue(); 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<Context> context = isolate->GetCurrentContext(); Local<Function> cons = Local<Function>::New(isolate, constructor); 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.Holder()); obj->value_ += 1; args.GetReturnValue().Set(Number::New(isolate, obj->value_)); } } // namespace demo de>
To build this example, the
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >{ "targets": [ { "target_name": "addon", "sources": [ "addon.cc", "myobject.cc" ] } ] } de>
Test it with:
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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 de>
Factory of wrapped objects#
Alternatively, it is possible to use a factory pattern to avoid explicitly creating object instances using the JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >const obj = addon.createObject(); // instead of: // const obj = new addon.Object(); de>
First, the
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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(exports->GetIsolate()); NODE_SET_METHOD(module, "exports", CreateObject); } NODE_MODULE(addon, InitAll) } // namespace demo de>
In
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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::Isolate* isolate); 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::Persistent<v8::Function> constructor; double value_; }; } // namespace demo #endif de>
The implementation in
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// myobject.cc #include <node.h> #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::Persistent; using v8::String; using v8::Value; Persistent<Function> MyObject::constructor; MyObject::MyObject(double value) : value_(value) { } MyObject::~MyObject() { } void MyObject::Init(Isolate* isolate) { // Prepare constructor template Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New); tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject")); tpl->InstanceTemplate()->SetInternalFieldCount(1); // Prototype NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne); constructor.Reset(isolate, tpl->GetFunction()); } void MyObject::New(const FunctionCallbackInfo<Value>& args) { Isolate* isolate = args.GetIsolate(); if (args.IsConstructCall()) { // Invoked as constructor: `new MyObject(...)` double value = args[0]->IsUndefined() ? 0 : args[0]->NumberValue(); 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<Context> context = isolate->GetCurrentContext(); 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.Holder()); obj->value_ += 1; args.GetReturnValue().Set(Number::New(isolate, obj->value_)); } } // namespace demo de>
On
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >{ "targets": [ { "target_name": "addon", "sources": [ "addon.cc", "myobject.cc" ] } ] } de>
Test it with:
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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 de>
Passing wrapped objects around#
In addition to wrapping and returning C++ objects, it is possible to pass wrapped objects around by unwrapping them with the Node.js helper function
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// addon.cc #include <node.h> #include <node_object_wrap.h> #include "myobject.h" namespace demo { 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(); MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>( args[0]->ToObject()); MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>( args[1]->ToObject()); double sum = obj1->value() + obj2->value(); args.GetReturnValue().Set(Number::New(isolate, sum)); } void InitAll(Local<Object> exports) { MyObject::Init(exports->GetIsolate()); NODE_SET_METHOD(exports, "createObject", CreateObject); NODE_SET_METHOD(exports, "add", Add); } NODE_MODULE(addon, InitAll) } // namespace demo de>
In
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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::Isolate* isolate); 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::Persistent<v8::Function> constructor; double value_; }; } // namespace demo #endif de>
The implementation of
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// myobject.cc #include <node.h> #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::Object; using v8::Persistent; using v8::String; using v8::Value; Persistent<Function> MyObject::constructor; MyObject::MyObject(double value) : value_(value) { } MyObject::~MyObject() { } void MyObject::Init(Isolate* isolate) { // Prepare constructor template Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New); tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject")); tpl->InstanceTemplate()->SetInternalFieldCount(1); constructor.Reset(isolate, tpl->GetFunction()); } void MyObject::New(const FunctionCallbackInfo<Value>& args) { Isolate* isolate = args.GetIsolate(); if (args.IsConstructCall()) { // Invoked as constructor: `new MyObject(...)` double value = args[0]->IsUndefined() ? 0 : args[0]->NumberValue(); 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<Context> context = isolate->GetCurrentContext(); 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 de>
Test it with:
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// 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 de>
AtExit hooks#
An "AtExit" hook is a function that is invoked after the Node.js event loop has ended but before the JavaS
void AtExit(callback, args)#
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >callback de>: de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >void (*)(void*) de> - A pointer to the function to call at exit. de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >args de>: de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0.1em 0.3em; font-size: 0.9em; color: rgb(4, 4, 4); border-radius: 2px; background-color: rgb(242, 242, 242);" >void* de> - A pointer to pass to the callback at exit.
Registers exit hooks that run after the event loop has ended but before the VM is killed.
AtExit takes two parameters: a pointer to a callback function to run at exit, and a pointer to untyped context da
Callbacks are run in last-in first-out order.
The following
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// addon.cc #undef NDEBUG #include <assert.h> #include <stdlib.h> #include <node.h> namespace demo { using node::AtExit; using v8::HandleScope; using v8::Isolate; using v8::Local; using v8::Object; static char cookie[] = "yum yum"; static int at_exit_cb1_called = 0; static int at_exit_cb2_called = 0; static void at_exit_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()); at_exit_cb1_called++; } static void at_exit_cb2(void* arg) { assert(arg == static_cast<void*>(cookie)); at_exit_cb2_called++; } static void sanity_check(void*) { assert(at_exit_cb1_called == 1); assert(at_exit_cb2_called == 2); } void init(Local<Object> exports) { AtExit(sanity_check); AtExit(at_exit_cb2, cookie); AtExit(at_exit_cb2, cookie); AtExit(at_exit_cb1, exports->GetIsolate()); } NODE_MODULE(addon, init); } // namespace demo de>
Test in JavaS
de style="line-height: 1.5em; font-family: Monaco, Consolas, 'Lucida Console', monospace; margin: 0px; padding: 0px; font-size: 0.8em; color: rgb(4, 4, 4); border-radius: 2px;" >// test.js const addon = require('./build/Release/addon'); de>