www.aleph1.co.uk Git - yaffs-website/blob - node_modules/nan/doc/scopes.md

   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/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