node_modules/node-pty/node_modules/nan/doc/node_misc.md

   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