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 |
|
11 | This class is analogous to the `AsyncResource` JavaScript class exposed by Node's [async_hooks][] API.
|
12 |
|
13 | When calling back into JavaScript asynchronously, special care must be taken to ensure that the runtime can properly track
|
14 | async hops. `Nan::AsyncResource` is a class that provides an RAII wrapper around `node::EmitAsyncInit`, `node::EmitAsyncDestroy`,
|
15 | and `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
|
17 | such as domains and [async_hooks][] function correctly.
|
18 |
|
19 | Definition:
|
20 |
|
21 | ```c++
|
22 | class 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 |
|
55 | For 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 |
|
61 | Deprecated wrappers around the legacy `node::MakeCallback()` APIs. Node.js 10+
|
62 | has deprecated these legacy APIs as they do not provide a mechanism to preserve
|
63 | async context.
|
64 |
|
65 | We 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
|
67 | context – something that is essential for functionality like domains, async_hooks and async debugging.
|
68 |
|
69 | Signatures:
|
70 |
|
71 | ```c++
|
72 | NAN_DEPRECATED
|
73 | v8::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);
|
77 | NAN_DEPRECATED
|
78 | v8::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);
|
82 | NAN_DEPRECATED
|
83 | v8::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 |
|
93 | 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.
|
94 |
|
95 | See example below.
|
96 |
|
97 | <a name="api_nan_export"></a>
|
98 | ### Nan::Export()
|
99 |
|
100 | A 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 |
|
102 | Signature:
|
103 |
|
104 | ```c++
|
105 | void Export(v8::Local<v8::Object> target, const char *name, Nan::FunctionCallback f)
|
106 | ```
|
107 |
|
108 | Also available as the shortcut `NAN_EXPORT` macro.
|
109 |
|
110 | Example:
|
111 |
|
112 | ```c++
|
113 | NAN_METHOD(Foo) {
|
114 | ...
|
115 | }
|
116 |
|
117 | NAN_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
|