C++ addons
目录
Added in: v0.10.0
Addons are dynamically-linked shared objects written in C++. The
require()
function can load addons as ordinary Node.js modules.
Addons provide an interface between JavaScript and C/C++ libraries.
There are three options for implementing addons: Node-API, nan, or direct use of internal V8, libuv, and Node.js libraries. Unless there is a need for direct access to functionality which is not exposed by Node-API, use Node-API. Refer to C/C++ addons with Node-API for more information on Node-API.
When not using Node-API, implementing addons is complicated, involving knowledge of several components and APIs:
V8: the C++ library Node.js uses to provide the JavaScript implementation. V8 provides the mechanisms for creating objects, calling functions, etc. V8's API is documented mostly in the
v8.h
header file (deps/v8/include/v8.h
in the Node.js source tree), which is also available online.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 threading abstraction similar to POSIX threads for more sophisticated asynchronous addons that need to move beyond the standard event loop. Addon authors should avoid blocking the event loop with I/O or other time-intensive tasks by offloading work via libuv to non-blocking system operations, worker threads, or a custom use of libuv threads.
Internal Node.js libraries. Node.js itself exports C++ APIs that addons can use, the most important of which is the
node::ObjectWrap
class.Node.js includes other statically linked libraries including OpenSSL. These other libraries are located in the
deps/
directory in the Node.js source tree. Only the libuv, OpenSSL, V8, and zlib symbols are purposefully re-exported by Node.js and may be used to various extents by addons. See Linking to libraries included with Node.js for additional information.
All of the following examples are available for download and may be used as the starting-point for an addon.
Hello world
This "Hello world" example is a simple addon, written in C++, that is the equivalent of the following JavaScript code:
JS
First, create the file hello.cc
:
CPP
All Node.js addons must export an initialization function following the pattern:
CPP
There is no semi-colon after NODE_MODULE
as it's not a function (see
node.h
).
The module_name
must match the filename of the final binary (excluding
the .node
suffix).
In the hello.cc
example, then, the initialization function is Initialize
and the addon module name is addon
.
When building addons with node-gyp
, using the macro NODE_GYP_MODULE_NAME
as
the first parameter of NODE_MODULE()
will ensure that the name of the final
binary will be passed to NODE_MODULE()
.
Context-aware addons
There are environments in which Node.js addons may need to be loaded multiple
times in multiple contexts. For example, the Electron runtime runs multiple
instances of Node.js in a single process. Each instance will have its own
require()
cache, and thus each instance will need a native addon to behave
correctly when loaded via require()
. This means that the addon
must support multiple initializations.
A context-aware addon can be constructed by using the macro
NODE_MODULE_INITIALIZER
, which expands to the name of a function which Node.js
will expect to find when it loads an addon. An addon can thus be initialized as
in the following example:
CPP
Another option is to use the macro NODE_MODULE_INIT()
, which will also
construct a context-aware addon. Unlike NODE_MODULE()
, which is used to
construct an addon around a given addon initializer function,
NODE_MODULE_INIT()
serves as the declaration of such an initializer to be
followed by a function body.
The following three variables may be used inside the function body following an
invocation of NODE_MODULE_INIT()
:
Local<Object> exports
,Local<Value> module
, andLocal<Context> context
The choice to build a context-aware addon carries with it the responsibility of carefully managing global static data. Since the addon may be loaded multiple times, potentially even from different threads, any global static data stored in the addon must be properly protected, and must not contain any persistent references to JavaScript objects. The reason for this is that JavaScript objects are only valid in one context, and will likely cause a crash when accessed from the wrong context or from a different thread than the one on which they were created.
The context-aware addon can be structured to avoid global static data by performing the following steps:
- Define a class which will hold per-addon-instance data and which has a static
member of the formCPP
- Heap-allocate an instance of this class in the addon initializer. This can be
accomplished using the
new
keyword. - Call
node::AddEnvironmentCleanupHook()
, passing it the above-created instance and a pointer toDeleteInstance()
. This will ensure the instance is deleted when the environment is torn down. - Store the instance of the class in a
v8::External
, and - Pass the
v8::External
to all methods exposed to JavaScript by passing it tov8::FunctionTemplate::New()
orv8::Function::New()
which creates the native-backed JavaScript functions. The third parameter ofv8::FunctionTemplate::New()
orv8::Function::New()
accepts thev8::External
and makes it available in the native callback using thev8::FunctionCallbackInfo::Data()
method.
This will ensure that the per-addon-instance data reaches each binding that can be called from JavaScript. The per-addon-instance data must also be passed into any asynchronous callbacks the addon may create.
The following example illustrates the implementation of a context-aware addon:
CPP
Worker support
In order to be loaded from multiple Node.js environments, such as a main thread and a Worker thread, an add-on needs to either:
- Be an Node-API addon, or
- Be declared as context-aware using
NODE_MODULE_INIT()
as described above
In order to support Worker
threads, addons need to clean up any resources
they may have allocated when such a thread exists. This can be achieved through
the usage of the AddEnvironmentCleanupHook()
function:
CPP
This function adds a hook that will run before a given Node.js instance shuts
down. If necessary, such hooks can be removed before they are run using
RemoveEnvironmentCleanupHook()
, which has the same signature. Callbacks are
run in last-in first-out order.
If necessary, there is an additional pair of AddEnvironmentCleanupHook()
and RemoveEnvironmentCleanupHook()
overloads, where the cleanup hook takes a
callback function. This can be used for shutting down asynchronous resources,
such as any libuv handles registered by the addon.
The following addon.cc
uses AddEnvironmentCleanupHook
:
CPP
Test in JavaScript by running:
JS
Building
Once the source code has been written, it must be compiled into the binary
addon.node
file. To do so, create a file called binding.gyp
in the
top-level of the project describing the build configuration of the module
using a JSON-like format. This file is used by node-gyp, a tool written
specifically to compile Node.js addons.
JSON
A version of the node-gyp
utility is bundled and distributed with
Node.js as part of npm
. This version is not made directly available for
developers to use and is intended only to support the ability to use the
npm install
command to compile and install addons. Developers who wish to
use node-gyp
directly can install it using the command
npm install -g node-gyp
. See the node-gyp
installation instructions for
more information, including platform-specific requirements.
Once the binding.gyp
file has been created, use node-gyp configure
to
generate the appropriate project build files for the current platform. This
will generate either a Makefile
(on Unix platforms) or a vcxproj
file
(on Windows) in the build/
directory.
Next, invoke the node-gyp build
command to generate the compiled addon.node
file. This will be put into the build/Release/
directory.
When using npm install
to install a Node.js addon, npm uses its own bundled
version of node-gyp
to perform this same set of actions, generating a
compiled version of the addon for the user's platform on demand.
Once built, the binary addon can be used from within Node.js by pointing
require()
to the built addon.node
module:
JS
Because the exact path to the compiled addon binary can vary depending on how
it is compiled (i.e. sometimes it may be in ./build/Debug/
), addons can use
the bindings package to load the compiled module.
While the bindings
package implementation is more sophisticated in how it
locates addon modules, it is essentially using a try…catch
pattern similar to:
JS
Linking to libraries included with Node.js
Node.js uses 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
#include <...>
statements (e.g. #include <v8.h>
) and node-gyp
will locate
the appropriate headers automatically. However, there are a few caveats to be
aware of:
When
node-gyp
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 only the Node.js headers are downloaded, then only the symbols exported by Node.js will be available.node-gyp
can be run using the--nodedir
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 .node
(as opposed
to .dll
or .so
). The require()
function is written to look for
files with the .node
file extension and initialize those as dynamically-linked
libraries.
When calling require()
, the .node
extension can usually be
omitted and Node.js will still find and initialize the addon. One caveat,
however, is that Node.js will first attempt to locate and load modules or
JavaScript files that happen to share the same base name. For instance, if
there is a file addon.js
in the same directory as the binary addon.node
,
then require('addon')
will give precedence to the addon.js
file
and load it instead.
Native abstractions for Node.js
Each of the examples illustrated in this document directly use the Node.js and V8 APIs for implementing addons. The V8 API can, and has, changed dramatically from one V8 release to the next (and one major Node.js release to the next). With each change, addons may need to be updated and recompiled in order to continue functioning. The Node.js release schedule is designed to minimize the frequency and impact of such changes but there is little that Node.js can do to ensure stability of the V8 APIs.
The Native Abstractions for Node.js (or nan
) provide a set of tools that
addon developers are recommended to use to keep compatibility between past and
future releases of V8 and Node.js. See the nan
examples for an
illustration of how it can be used.
Node-API
Node-API is an API for building native addons. It is independent from the underlying JavaScript runtime (e.g. V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate addons from changes in the underlying JavaScript engine and allow modules compiled for one version to run on later versions of Node.js without recompilation. Addons are built/packaged with the same approach/tools outlined in this document (node-gyp, etc.). The only difference is the set of APIs that are used by the native code. Instead of using the V8 or Native Abstractions for Node.js APIs, the functions available in the Node-API are used.
Creating and maintaining an addon that benefits from the ABI stability provided by Node-API carries with it certain implementation considerations.
To use Node-API in the above "Hello world" example, replace the content of
hello.cc
with the following. All other instructions remain the same.
CPP
The functions available and how to use them are documented in C/C++ addons with Node-API.
Addon examples
Following are some example addons intended to help developers get started. The examples use the V8 APIs. Refer to the online V8 reference for help with the various V8 calls, and V8's Embedder's Guide for an explanation of several concepts used such as handles, scopes, function templates, etc.
Each of these examples using the following binding.gyp
file:
JSON
In cases where there is more than one .cc
file, simply add the additional
filename to the sources
array:
JSON
Once the binding.gyp
file is ready, the example addons can be configured and
built using node-gyp
:
BASH
Function arguments
Addons will typically expose objects and functions that can be accessed from JavaScript running within Node.js. When functions are invoked from JavaScript, the input arguments and return value must be mapped to and from the C/C++ code.
The following example illustrates how to read function arguments passed from JavaScript and how to return a result:
CPP
Once compiled, the example addon can be required and used from within Node.js:
JS
Callbacks
It is common practice within addons to pass JavaScript functions to a C++ function and execute them from there. The following example illustrates how to invoke such callbacks:
CPP
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:
JS
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 msg
that echoes the string passed to createObject()
:
CPP
To test it in JavaScript:
JS
Function factory
Another common scenario is creating JavaScript functions that wrap C++ functions and returning those back to JavaScript:
CPP
To test:
JS
Wrapping C++ objects
It is also possible to wrap C++ objects/classes in a way that allows new
instances to be created using the JavaScript new
operator:
CPP
Then, in myobject.h
, the wrapper class inherits from node::ObjectWrap
:
CPP
In myobject.cc
, implement the various methods that are to be exposed.
Below, the method plusOne()
is exposed by adding it to the constructor's
prototype:
CPP
To build this example, the myobject.cc
file must be added to the
binding.gyp
:
JSON
Test it with:
JS
The destructor for a wrapper object will run when the object is garbage-collected. For destructor testing, there are command-line flags that can be used to make it possible to force garbage collection. These flags are provided by the underlying V8 JavaScript engine. They are subject to change or removal at any time. They are not documented by Node.js or V8, and they should never be used outside of testing.
During shutdown of the process or worker threads destructors are not called by the JS engine. Therefore it's the responsibility of the user to track these objects and ensure proper destruction to avoid resource leaks.
Factory of wrapped objects
Alternatively, it is possible to use a factory pattern to avoid explicitly
creating object instances using the JavaScript new
operator:
JS
First, the createObject()
method is implemented in addon.cc
:
CPP
In myobject.h
, the static method NewInstance()
is added to handle
instantiating the object. This method takes the place of using new
in
JavaScript:
CPP
The implementation in myobject.cc
is similar to the previous example:
CPP
Once again, to build this example, the myobject.cc
file must be added to the
binding.gyp
:
JSON
Test it with:
JS
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
node::ObjectWrap::Unwrap
. The following examples shows a function add()
that can take two MyObject
objects as input arguments:
CPP
In myobject.h
, a new public method is added to allow access to private values
after unwrapping the object.
CPP
The implementation of myobject.cc
is similar to before:
CPP
Test it with:
JS