1## Miscellaneous Node Helpers 2 3 - <a href="#api_nan_asyncresource"><b><code>Nan::AsyncResource</code></b></a> 4 - <a href="#api_nan_make_callback"><b><code>Nan::MakeCallback()</code></b></a> 5 - <a href="#api_nan_module_init"><b><code>NAN_MODULE_INIT()</code></b></a> 6 - <a href="#api_nan_export"><b><code>Nan::Export()</code></b></a> 7 8<a name="api_nan_asyncresource"></a> 9### Nan::AsyncResource 10 11This class is analogous to the `AsyncResource` JavaScript class exposed by Node's [async_hooks][] API. 12 13When calling back into JavaScript asynchronously, special care must be taken to ensure that the runtime can properly track 14async hops. `Nan::AsyncResource` is a class that provides an RAII wrapper around `node::EmitAsyncInit`, `node::EmitAsyncDestroy`, 15and `node::MakeCallback`. Using this mechanism to call back into JavaScript, as opposed to `Nan::MakeCallback` or 16`v8::Function::Call` ensures that the callback is executed in the correct async context. This ensures that async mechanisms 17such as domains and [async_hooks][] function correctly. 18 19Definition: 20 21```c++ 22class AsyncResource { 23 public: 24 AsyncResource(v8::Local<v8::String> name, 25 v8::Local<v8::Object> resource = New<v8::Object>()); 26 AsyncResource(const char* name, 27 v8::Local<v8::Object> resource = New<v8::Object>()); 28 ~AsyncResource(); 29 30 v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target, 31 v8::Local<v8::Function> func, 32 int argc, 33 v8::Local<v8::Value>* argv); 34 v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target, 35 v8::Local<v8::String> symbol, 36 int argc, 37 v8::Local<v8::Value>* argv); 38 v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target, 39 const char* method, 40 int argc, 41 v8::Local<v8::Value>* argv); 42}; 43``` 44 45* `name`: Identifier for the kind of resource that is being provided for diagnostics information exposed by the [async_hooks][] 46 API. This will be passed to the possible `init` hook as the `type`. To avoid name collisions with other modules we recommend 47 that the name include the name of the owning module as a prefix. For example `mysql` module could use something like 48 `mysql:batch-db-query-resource`. 49* `resource`: An optional object associated with the async work that will be passed to the possible [async_hooks][] 50 `init` hook. If this parameter is omitted, or an empty handle is provided, this object will be created automatically. 51* When calling JS on behalf of this resource, one can use `runInAsyncScope`. This will ensure that the callback runs in the 52 correct async execution context. 53* `AsyncDestroy` is automatically called when an AsyncResource object is destroyed. 54 55For more details, see the Node [async_hooks][] documentation. You might also want to take a look at the documentation for the 56[N-API counterpart][napi]. For example usage, see the `asyncresource.cpp` example in the `test/cpp` directory. 57 58<a name="api_nan_make_callback"></a> 59### Nan::MakeCallback() 60 61Deprecated wrappers around the legacy `node::MakeCallback()` APIs. Node.js 10+ 62has deprecated these legacy APIs as they do not provide a mechanism to preserve 63async context. 64 65We recommend that you use the `AsyncResource` class and `AsyncResource::runInAsyncScope` instead of using `Nan::MakeCallback` or 66`v8::Function#Call()` directly. `AsyncResource` properly takes care of running the callback in the correct async execution 67context – something that is essential for functionality like domains, async_hooks and async debugging. 68 69Signatures: 70 71```c++ 72NAN_DEPRECATED 73v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target, 74 v8::Local<v8::Function> func, 75 int argc, 76 v8::Local<v8::Value>* argv); 77NAN_DEPRECATED 78v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target, 79 v8::Local<v8::String> symbol, 80 int argc, 81 v8::Local<v8::Value>* argv); 82NAN_DEPRECATED 83v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target, 84 const char* method, 85 int argc, 86 v8::Local<v8::Value>* argv); 87``` 88 89 90<a name="api_nan_module_init"></a> 91### NAN_MODULE_INIT() 92 93Used 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. 94 95See example below. 96 97<a name="api_nan_export"></a> 98### Nan::Export() 99 100A simple helper to register a `v8::FunctionTemplate` from a JavaScript-accessible method (see [Methods](./methods.md)) as a property on an object. Can be used in a way similar to assigning properties to `module.exports` in JavaScript. 101 102Signature: 103 104```c++ 105void Export(v8::Local<v8::Object> target, const char *name, Nan::FunctionCallback f) 106``` 107 108Also available as the shortcut `NAN_EXPORT` macro. 109 110Example: 111 112```c++ 113NAN_METHOD(Foo) { 114 ... 115} 116 117NAN_MODULE_INIT(Init) { 118 NAN_EXPORT(target, Foo); 119} 120``` 121 122[async_hooks]: https://nodejs.org/dist/latest-v9.x/docs/api/async_hooks.html 123[napi]: https://nodejs.org/dist/latest-v9.x/docs/api/n-api.html#n_api_custom_asynchronous_operations 124