node_misc.md

Miscellaneous Node Helpers

• Nan::AsyncResource
• Nan::MakeCallback()
• NAN_MODULE_INIT()
• Nan::Export()

Nan::AsyncResource

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

When calling back into JavaScript asynchronously, 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);
  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
                                            v8::Local<v8::String> symbol,
                                            int argc,
                                            v8::Local<v8::Value>* argv);
  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
                                            const char* method,
                                            int argc,
                                            v8::Local<v8::Value>* argv);
};

• name: Identifier for the kind of resource that is being provided for diagnostics information exposed by the async_hooks API. This will be passed to the possible init hook as the type. To avoid name collisions with other modules we recommend that the name include the name of the owning module as a prefix. For example mysql module could use something like mysql:batch-db-query-resource.
• resource: An optional object associated with the async work that will be passed to the possible async_hooks init hook. If this parameter is omitted, or an empty handle is provided, this object will be created automatically.
• When calling JS on behalf of this resource, one can use runInAsyncScope. This will ensure that the callback runs in the correct async execution context.
• AsyncDestroy is automatically called when an AsyncResource object is destroyed.

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()

Deprecated wrappers around the legacy node::MakeCallback() APIs. Node.js 10+ has deprecated these legacy APIs as they do not provide a mechanism to preserve async context.

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:

NAN_DEPRECATED
v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
                                       v8::Local<v8::Function> func,
                                       int argc,
                                       v8::Local<v8::Value>* argv);
NAN_DEPRECATED
v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
                                       v8::Local<v8::String> symbol,
                                       int argc,
                                       v8::Local<v8::Value>* argv);
NAN_DEPRECATED
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);
}