1# EscapableHandleScope
2
3The `Napi::EscapableHandleScope` class is used to manage the lifetime of object handles
4which are created through the use of node-addon-api. These handles
5keep an object alive in the heap in order to ensure that the objects
6are not collected by the garbage collector while native code is using them.
7A handle may be created when any new node-addon-api Value or one
8of its subclasses is created or returned.
9
10The `Napi::EscapableHandleScope` is a special type of `Napi::HandleScope`
11which allows a single handle to be "promoted" to an outer scope.
12
13For more details refer to the section titled
14[Object lifetime management](object_lifetime_management.md).
15
16## Methods
17
18### Constructor
19
20Creates a new escapable handle scope.
21
22```cpp
23Napi::EscapableHandleScope Napi::EscapableHandleScope::New(Napi::Env env);
24```
25
26- `[in] Env`: The environment in which to construct the `Napi::EscapableHandleScope` object.
27
28Returns a new `Napi::EscapableHandleScope`
29
30### Constructor
31
32Creates a new escapable handle scope.
33
34```cpp
35Napi::EscapableHandleScope Napi::EscapableHandleScope::New(napi_env env, napi_handle_scope scope);
36```
37
38- `[in] env`: `napi_env` in which the scope passed in was created.
39- `[in] scope`: pre-existing `napi_handle_scope`.
40
41Returns a new `Napi::EscapableHandleScope` instance which wraps the
42`napi_escapable_handle_scope` handle passed in. This can be used
43to mix usage of the C Node-API and node-addon-api.
44
45```cpp
46operator Napi::EscapableHandleScope::napi_escapable_handle_scope() const
47```
48
49Returns the Node-API `napi_escapable_handle_scope` wrapped by the `Napi::EscapableHandleScope` object.
50This can be used to mix usage of the C Node-API and node-addon-api by allowing
51the class to be used be converted to a `napi_escapable_handle_scope`.
52
53### Destructor
54```cpp
55Napi::EscapableHandleScope::~EscapableHandleScope();
56```
57
58Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created
59in the scope to be collected by the garbage collector. There is no
60guarantee as to when the garbage collector will do this.
61
62### Escape
63
64```cpp
65napi::Value Napi::EscapableHandleScope::Escape(napi_value escapee);
66```
67
68- `[in] escapee`: `Napi::Value` or `napi_env` to promote to the outer scope
69
70Returns `Napi::Value` which can be used in the outer scope. This method can
71be called at most once on a given `Napi::EscapableHandleScope`. If it is called
72more than once an exception will be thrown.
73
74### Env
75
76```cpp
77Napi::Env Napi::EscapableHandleScope::Env() const;
78```
79
80Returns the `Napi::Env` associated with the `Napi::EscapableHandleScope`.
81