A header file filled with macro and utility goodness for making add-on development for Node.js easier across versions 0.8, 0.10 and 0.11, and eventually 0.12.
Current version: 0.8.0 (See nan.h for complete ChangeLog)
Thanks to the crazy changes in V8 (and some in Node core), keeping native addons compiling happily across versions, particularly 0.10 to 0.11/0.12, is a minor nightmare. The goal of this project is to store all logic necessary to develop native Node.js addons without having to inspect NODE_MODULE_VERSION
and get yourself into a macro-tangle.
This project also contains some helper utilities that make addon development a bit more pleasant.
Two new functions have been introduced to replace the functionality that's been provided by NanFromV8String
until now. NanCString has sensible defaults so it's super easy to fetch a null-terminated c-style string out of a v8::String
. NanFromV8String
is still around and has defaults that allow you to pass a single handle to fetch a char*
while NanRawString
requires a little more attention to arguments.
The version of V8 that's shipping with Node 0.11.9+ has changed the signature for new Local
s to: v8::Local<T>::New(isolate, value)
, i.e. introducing the isolate
argument and therefore breaking all new Local
declarations for previous versions. NAN 0.6+ now includes a NanNewLocal<T>(value)
that can be used in place to work around this incompatibility and maintain compatibility with 0.8->0.11.9+ (minus a few early 0.11 releases).
For example, if you wanted to return a null
on a callback you will have to change the argument from v8::Local<v8::Value>::New(v8::Null())
to NanNewLocal<v8::Value>(v8::Null())
.
Inclusion of NAN in a project's binding.gyp is now greatly simplified. You can now just use "<!(node -e \"require('nan')\")"
in your "include_dirs"
, see example below (note Windows needs the quoting around require
to be just right: "require('nan')"
with appropriate \
escaping).
Simply add NAN as a dependency in the package.json of your Node addon:
$ npm install --save nan
Pull in the path to NAN in your binding.gyp so that you can use #include "nan.h"
in your .cpp files:
"include_dirs" : [
"<!(node -e \"require('nan')\")"
]
This works like a -I<path-to-NAN>
when compiling your addon.
See LevelDOWN for a full example of NAN in use.
For a simpler example, see the async pi estimation example in the examples directory for full code and an explanation of what this Monte Carlo Pi estimation example does. Below are just some parts of the full example that illustrate the use of NAN.
Compare to the current 0.10 version of this example, found in the node-addon-examples repository and also a 0.11 version of the same found here.
Note that there is no embedded version sniffing going on here and also the async work is made much simpler, see below for details on the NanAsyncWorker
class.
// addon.cc
#include <node.h>
#include "nan.h"
// ...
using namespace v8;
void InitAll(Handle<Object> exports) {
exports->Set(NanSymbol("calculateSync"),
FunctionTemplate::New(CalculateSync)->GetFunction());
exports->Set(NanSymbol("calculateAsync"),
FunctionTemplate::New(CalculateAsync)->GetFunction());
}
NODE_MODULE(addon, InitAll)
// sync.h
#include <node.h>
#include "nan.h"
NAN_METHOD(CalculateSync);
// sync.cc
#include <node.h>
#include "nan.h"
#include "sync.h"
// ...
using namespace v8;
// Simple synchronous access to the `Estimate()` function
NAN_METHOD(CalculateSync) {
NanScope();
// expect a number as the first argument
int points = args[0]->Uint32Value();
double est = Estimate(points);
NanReturnValue(Number::New(est));
}
// async.cc
#include <node.h>
#include "nan.h"
#include "async.h"
// ...
using namespace v8;
class PiWorker : public NanAsyncWorker {
public:
PiWorker(NanCallback *callback, int points)
: NanAsyncWorker(callback), points(points) {}
~PiWorker() {}
// Executed inside the worker-thread.
// It is not safe to access V8, or V8 data structures
// here, so everything we need for input and output
// should go on `this`.
void Execute () {
estimate = Estimate(points);
}
// Executed when the async work is complete
// this function will be run inside the main event loop
// so it is safe to use V8 again
void HandleOKCallback () {
NanScope();
Local<Value> argv[] = {
Local<Value>::New(Null())
, Number::New(estimate)
};
callback->Call(2, argv);
};
private:
int points;
double estimate;
};
// Asynchronous access to the `Estimate()` function
NAN_METHOD(CalculateAsync) {
NanScope();
int points = args[0]->Uint32Value();
NanCallback *callback = new NanCallback(args[1].As<Function>());
NanAsyncQueueWorker(new PiWorker(callback, points));
NanReturnUndefined();
}
NAN_METHOD
NAN_GETTER
NAN_SETTER
NAN_PROPERTY_GETTER
NAN_PROPERTY_SETTER
NAN_PROPERTY_ENUMERATOR
NAN_PROPERTY_DELETER
NAN_PROPERTY_QUERY
NAN_INDEX_GETTER
NAN_INDEX_SETTER
NAN_INDEX_ENUMERATOR
NAN_INDEX_DELETER
NAN_INDEX_QUERY
NAN_WEAK_CALLBACK
NAN_DEPRECATED
NAN_INLINE
NanNewLocal
NanReturnValue
NanReturnUndefined
NanReturnNull
NanReturnEmptyString
NanScope
NanLocker
NanUnlocker
NanGetInternalFieldPointer
NanSetInternalFieldPointer
NanObjectWrapHandle
NanMakeWeak
NanSymbol
NanGetPointerSafe
NanSetPointerSafe
NanRawString
NanCString
NanFromV8String
NanBooleanOptionValue
NanUInt32OptionValue
NanError
,NanTypeError
,NanRangeError
NanThrowError
,NanThrowTypeError
,NanThrowRangeError
,NanThrowError(Handle)
,NanThrowError(Handle, int)
NanNewBufferHandle(char *, size_t, FreeCallback, void *)
,NanNewBufferHandle(char *, uint32_t)
,NanNewBufferHandle(uint32_t)
NanBufferUse(char *, uint32_t)
NanNewContextHandle
NanHasInstance
NanPersistentToLocal
NanDisposePersistent
NanAssignPersistent
NanInitPersistent
NanCallback
NanAsyncWorker
NanAsyncQueueWorker
Use NAN_METHOD
to define your V8 accessible methods:
// .h:
class Foo : public node::ObjectWrap {
...
static NAN_METHOD(Bar);
static NAN_METHOD(Baz);
}
// .cc:
NAN_METHOD(Foo::Bar) {
...
}
NAN_METHOD(Foo::Baz) {
...
}
The reason for this macro is because of the method signature change in 0.11:
// 0.10 and below:
Handle<Value> name(const Arguments& args)
// 0.11 and above
void name(const FunctionCallbackInfo<Value>& args)
The introduction of FunctionCallbackInfo
brings additional complications:
Use NAN_GETTER
to declare your V8 accessible getters. You get a Local<String>
property
and an appropriately typed args
object that can act like the args
argument to a NAN_METHOD
call.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_GETTER
.
Use NAN_SETTER
to declare your V8 accessible setters. Same as NAN_GETTER
but you also get a Local<Value>
value
object to work with.
Use NAN_PROPERTY_GETTER
to declare your V8 accessible property getters. You get a Local<String>
property
and an appropriately typed args
object that can act similar to the args
argument to a NAN_METHOD
call.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_PROPERTY_GETTER
.
Use NAN_PROPERTY_SETTER
to declare your V8 accessible property setters. Same as NAN_PROPERTY_GETTER
but you also get a Local<Value>
value
object to work with.
Use NAN_PROPERTY_ENUMERATOR
to declare your V8 accessible property enumerators. You get an appropriately typed args
object like the args
argument to a NAN_PROPERTY_GETTER
call.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_PROPERTY_ENUMERATOR
.
Use NAN_PROPERTY_DELETER
to declare your V8 accessible property deleters. Same as NAN_PROPERTY_GETTER
.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_PROPERTY_DELETER
.
Use NAN_PROPERTY_QUERY
to declare your V8 accessible property queries. Same as NAN_PROPERTY_GETTER
.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_PROPERTY_QUERY
.
Use NAN_INDEX_GETTER
to declare your V8 accessible index getters. You get a uint32_t
index
and an appropriately typed args
object that can act similar to the args
argument to a NAN_METHOD
call.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_INDEX_GETTER
.
Use NAN_INDEX_SETTER
to declare your V8 accessible index setters. Same as NAN_INDEX_GETTER
but you also get a Local<Value>
value
object to work with.
Use NAN_INDEX_ENUMERATOR
to declare your V8 accessible index enumerators. You get an appropriately typed args
object like the args
argument to a NAN_INDEX_GETTER
call.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_INDEX_ENUMERATOR
.
Use NAN_INDEX_DELETER
to declare your V8 accessible index deleters. Same as NAN_INDEX_GETTER
.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_INDEX_DELETER
.
Use NAN_INDEX_QUERY
to declare your V8 accessible index queries. Same as NAN_INDEX_GETTER
.
You can use NanReturnNull()
, NanReturnEmptyString()
, NanReturnUndefined()
and NanReturnValue()
in a NAN_INDEX_QUERY
.
Use NAN_WEAK_CALLBACK
to declare your V8 WeakReference callbacks. There is an object argument accessible through NAN_WEAK_CALLBACK_OBJECT
. The type
argument gives the type of the data
argument, accessible through NAN_WEAK_CALLBACK_DATA(type)
.
static NAN_WEAK_CALLBACK(BufferReference*, WeakCheck) {
if (NAN_WEAK_CALLBACK_DATA(BufferReference*)->noLongerNeeded_) {
delete NAN_WEAK_CALLBACK_DATA(BufferReference*);
} else {
// Still in use, revive, prevent GC
NanMakeWeak(NAN_WEAK_CALLBACK_OBJECT, NAN_WEAK_CALLBACK_DATA(BufferReference*), &WeakCheck);
}
}
Declares a function as deprecated. Identical to V8_DEPRECATED
.
static NAN_DEPRECATED(NAN_METHOD(foo)) {
...
}
Inlines a function. Identical to V8_INLINE
.
static NAN_INLINE(int foo(int bar)) {
...
}
Use NanNewLocal
in place of v8::Local<T>::New(...)
as this function
requires an isolate
argument in recent versions of V8 but not in older versions.
NanNewLocal<v8::Value>(v8::Null())
Use NanReturnValue
when you want to return a value from your V8 accessible method:
NAN_METHOD(Foo::Bar) {
...
NanReturnValue(String::New("FooBar!"));
}
No return
statement required.
Use NanReturnUndefined
when you don't want to return anything from your V8 accessible method:
NAN_METHOD(Foo::Baz) {
...
NanReturnUndefined();
}
Use NanReturnNull
when you want to return Null
from your V8 accessible method:
NAN_METHOD(Foo::Baz) {
...
NanReturnNull();
}
Use NanReturnEmptyString
when you want to return an empty String
from your V8 accessible method:
NAN_METHOD(Foo::Baz) {
...
NanReturnEmptyString();
}
The introduction of isolate
references for many V8 calls in Node 0.11 makes NanScope()
necessary, use it in place of HandleScope scope
:
NAN_METHOD(Foo::Bar) {
NanScope();
NanReturnValue(String::New("FooBar!"));
}
The introduction of isolate
references for many V8 calls in Node 0.11 makes NanLocker()
necessary, use it in place of Locker locker
:
NAN_METHOD(Foo::Bar) {
NanLocker();
...
NanUnlocker();
}
The introduction of isolate
references for many V8 calls in Node 0.11 makes NanUnlocker()
necessary, use it in place of Unlocker unlocker
:
NAN_METHOD(Foo::Bar) {
NanLocker();
...
NanUnlocker();
}
Gets a pointer to the internal field with at index
from a V8 Object
handle.
Local<Object> obj;
...
NanGetInternalFieldPointer(obj, 0);
Sets the value of the internal field at index
on a V8 Object
handle.
static Persistent<Function> dataWrapperCtor;
...
Local<Object> wrapper = NanPersistentToLocal(dataWrapperCtor)->NewInstance();
NanSetInternalFieldPointer(wrapper, 0, this);
When you want to fetch the V8 object handle from a native object you've wrapped with Node's ObjectWrap
, you should use NanObjectWrapHandle
:
NanObjectWrapHandle(iterator)->Get(String::NewSymbol("end"))
Make a persistent reference weak.
This isn't strictly about compatibility, it's just an easier way to create string symbol objects (i.e. String::NewSymbol(x)
), for getting and setting object properties, or names of objects.
bool foo = false;
if (obj->Has(NanSymbol("foo")))
foo = optionsObj->Get(NanSymbol("foo"))->BooleanValue()
A helper for getting values from optional pointers. If the pointer is NULL
, the function returns the optional default value, which defaults to 0
. Otherwise, the function returns the value the pointer points to.
char *plugh(uint32_t *optional) {
char res[] = "xyzzy";
uint32_t param = NanGetPointerSafe<uint32_t>(optional, 0x1337);
switch (param) {
...
}
NanSetPointerSafe<uint32_t>(optional, 0xDEADBEEF);
}
A helper for setting optional argument pointers. If the pointer is NULL
, the function simply return false
. Otherwise, the value is assigned to the variable the pointer points to.
const char *plugh(size_t *outputsize) {
char res[] = "xyzzy";
if !(NanSetPointerSafe<size_t>(outputsize, strlen(res) + 1)) {
...
}
...
}
When you want to convert a V8 String
to a char*
buffer, use NanRawString
. You have to supply an encoding as well as a pointer to a variable that will be assigned the number of bytes in the returned string. It is also possible to supply a buffer and its length to the function in order not to have a new buffer allocated. The final argument allows setting String::WriteOptions
.
Just remember that you'll end up with an object that you'll need to delete[]
at some point unless you supply your own buffer:
size_t count;
void* decoded = NanRawString(args[1], Nan::BASE64, &count, NULL, 0, String::HINT_MANY_WRITES_EXPECTED);
char param_copy[count];
memcpy(param_copy, decoded, count);
delete[] decoded;
When you want to convert a V8 String
to a null-terminated C char*
use NanCString
. The resulting char*
will be UTF-8-encoded, and you need to supply a pointer to a variable that will be assigned the number of bytes in the returned string. It is also possible to supply a buffer and its length to the function in order not to have a new buffer allocated. The final argument allows optionally setting String::WriteOptions
, which default to v8::String::NO_OPTIONS
.
Just remember that you'll end up with an object that you'll need to delete[]
at some point unless you supply your own buffer:
size_t count;
char* name = NanCString(args[0], &count);
A convenience function that uses NanRawString()
to convert a V8 String
to a char*
. Defaults to UTF8 encoding and no null-termination.
size_t count;
char* name = NanFromV8String(args[0]);
When you have an "options" object that you need to fetch properties from, boolean options can be fetched with this pair. They check first if the object exists (IsEmpty
), then if the object has the given property (Has
) then they get and convert/coerce the property to a bool
.
The optional last parameter is the default value, which is false
if left off:
// `foo` is false unless the user supplies a truthy value for it
bool foo = NanBooleanOptionValue(optionsObj, NanSymbol("foo"));
// `bar` is true unless the user supplies a falsy value for it
bool bar = NanBooleanOptionValueDefTrue(optionsObj, NanSymbol("bar"), true);
Similar to NanBooleanOptionValue
, use NanUInt32OptionValue
to fetch an integer option from your options object. Can be any kind of JavaScript Number
and it will be coerced to an unsigned 32-bit integer.
Requires all 3 arguments as a default is not optional:
uint32_t count = NanUInt32OptionValue(optionsObj, NanSymbol("count"), 1024);
For making Error
, TypeError
and RangeError
objects.
Local<Value> res = NanError("you must supply a callback argument");
NanThrowError(message), NanThrowTypeError(message), NanThrowRangeError(message), NanThrowError(Local<Value>), NanThrowError(Local<Value>, int)
For throwing Error
, TypeError
and RangeError
objects. You should return
this call:
return NanThrowError("you must supply a callback argument");
Can also handle any custom object you may want to throw. If used with the error code argument, it will add the supplied error code to the error object as a property called code
.
The Buffer
API has changed a little in Node 0.11, this helper provides consistent access to Buffer
creation:
NanNewBufferHandle((char*)value.data(), value.size());
Can also be used to initialize a Buffer
with just a size
argument.
Can also be supplied with a NAN_WEAK_CALLBACK
and a hint for the garbage collector, when dealing with weak references.
Buffer::New(char*, uint32_t)
prior to 0.11 would make a copy of the data.
While it was possible to get around this, it required a shim by passing a
callback. So the new API Buffer::Use(char*, uint32_t)
was introduced to remove
needing to use this shim.
NanBufferUse
uses the char*
passed as the backing data, and will free the
memory automatically when the weak callback is called. Keep this in mind, as
careless use can lead to "double free or corruption" and other cryptic failures.
Can be used to check the type of an object to determine it is of a particular class you have already defined and have a Persistent<FunctionTemplate>
handle for.
Aside from FunctionCallbackInfo
, the biggest and most painful change to V8 in Node 0.11 is the many restrictions now placed on Persistent
handles. They are difficult to assign and difficult to fetch the original value out of.
Use NanPersistentToLocal
to convert a Persistent
handle back to a Local
handle.
Local<Object> handle = NanPersistentToLocal(persistentHandle);
Local<FunctionTemplate> ftmpl = FunctionTemplate::New();
Local<ObjectTemplate> otmpl = ftmpl->InstanceTemplate();
Local<Context> ctx = NanNewContextHandle(NULL, otmpl);
Use NanDisposePersistent
to dispose a Persistent
handle.
NanDisposePersistent(persistentHandle);
Use NanAssignPersistent
to assign a non-Persistent
handle to a Persistent
one. You can no longer just declare a Persistent
handle and assign directly to it later, you have to Reset
it in Node 0.11, so this makes it easier.
In general it is now better to place anything you want to protect from V8's garbage collector as properties of a generic Object
and then assign that to a Persistent
. This works in older versions of Node also if you use NanAssignPersistent
:
Persistent<Object> persistentHandle;
...
Local<Object> obj = Object::New();
obj->Set(NanSymbol("key"), keyHandle); // where keyHandle might be a Local<String>
NanAssignPersistent(Object, persistentHandle, obj)
User NanInitPersistent
to declare and initialize a new Persistent
with the supplied object. The assignment operator for Persistent
is no longer public in Node 0.11, so this macro makes it easier to declare and initializing a new Persistent
. See NanAssignPersistent
for more information.
Local<Object> obj = Object::New();
obj->Set(NanSymbol("key"), keyHandle); // where keyHandle might be a Local<String>
NanInitPersistent(Object, persistentHandle, obj);
Because of the difficulties imposed by the changes to Persistent
handles in V8 in Node 0.11, creating Persistent
versions of your Handle<Function>
is annoyingly tricky. NanCallback
makes it easier by taking your handle, making it persistent until the NanCallback
is deleted and even providing a handy Call()
method to fetch and execute the callback Function
.
Local<Function> callbackHandle = args[0].As<Function>();
NanCallback *callback = new NanCallback(callbackHandle);
// pass `callback` around and it's safe from GC until you:
delete callback;
You can execute the callback like so:
// no arguments:
callback->Call(0, NULL);
// an error argument:
Handle<Value> argv[] = {
Exception::Error(String::New("fail!"))
};
callback->Call(1, argv);
// a success argument:
Handle<Value> argv[] = {
Null(),
String::New("w00t!")
};
callback->Call(2, argv);
NanCallback
also has a Local<Function> GetCallback()
method that you can use
to fetch a local handle to the underlying callback function, as well as a
void SetFunction(Handle<Function>)
for setting the callback on the
NanCallback
. Additionally a generic constructor is available for using
NanCallback
without performing heap allocations.
NanAsyncWorker
is an abstract class that you can subclass to have much of the annoying async queuing and handling taken care of for you. It can even store arbitrary V8 objects for you and have them persist while the async work is in progress.
See a rough outline of the implementation:
class NanAsyncWorker {
public:
NanAsyncWorker (NanCallback *callback);
// Clean up persistent handles and delete the *callback
virtual ~NanAsyncWorker ();
// Check the `char *errmsg` property and call HandleOKCallback()
// or HandleErrorCallback depending on whether it has been set or not
virtual void WorkComplete ();
// You must implement this to do some async work. If there is an
// error then allocate `errmsg` to a message and the callback will
// be passed that string in an Error object
virtual void Execute ();
// Save a V8 object in a Persistent handle to protect it from GC
void SavePersistent(const char *key, Local<Object> &obj);
// Fetch a stored V8 object (don't call from within `Execute()`)
Local<Object> GetFromPersistent(const char *key);
protected:
// Set this if there is an error, otherwise it's NULL
const char *errmsg;
// Default implementation calls the callback function with no arguments.
// Override this to return meaningful data
virtual void HandleOKCallback ();
// Default implementation calls the callback function with an Error object
// wrapping the `errmsg` string
virtual void HandleErrorCallback ();
};
NanAsyncQueueWorker
will run a NanAsyncWorker
asynchronously via libuv. Both the execute and after_work steps are taken care of for you—most of the logic for this is embedded in NanAsyncWorker
.
NAN is only possible due to the excellent work of the following contributors:
Rod Vagg | GitHub/rvagg | Twitter/@rvagg |
---|---|---|
Benjamin Byholm | GitHub/kkoopa | |
Trevor Norris | GitHub/trevnorris | Twitter/@trevnorris |
Nathan Rajlich | GitHub/TooTallNate | Twitter/@TooTallNate |
Brett Lawson | GitHub/brett19 | Twitter/@brett19x |
Ben Noordhuis | GitHub/bnoordhuis | Twitter/@bnoordhuis |
Copyright (c) 2013 NAN contributors (listed above).
Native Abstractions for Node.js is licensed under an MIT +no-false-attribs license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.