Native Abstractions for Node.js: C++ header for Node 0.8->0.12 compatibility
npm install nan-asNative Abstractions for Node.js
===============================
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: 1.6.0
(See CHANGELOG.md 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.
* News & Updates
* Usage
* Example
* API
* Tests
* Deprecated NanNewContextHandle in favor of NanNew
* Added NanSetCounterFunction, NanSetCreateHistogramFunction, NanSetAddHistogramSampleFunction
* Added NanIdleNotification, NanLowMemoryNotification, NanContextDisposedNotification
* Added NanEncode, NanDecodeBytes and NanDecodeWrite
* Support io.js thanks to Ben Noordhuis
* Rewritten NanNew internals thanks to David Siegel
* NanAsyncWorker now supports progress reporting thanks to Brett Lawson
NanCString() and NanRawString() have been deprecated in favour of new NanAsciiString, NanUtf8String and NanUcs2String. These classes manage the underlying memory for you in a safer way than just handing off an allocated array. You should now NanAsciiString(handle) to access the raw char data, you can also allocate on the heap if you need to keep a reference.
* Two more NanMakeCallback overloads have been added to for parity with Node core.
* You can now NanNew(std::string) (use NanNew to pass by reference)
* NanSetTemplate, NanSetPrototypeTemplate and NanSetInstanceTemplate have been added.
* We've deprecated NanSymbol(), you should just use NanNew now.
* NanNull(), NanUndefined(), NanTrue(), NanFalse() all return Locals now.
* nan_isolate is gone, it was intended to be internal-only but if you were using it then you should switch to v8::Isolate::GetCurrent().
* NanNew() has received some additional overload-love so you should be able to give it many kinds of values without specifying the
Lots of small fixes and additions to expand the V8 API coverage, use the source, Luke*.
Node 0.11.11 and 0.11.12 were both broken releases for native add-ons, you simply can't properly compile against either of them for different reasons. But we now have a 0.11.13 release that jumps a couple of versions of V8 ahead and includes some more, major (traumatic) API changes.
Because we are now nearing Node 0.12 and estimate that the version of V8 we are using in Node 0.11.13 will be close to the API we get for 0.12, we have taken the opportunity to not only fix NAN for 0.11.13 but make some major changes to improve the NAN API.
We have removed support for Node 0.11 versions prior to 0.11.13. As usual, our tests are run against (and pass) the last 5 versions of Node 0.8 and Node 0.10. We also include Node 0.11.13 obviously.
The major change is something that Benjamin Byholm has put many hours in to. We now have a fantastic new NanNew interface for creating new Locals, this replaces NanNewLocal() and much more. If you look in ./nan.h you'll see a large number of overloaded versions of this method. In general you should be able to NanNew for any type you want to make a Local from. This includes Persistent types, so we now have a Local to replace NanPersistentToLocal().
We also now have NanUndefined(), NanNull(), NanTrue() and NanFalse(). Mainly because of the new requirement for an Isolate argument for each of the native V8 versions of this.
V8 has now introduced an EscapableHandleScope from which you scope.Escape(Local to return a value from a one scope to another. This replaces the standard HandleScope and scope.Close(Local, although HandleScope still exists for when you don't need to return a handle to the caller. For NAN we are exposing it as NanEscapableScope() and NanEscapeScope(), while NanScope() is still how you create a new scope that doesn't need to return handles. For older versions of Node/V8, it'll still map to the older HandleScope functionality.
NanFromV8String() was deprecated and has now been removed. You should use NanCString() or NanRawString() instead.
Because node::MakeCallback() now takes an Isolate, and because it doesn't exist in older versions of Node, we've introduced NanMakeCallback(). You should always use this when calling a JavaScript function from C++.
There's lots more, check out the Changelog in nan.h or look through #86 for all the gory details.
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 Locals to: v8::Local, i.e. introducing the isolate argument and therefore breaking all new Local declarations for previous versions. NAN 0.6+ now includes a NanNewLocal 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 to NanNewLocal.
Inclusion of NAN in a project's binding.gyp is now greatly simplified. You can now just use " 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:
`` bash`
$ npm install --save nan
Pull in the path to NAN in your binding.gyp so that you can use #include in your .cpp files:
` python`
"include_dirs" : [
"]
This works like a -I 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.
For another example, see nan-example-eol. It shows newline detection implemented as a native addon.
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.
`c++
// addon.cc
#include
#include
// ...
using v8::FunctionTemplate;
using v8::Handle;
using v8::Object;
using v8::String;
void InitAll(Handle
exports->Set(NanNew
NanNew
}
NODE_MODULE(addon, InitAll)
`
`c++
// sync.h
#include
#include
NAN_METHOD(CalculateSync);
`
`c++
// sync.cc
#include
#include
#include "./sync.h"
// ...
using v8::Number;
// 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(NanNew
}
`
`c++
// async.h
#include
#include
NAN_METHOD(CalculateAsync);
`
`c++
// async.cc
#include
#include
#include "./async.h"
// ...
using v8::Function;
using v8::Local;
using v8::Null;
using v8::Number;
using v8::Value;
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
NanNull()
, NanNew
};
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
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_GC_CALLBACK
* NAN_WEAK_CALLBACK
* NAN_DEPRECATED
* NAN_INLINE
* NanNew
* NanUndefined
* NanNull
* NanTrue
* NanFalse
* NanReturnValue
* NanReturnUndefined
* NanReturnNull
* NanReturnEmptyString
* NanReturnThis
* NanReturnHolder
* NanScope
* NanEscapableScope
* NanEscapeScope
* NanLocker
* NanUnlocker
* NanGetInternalFieldPointer
* NanSetInternalFieldPointer
* NanObjectWrapHandle
* NanSymbol
* NanGetPointerSafe
* NanSetPointerSafe
* NanRawString
* NanCString
* NanAsciiString
* NanUtf8String
* NanUcs2String
* NanBooleanOptionValue
* NanUInt32OptionValue
* NanError, NanTypeError, NanRangeError
* NanThrowError, NanThrowTypeError, NanThrowRangeError, NanThrowError(Handle, NanThrowError(Handle
NanNewBufferHandle(char , size_t, FreeCallback, void ), NanNewBufferHandle(char , uint32_t), NanNewBufferHandle(uint32_t)
NanBufferUse(char , uint32_t)
* NanNewContextHandle
* NanGetCurrentContext
* NanHasInstance
* NanDisposePersistent
* NanAssignPersistent
* NanMakeWeakPersistent
* NanSetTemplate
* NanSetPrototypeTemplate
* NanSetInstanceTemplate
* NanMakeCallback
* NanEncode
* NanDecodeBytes
* NanDecodeWrite
* NanCompileScript
* NanRunScript
* NanAdjustExternalMemory
* NanAddGCEpilogueCallback
* NanAddGCPrologueCallback
* NanRemoveGCEpilogueCallback
* NanRemoveGCPrologueCallback
* NanGetHeapStatistics
* NanSetCounterFunction
* NanSetCreateHistogramFunction
* NanSetAddHistogramSampleFunction
* NanIdleNotification
* NanLowMemoryNotification
* NanContextDisposedNotification
* NanCallback
* NanAsyncWorker
* NanAsyncQueueWorker
Use NAN_METHOD to define your V8 accessible methods:
`c++
// .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:
`c++
// 0.10 and below:
Handle
// 0.11 and above
void name(const FunctionCallbackInfo
`
The introduction of FunctionCallbackInfo brings additional complications:
Use NAN_GETTER to declare your V8 accessible getters. You get a Local 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 object to work with.
to declare your V8 accessible property getters. You get a Local 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.$3
Use NAN_PROPERTY_SETTER to declare your V8 accessible property setters. Same as NAN_PROPERTY_GETTER but you also get a Local value object to work with.$3
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.$3
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.$3
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.$3
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.$3
Use NAN_INDEX_SETTER to declare your V8 accessible index setters. Same as NAN_INDEX_GETTER but you also get a Local value object to work with.$3
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.$3
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.$3
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.$3
Use NAN_GC_CALLBACK to declare your callbacks for NanAddGCEpilogueCallback and NanAddGCPrologueCallback. You get arguments GCType type and GCCallbackFlags flags.`c++
static Persistent callback;NAN_GC_CALLBACK(gcPrologueCallback) {
Local argv[] = {NanNew("prologue")};
NanMakeCallback(NanGetCurrentContext()->Global(), NanNew(callback), 1, argv);
}
NAN_METHOD(Hook) {
NanScope();
NanAssignPersistent(callback, args[0].As());
NanAddGCPrologueCallback(gcPrologueCallback);
NanReturnValue(args.Holder());
}
`$3
Use
to define your V8 WeakReference callbacks. There is an argument object const _NanWeakCallbackData allowing access to the weak object and the supplied parameter through its GetValue and GetParameter methods. You can even access the weak callback info object through the GetCallbackInfo()method, but you probably should not. Revive() keeps the weak object alive until the next GC round.`c++
NAN_WEAK_CALLBACK(weakCallback) {
int *parameter = data.GetParameter();
NanMakeCallback(NanGetCurrentContext()->Global(), data.GetValue(), 0, NULL);
if ((*parameter)++ == 0) {
data.Revive();
} else {
delete parameter;
}
}
`$3
Declares a function as deprecated.c++
static NAN_DEPRECATED NAN_METHOD(foo) {
...
}
`$3
Inlines a function.c++
NAN_INLINE int foo(int bar) {
...
}
`$3
Use
to construct almost all v8 objects (bound Scripts are constructed with NanCompileScript(Handle)) and make new local handles.`c++
Local s = NanNew("value");...
Persistent
...
Local
`$3
Use instead of
$3
Use instead of
$3
Use instead of
$3
Use instead of
$3
Use
when you want to return a value from your V8 accessible method:`c++
NAN_METHOD(Foo::Bar) {
... NanReturnValue(NanNew("FooBar!"));
}
`No
statement required.$3
Use
NanReturnUndefined when you don't want to return anything from your V8 accessible method:`c++
NAN_METHOD(Foo::Baz) {
... NanReturnUndefined();
}
`$3
Use
when you want to return Null from your V8 accessible method:`c++
NAN_METHOD(Foo::Baz) {
... NanReturnNull();
}
`$3
Use
when you want to return an empty String from your V8 accessible method:`c++
NAN_METHOD(Foo::Baz) {
... NanReturnEmptyString();
}
`$3
Use
when you want to return This from your V8 accessible method:`c++
NAN_METHOD(Foo::Baz) {
... NanReturnThis();
}
`$3
Use
when you want to return Holder from your V8 accessible method:`c++
NAN_METHOD(Foo::Baz) {
... NanReturnHolder();
}
`$3
The introduction of
references for many V8 calls in Node 0.11 makes NanScope() necessary, use it in place of HandleScope scope when you do not wish to return handles (Handle or Local) to the surrounding scope (or in functions directly exposed to V8, as they do not return values in the normal sense):`c++
NAN_METHOD(Foo::Bar) {
NanScope(); NanReturnValue(NanNew("FooBar!"));
}
`This method is not directly exposed to V8, nor does it return a handle, so it uses an unescapable scope:
c++
bool Foo::Bar() {
NanScope(); Local val = NanFalse();
...
return val->Value();
}
`$3
The separation of handle scopes into escapable and inescapable scopes makes
necessary, use it in place of HandleScope scope when you later wish to return a handle (Handle or Local) from the scope, this is for internal functions not directly exposed to V8:`c++
Handle Foo::Bar() {
NanEscapableScope(); return NanEscapeScope(NanNew("FooBar!"));
}
`$3
Use together with to escape the scope. Corresponds to HandleScope::Close or EscapableHandleScope::Escape.$3
The introduction of
isolate references for many V8 calls in Node 0.11 makes NanLocker() necessary, use it in place of Locker locker:`c++
NAN_METHOD(Foo::Bar) {
NanLocker();
...
NanUnlocker();
}
`$3
The introduction of
references for many V8 calls in Node 0.11 makes NanUnlocker() necessary, use it in place of Unlocker unlocker:`c++
NAN_METHOD(Foo::Bar) {
NanLocker();
...
NanUnlocker();
}
`$3
Gets a pointer to the internal field with at
from a V8 Object handle.`c++
Local`
$3
Sets the value of the internal field at
on a V8 Object handle.`c++
static Persistent dataWrapperCtor;
...
Local `$3
When you want to fetch the V8 object handle from a native object you've wrapped with Node's
, you should use NanObjectWrapHandle:`c++
NanObjectWrapHandle(iterator)->Get(NanNew("end"))
`$3
Deprecated. Use
instead.
~~Use to create string symbol objects (i.e. v8::String::NewSymbol(x)), for getting and setting object properties, or names of objects.~~`c++
bool foo = false;
if (obj->Has(NanNew("foo")))
foo = optionsObj->Get(NanNew("foo"))->BooleanValue()
`$3
A helper for getting values from optional pointers. If the pointer is
, the function returns the optional default value, which defaults to 0. Otherwise, the function returns the value the pointer points to.`c++
char plugh(uint32_t optional) {
char res[] = "xyzzy";
uint32_t param = NanGetPointerSafe(optional, 0x1337);
switch (param) {
...
}
NanSetPointerSafe(optional, 0xDEADBEEF);
}
`$3
A helper for setting optional argument pointers. If the pointer is
, the function simply returns false. Otherwise, the value is assigned to the variable the pointer points to.`c++
const char plugh(size_t outputsize) {
char res[] = "xyzzy";
if !(NanSetPointerSafe(outputsize, strlen(res) + 1)) {
...
} ...
}
`$3
Deprecated. Use something else.
~~When you want to convert a V8
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:~~`c++
size_t count;
void* decoded = NanRawString(args[1], Nan::BASE64, &count, NULL, 0, String::HINT_MANY_WRITES_EXPECTED);
...
delete[] reinterpret_cast(decoded);
`$3
Deprecated. Use
or NanUtf8String instead.~~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:~~`c++
size_t count;
char* name = NanCString(args[0], &count);
...
delete[] name;
`$3
Contrary to the name, this is not actually an ASCII string, it is a one-byte string with no particular encoding. Do not use unless you actually need this incorrect legacy behavior. Consider fixing your broken code instead. If you actually have a proper ASCII-string, use UTF-8, which is a proper superset of ASCII.
Convert a
to zero-terminated, sort-of Ascii-encoded char *. The underlying buffer is freed when the owner object goes out of scope, so make a copy or heap allocation if you need it to stick around.`c++
NAN_METHOD(foo) {
NanScope();
NanReturnValue(NanNew(*NanAsciiString(arg[0])));
}
`####WRONG:
the buffer
points to has been freed when baz was destroyed:
`c++
static char *str;NAN_METHOD(bar) {
NanScope();
NanAsciiString baz(arg[0]);
str = *baz;
NanReturnUndefined(); // baz goes out of scope, freeing str
}
...
printf(str); // use-after-free error
`####RIGHT:
c++
static NanAsciiString *str;NAN_METHOD(bar) {
NanScope();
str = new NanAsciiString(arg[0]);
NanReturnUndefined();
}
...
printf(**str);
`$3
Equivalent to
, it only exists for the sake of completeness.
Convert a String to zero-terminated, Utf8-encoded char *. The underlying buffer is freed when the owner object goes out of scope, so make a copy or heap allocation if you need it to stick around.`c++
NAN_METHOD(foo) {
NanScope();
NanReturnValue(NanNew(*NanUtf8String(arg[0])));
}
`####WRONG:
the buffer
points to has been freed when baz was destroyed:
`c++
static char *str;NAN_METHOD(bar) {
NanScope();
NanUtf8String baz(arg[0]);
str = *baz;
NanReturnUndefined(); // baz goes out of scope, freeing str
}
...
printf(str); // use-after-free error
`####RIGHT:
c++
static NanUtf8String *str;NAN_METHOD(bar) {
NanScope();
str = new NanUtf8String(arg[0]);
NanReturnUndefined();
}
...
printf(**str);
`$3
Equivalent to
, it only exists for the sake of completeness.
Convert a String to zero-terminated, Ucs2-encoded uint16_t *. The underlying buffer is freed when the owner object goes out of scope, so make a copy or heap allocation if you need it to stick around.`c++
NAN_METHOD(foo) {
NanScope();
NanReturnValue(NanNew(*NanUcs2String(arg[0])));
}
`####WRONG:
the buffer
points to has been freed when baz was destroyed:
`c++
static char *str;NAN_METHOD(bar) {
NanScope();
NanUcs2String baz(arg[0]);
str = *baz;
NanReturnUndefined(); // baz goes out of scope, freeing str
}
...
printf(str); // use-after-free error
`####RIGHT:
c++
static NanUcs2String *str;NAN_METHOD(bar) {
NanScope();
str = new NanUcs2String(arg[0]);
NanReturnUndefined();
}
...
printf(**str);
`$3
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 (
), 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:`c++
// foo is false unless the user supplies a truthy value for it
bool foo = NanBooleanOptionValue(optionsObj, NanNew("foo"));
// bar is true unless the user supplies a falsy value for it
bool bar = NanBooleanOptionValueDefTrue(optionsObj, NanNew("bar"), true);
`$3
Similar to
, 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:
`c++
uint32_t count = NanUInt32OptionValue(optionsObj, NanNew("count"), 1024);
`$3
For making
, TypeError and RangeError objects.`c++
Local res = NanError("you must supply a callback argument");
`$3
For throwing
, TypeError and RangeError objects.`c++
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
.$3
The
Buffer API has changed a little in Node 0.11, this helper provides consistent access to Buffer creation:`c++
NanNewBufferHandle((char*)value.data(), value.size());
`Can also be used to initialize a
with just a size argument.Can also be supplied with a
NanFreeCallback and a hint for the garbage collector.$3
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.$3
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 handle for.$3
Deprecated. Use
NanNew instead.~~Creates a new
Local handle.`c++
Local ftmpl = NanNew();
Local otmpl = ftmpl->InstanceTemplate();
Local ctx = NanNewContextHandle(NULL, otmpl);
`$3
Gets the current context.
c++
Local ctx = NanGetCurrentContext();
`$3
Use
to dispose a Persistent handle.`c++
NanDisposePersistent(persistentHandle);
`$3
Use
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:`c++
Persistent`$3
Creates a weak persistent handle with the supplied parameter and
.`c++
NAN_WEAK_CALLBACK(weakCallback) {...
}
Local func;
...
int *parameter = new int(0);
NanMakeWeakPersistent(func, parameter, &weakCallback);
`$3
Use to add properties on object and function templates.
$3
Use to add prototype properties on function templates.
$3
Use to add instance properties on function templates.
$3
Use instead of
to call javascript functions. This (or NanCallback) is the only proper way of calling functions. You must _never, ever_ directly use Function::Call, it will lead to run-time failures.$3
Replaces
node::Encode.$3
Replaces
node::DecodeBytes.$3
Replaces
node::DecodeWrite.$3
Use to create new scripts bound to the current context.
$3
Use to run both bound and unbound scripts.
$3
Simply does
AdjustAmountOfExternalAllocatedMemory, note that the argument and returned value have type int.$3
Simply does
AddGCEpilogueCallback$3
Simply does
$3
Simply does
$3
Simply does
$3
Simply does
$3
Simply does
$3
Simply does
$3
Simply does
$3
Simply does
$3
Simply does
$3
Simply does
$3
Because of the difficulties imposed by the changes to
handles in V8 in Node 0.11, creating Persistent versions of your Handle 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.`c++
Local callbackHandle = args[0].As();
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:
c++
// no arguments:
callback->Call(0, NULL);// an error argument:
Handle argv[] = {
NanError(NanNew("fail!"))
};
callback->Call(1, argv);
// a success argument:
Handle argv[] = {
NanNull(),
NanNew("w00t!")
};
callback->Call(2, argv);
` also has a Local method that you can use
to fetch a local handle to the underlying callback function, as well as a
void SetFunction(Handle for setting the callback on the
NanCallback. You can check if a NanCallback is empty with the bool IsEmpty() method. Additionally a generic constructor is available for using
NanCallback without performing heap allocations.$3
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:
`c++
class NanAsyncWorker {
public:
NanAsyncWorker (NanCallback *callback); // Clean up persistent handles and delete the *callback
virtual ~NanAsyncWorker ();
// Check the
ErrorMessage() 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 use
SetErrorMessage() to set an error 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 SaveToPersistent(const char *key, Local
// Fetch a stored V8 object (don't call from within
Execute())
Localerrmsg string
virtual void HandleErrorCallback ();
};
`$3
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.$3
To run the NAN tests do:
` sh
npm install
npm run-script rebuild-tests
npm test
`Or just:
sh
npm install
make test
``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 |
| David Siegel | GitHub/agnat | - |
Licence & copyright
-----------------------
Copyright (c) 2015 NAN contributors (listed above).
Native Abstractions for Node.js is licensed under an MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.