1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
# Env
The opaque data structure containing the environment in which the request is being run.
The Env object is usually created and passed by the Node.js runtime or node-addon-api infrastructure.
## Methods
### Constructor
```cpp
Napi::Env::Env(napi_env env);
```
- `[in] env`: The `napi_env` environment from which to construct the `Napi::Env` object.
### napi_env
```cpp
operator napi_env() const;
```
Returns the `napi_env` opaque data structure representing the environment.
### Global
```cpp
Napi::Object Napi::Env::Global() const;
```
Returns the `Napi::Object` representing the environment's JavaScript Global Object.
### Undefined
```cpp
Napi::Value Napi::Env::Undefined() const;
```
Returns the `Napi::Value` representing the environment's JavaScript Undefined Object.
### Null
```cpp
Napi::Value Napi::Env::Null() const;
```
Returns the `Napi::Value` representing the environment's JavaScript Null Object.
### IsExceptionPending
```cpp
bool Napi::Env::IsExceptionPending() const;
```
Returns a `bool` indicating if an exception is pending in the environment.
### GetAndClearPendingException
```cpp
Napi::Error Napi::Env::GetAndClearPendingException() const;
```
Returns an `Napi::Error` object representing the environment's pending exception, if any.
### RunScript
```cpp
Napi::Value Napi::Env::RunScript(____ script) const;
```
- `[in] script`: A string containing JavaScript code to execute.
Runs JavaScript code contained in a string and returns its result.
The `script` can be any of the following types:
- [`Napi::String`](string.md)
- `const char *`
- `const std::string &`
### GetInstanceData
```cpp
template <typename T> T* GetInstanceData() const;
```
Returns the instance data that was previously associated with the environment,
or `nullptr` if none was associated.
### SetInstanceData
```cpp
template <typename T> using Finalizer = void (*)(Env, T*);
template <typename T, Finalizer<T> fini = Env::DefaultFini<T>>
void SetInstanceData(T* data) const;
```
- `[template] fini`: A function to call when the instance data is to be deleted.
Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
not given, the default finalizer will be used, which simply uses the `delete`
operator to destroy `T*` when the addon instance is unloaded.
- `[in] data`: A pointer to data that will be associated with the instance of
the addon for the duration of its lifecycle.
Associates a data item stored at `T* data` with the current instance of the
addon. The item will be passed to the function `fini` which gets called when an
instance of the addon is unloaded.
### SetInstanceData
```cpp
template <typename DataType, typename HintType>
using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
template <typename DataType,
typename HintType,
FinalizerWithHint<DataType, HintType> fini =
Env::DefaultFiniWithHint<DataType, HintType>>
void SetInstanceData(DataType* data, HintType* hint) const;
```
- `[template] fini`: A function to call when the instance data is to be deleted.
Accepts a function of the form
`void CleanupData(Napi::Env env, DataType* data, HintType* hint)`. If not given,
the default finalizer will be used, which simply uses the `delete` operator to
destroy `T*` when the addon instance is unloaded.
- `[in] data`: A pointer to data that will be associated with the instance of
the addon for the duration of its lifecycle.
- `[in] hint`: A pointer to data that will be associated with the instance of
the addon for the duration of its lifecycle and will be passed as a hint to
`fini` when the addon instance is unloaded.
Associates a data item stored at `T* data` with the current instance of the
addon. The item will be passed to the function `fini` which gets called when an
instance of the addon is unloaded. This overload accepts an additional hint to
be passed to `fini`.
### AddCleanupHook
```cpp
template <typename Hook>
CleanupHook<Hook> AddCleanupHook(Hook hook);
```
- `[in] hook`: A function to call when the environment exists. Accepts a
function of the form `void ()`.
Registers `hook` as a function to be run once the current Node.js environment
exits. Unlike the underlying C-based Node-API, providing the same `hook`
multiple times **is** allowed. The hooks will be called in reverse order, i.e.
the most recently added one will be called first.
Returns an `Env::CleanupHook` object, which can be used to remove the hook via
its `Remove()` method.
### AddCleanupHook
```cpp
template <typename Hook, typename Arg>
CleanupHook<Hook, Arg> AddCleanupHook(Hook hook, Arg* arg);
```
- `[in] hook`: A function to call when the environment exists. Accepts a
function of the form `void (Arg* arg)`.
- `[in] arg`: A pointer to data that will be passed as the argument to `hook`.
Registers `hook` as a function to be run with the `arg` parameter once the
current Node.js environment exits. Unlike the underlying C-based Node-API,
providing the same `hook` and `arg` pair multiple times **is** allowed. The
hooks will be called in reverse order, i.e. the most recently added one will be
called first.
Returns an `Env::CleanupHook` object, which can be used to remove the hook via
its `Remove()` method.
# Env::CleanupHook
The `Env::CleanupHook` object allows removal of the hook added via
`Env::AddCleanupHook()`
## Methods
### IsEmpty
```cpp
bool IsEmpty();
```
Returns `true` if the cleanup hook was **not** successfully registered.
### Remove
```cpp
bool Remove(Env env);
```
Unregisters the hook from running once the current Node.js environment exits.
Returns `true` if the hook was successfully removed from the Node.js
environment.
|
