1 | ## Scopes
|
2 |
|
3 | A _local handle_ is a pointer to an object. All V8 objects are accessed using handles, they are necessary because of the way the V8 garbage collector works.
|
4 |
|
5 | A handle scope can be thought of as a container for any number of handles. When you've finished with your handles, instead of deleting each one individually you can simply delete their scope.
|
6 |
|
7 | The creation of `HandleScope` objects is different across the supported versions of V8. Therefore, NAN provides its own implementations that can be used safely across these.
|
8 |
|
9 | - <a href="#api_nan_handle_scope"><b><code>Nan::HandleScope</code></b></a>
|
10 | - <a href="#api_nan_escapable_handle_scope"><b><code>Nan::EscapableHandleScope</code></b></a>
|
11 |
|
12 | Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://github.com/v8/v8/wiki/Embedder%27s%20Guide#handles-and-garbage-collection).
|
13 |
|
14 | <a name="api_nan_handle_scope"></a>
|
15 | ### Nan::HandleScope
|
16 |
|
17 | A simple wrapper around [`v8::HandleScope`](https://v8docs.nodesource.com/node-8.11/d3/d95/classv8_1_1_handle_scope.html).
|
18 |
|
19 | Definition:
|
20 |
|
21 | ```c++
|
22 | class Nan::HandleScope {
|
23 | public:
|
24 | Nan::HandleScope();
|
25 | static int NumberOfHandles();
|
26 | };
|
27 | ```
|
28 |
|
29 | Allocate a new `Nan::HandleScope` whenever you are creating new V8 JavaScript objects. Note that an implicit `HandleScope` is created for you on JavaScript-accessible methods so you do not need to insert one yourself.
|
30 |
|
31 | Example:
|
32 |
|
33 | ```c++
|
34 | // new object is created, it needs a new scope:
|
35 | void Pointless() {
|
36 | Nan::HandleScope scope;
|
37 | v8::Local<v8::Object> obj = Nan::New<v8::Object>();
|
38 | }
|
39 |
|
40 | // JavaScript-accessible method already has a HandleScope
|
41 | NAN_METHOD(Pointless2) {
|
42 | v8::Local<v8::Object> obj = Nan::New<v8::Object>();
|
43 | }
|
44 | ```
|
45 |
|
46 | <a name="api_nan_escapable_handle_scope"></a>
|
47 | ### Nan::EscapableHandleScope
|
48 |
|
49 | Similar to [`Nan::HandleScope`](#api_nan_handle_scope) but should be used in cases where a function needs to return a V8 JavaScript type that has been created within it.
|
50 |
|
51 | Definition:
|
52 |
|
53 | ```c++
|
54 | class Nan::EscapableHandleScope {
|
55 | public:
|
56 | Nan::EscapableHandleScope();
|
57 | static int NumberOfHandles();
|
58 | template<typename T> v8::Local<T> Escape(v8::Local<T> value);
|
59 | }
|
60 | ```
|
61 |
|
62 | Use `Escape(value)` to return the object.
|
63 |
|
64 | Example:
|
65 |
|
66 | ```c++
|
67 | v8::Local<v8::Object> EmptyObj() {
|
68 | Nan::EscapableHandleScope scope;
|
69 | v8::Local<v8::Object> obj = Nan::New<v8::Object>();
|
70 | return scope.Escape(obj);
|
71 | }
|
72 | ```
|
73 |
|