Miscellaneous Node Helpers

Nan::AsyncResource

This class is analogous to the AsyncResource JavaScript class exposed by Node’s async_hooks API.

When calling back into JavaScript asynchornously, special care must be taken to ensure that the runtime can properly track async hops. Nan::AsyncResource is a class that provides an RAII wrapper around node::EmitAsyncInit, node::EmitAsyncDestroy, and node::MakeCallback. Using this mechanism to call back into JavaScript, as opposed to Nan::MakeCallback or v8::Function::Call ensures that the callback is executed in the correct async context. This ensures that async mechanisms such as domains and async_hooks function correctly.

Definition:

class AsyncResource {
 public:
  AsyncResource(v8::Local<v8::String> name,
                v8::Local<v8::Object> resource = New<v8::Object>());
  AsyncResource(const char* name,
                v8::Local<v8::Object> resource = New<v8::Object>());
  ~AsyncResource();

  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
                                            v8::Local<v8::Function> func,
                                            int argc,
                                            v8::Local<v8::Value>* argv,
                                            Nan::async_context async_context);
  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
                                            v8::Local<v8::String> symbol,
                                            int argc,
                                            v8::Local<v8::Value>* argv,
                                            Nan::async_context async_context);
  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
                                            const char* method,
                                            int argc,
                                            v8::Local<v8::Value>* argv,
                                            Nan::async_context async_context);
};

For more details, see the Node async_hooks documentation. You might also want to take a look at the documentation for the N-API counterpart. For example usage, see the asyncresource.cpp example in the test/cpp directory.

Nan::MakeCallback()

Wrappers around the legacy node::MakeCallback() APIs.

We recommend that you use the AsyncResource class and AsyncResource::runInAsyncScope instead of using Nan::MakeCallback or v8::Function#Call() directly. AsyncResource properly takes care of running the callback in the correct async execution context – something that is essential for functionality like domains, async_hooks and async debugging.

Signatures:

v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
                                       v8::Local<v8::Function> func,
                                       int argc,
                                       v8::Local<v8::Value>* argv);
v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
                                       v8::Local<v8::String> symbol,
                                       int argc,
                                       v8::Local<v8::Value>* argv);
v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
                                       const char* method,
                                       int argc,
                                       v8::Local<v8::Value>* argv);

NAN_MODULE_INIT()

Used to define the entry point function to a Node add-on. Creates a function with a given name that receives a target object representing the equivalent of the JavaScript exports object.

See example below.

Nan::Export()

A simple helper to register a v8::FunctionTemplate from a JavaScript-accessible method (see Methods) as a property on an object. Can be used in a way similar to assigning properties to module.exports in JavaScript.

Signature:

void Export(v8::Local<v8::Object> target, const char *name, Nan::FunctionCallback f)

Also available as the shortcut NAN_EXPORT macro.

Example:

NAN_METHOD(Foo) {
  ...
}

NAN_MODULE_INIT(Init) {
  NAN_EXPORT(target, Foo);
}