Scopes

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.

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.

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.

• Nan::HandleScope

• Nan::EscapableHandleScope

Also see the V8 Embedders Guide section on Handles and Garbage Collection.

Nan::HandleScope

A simple wrapper around v8::HandleScope.

Definition:

class Nan::HandleScope {
 public:
  Nan::HandleScope();
  static int NumberOfHandles();
};

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.

Example:

// new object is created, it needs a new scope:
void Pointless() {
  Nan::HandleScope scope;
  v8::Local<v8::Object> obj = Nan::New<v8::Object>();
}

// JavaScript-accessible method already has a HandleScope
NAN_METHOD(Pointless2) {
  v8::Local<v8::Object> obj = Nan::New<v8::Object>();
}

Nan::EscapableHandleScope

Similar to Nan::HandleScope but should be used in cases where a function needs to return a V8 JavaScript type that has been created within it.

Definition:

class Nan::EscapableHandleScope {
 public:
  Nan::EscapableHandleScope();
  static int NumberOfHandles();
  template<typename T> v8::Local<T> Escape(v8::Local<T> value);
}

Use Escape(value) to return the object.

Example:

v8::Local<v8::Object> EmptyObj() {
  Nan::EscapableHandleScope scope;
  v8::Local<v8::Object> obj = Nan::New<v8::Object>();
  return scope.Escape(obj);
}