| 14 |
liveuser |
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://developers.google.com/v8/embed#handles).
|
|
|
13 |
|
|
|
14 |
<a name="api_nan_handle_scope"></a>
|
|
|
15 |
### Nan::HandleScope
|
|
|
16 |
|
|
|
17 |
A simple wrapper around [`v8::HandleScope`](https://v8docs.nodesource.com/io.js-3.0/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 |
|