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
|
# EscapableHandleScope
The `Napi::EscapableHandleScope` class is used to manage the lifetime of object handles
which are created through the use of node-addon-api. These handles
keep an object alive in the heap in order to ensure that the objects
are not collected by the garbage collector while native code is using them.
A handle may be created when any new node-addon-api Value or one
of its subclasses is created or returned.
The `Napi::EscapableHandleScope` is a special type of `Napi::HandleScope`
which allows a single handle to be "promoted" to an outer scope.
For more details refer to the section titled
[Object lifetime management](object_lifetime_management.md).
## Methods
### Constructor
Creates a new escapable handle scope.
```cpp
Napi::EscapableHandleScope Napi::EscapableHandleScope::New(Napi::Env env);
```
- `[in] Env`: The environment in which to construct the `Napi::EscapableHandleScope` object.
Returns a new `Napi::EscapableHandleScope`
### Constructor
Creates a new escapable handle scope.
```cpp
Napi::EscapableHandleScope Napi::EscapableHandleScope::New(napi_env env, napi_handle_scope scope);
```
- `[in] env`: `napi_env` in which the scope passed in was created.
- `[in] scope`: pre-existing `napi_handle_scope`.
Returns a new `Napi::EscapableHandleScope` instance which wraps the
`napi_escapable_handle_scope` handle passed in. This can be used
to mix usage of the C Node-API and node-addon-api.
```cpp
operator Napi::EscapableHandleScope::napi_escapable_handle_scope() const
```
Returns the Node-API `napi_escapable_handle_scope` wrapped by the `Napi::EscapableHandleScope` object.
This can be used to mix usage of the C Node-API and node-addon-api by allowing
the class to be used be converted to a `napi_escapable_handle_scope`.
### Destructor
```cpp
Napi::EscapableHandleScope::~EscapableHandleScope();
```
Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created
in the scope to be collected by the garbage collector. There is no
guarantee as to when the garbage collector will do this.
### Escape
```cpp
napi::Value Napi::EscapableHandleScope::Escape(napi_value escapee);
```
- `[in] escapee`: `Napi::Value` or `napi_env` to promote to the outer scope
Returns `Napi::Value` which can be used in the outer scope. This method can
be called at most once on a given `Napi::EscapableHandleScope`. If it is called
more than once an exception will be thrown.
### Env
```cpp
Napi::Env Napi::EscapableHandleScope::Env() const;
```
Returns the `Napi::Env` associated with the `Napi::EscapableHandleScope`.
|
