Persistent references

An object reference that is independent of any HandleScope is a persistent reference. Where a Local handle only lives as long as the HandleScope in which it was allocated, a Persistent handle remains valid until it is explicitly disposed.

Due to the evolution of the V8 API, it is necessary for NAN to provide a wrapper implementation of the Persistent classes to supply compatibility across the V8 versions supported.

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

Nan::PersistentBase & v8::PersistentBase

A persistent handle contains a reference to a storage cell in V8 which holds an object value and which is updated by the garbage collector whenever the object is moved. A new storage cell can be created using the constructor or Nan::PersistentBase::Reset(). Existing handles can be disposed using an argument-less Nan::PersistentBase::Reset().

Definition:

(note: this is implemented as Nan::PersistentBase for older versions of V8 and the native v8::PersistentBase is used for newer versions of V8)

```c++ template class PersistentBase { public: /* * If non-empty, destroy the underlying storage cell / void Reset();

/* * If non-empty, destroy the underlying storage cell and create a new one with * the contents of another if it is also non-empty / template void Reset(const v8::Local &other);

/* * If non-empty, destroy the underlying storage cell and create a new one with * the contents of another if it is also non-empty / template void Reset(const PersistentBase &other);

/* Returns true if the handle is empty. / bool IsEmpty() const;

/* * If non-empty, destroy the underlying storage cell * IsEmpty() will return true after this call. / void Empty();

template bool operator==(const PersistentBase &that);

template bool operator==(const v8::Local &that);

template bool operator!=(const PersistentBase &that);

template bool operator!=(const v8::Local &that);

/ * Install a finalization callback on this object. * NOTE: There is no guarantee as to when or even if the callback is * invoked. The invocation is performed solely on a best effort basis. * As always, GC-based finalization should not be relied upon for any * critical form of resource management! At the moment you can either * specify a parameter for the callback or the location of two internal * fields in the dying object. / template void SetWeak(P parameter, typename WeakCallbackInfo

::Callback callback, WeakCallbackType type);

void ClearWeak();

/* * Marks the reference to this object independent. Garbage collector is free * to ignore any object groups containing this object. Weak callback for an * independent handle should not assume that it will be preceded by a global * GC prologue callback or followed by a global GC epilogue callback. / void MarkIndependent() const;

bool IsIndependent() const;

/* Checks if the handle holds the only reference to an object. / bool IsNearDeath() const;

/* Returns true if the handle's reference is weak. / bool IsWeak() const }; ```

See the V8 documentation for PersistentBase for further information.

Tip: To get a v8::Local reference to the original object back from a PersistentBase or Persistent object:

c++ v8::Local<v8::Object> object = Nan::New(persistent);

Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits

Default traits for Nan::Persistent. This class does not allow use of the a copy constructor or assignment operator. At present kResetInDestructor is not set, but that will change in a future version.

Definition:

(note: this is implemented as Nan::NonCopyablePersistentTraits for older versions of V8 and the native v8::NonCopyablePersistentTraits is used for newer versions of V8)

```c++ template class NonCopyablePersistentTraits { public: typedef Persistent > NonCopyablePersistent;

static const bool kResetInDestructor = false;

template static void Copy(const Persistent &source, NonCopyablePersistent *dest);

template static void Uncompilable(); }; ```

See the V8 documentation for NonCopyablePersistentTraits for further information.

Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits

A helper class of traits to allow copying and assignment of Persistent. This will clone the contents of storage cell, but not any of the flags, etc..

Definition:

(note: this is implemented as Nan::CopyablePersistentTraits for older versions of V8 and the native v8::NonCopyablePersistentTraits is used for newer versions of V8)

```c++ template class CopyablePersistentTraits { public: typedef Persistent > CopyablePersistent;

static const bool kResetInDestructor = true;

template static void Copy(const Persistent &source, CopyablePersistent *dest); }; ```

See the V8 documentation for CopyablePersistentTraits for further information.

Nan::Persistent

A type of PersistentBase which allows copy and assignment. Copy, assignment and destructor behavior is controlled by the traits class M.

Definition:

```c++ template > class Persistent;

template class Persistent : public PersistentBase { public: /* * A Persistent with no storage cell. / Persistent();

/* * Construct a Persistent from a v8::Local. When the v8::Local is non-empty, a * new storage cell is created pointing to the same object, and no flags are * set. / template Persistent(v8::Local that);

/* * Construct a Persistent from a Persistent. When the Persistent is non-empty, * a new storage cell is created pointing to the same object, and no flags are * set. / Persistent(const Persistent &that);

/* * The copy constructors and assignment operator create a Persistent exactly * as the Persistent constructor, but the Copy function from the traits class * is called, allowing the setting of flags based on the copied Persistent. / Persistent &operator=(const Persistent &that);

template Persistent &operator=(const Persistent &that);

/* * The destructor will dispose the Persistent based on the kResetInDestructor * flags in the traits class. Since not calling dispose can result in a * memory leak, it is recommended to always set this flag. / ~Persistent(); }; ```

See the V8 documentation for Persistent for further information.

Nan::Global

A type of PersistentBase which has move semantics.

```c++ template class Global : public PersistentBase { public: /* * A Global with no storage cell. / Global();

/ * Construct a Global from a v8::Local. When the v8::Local is non-empty, a new * storage cell is created pointing to the same object, and no flags are set. */ template Global(v8::Local that); / * Construct a Global from a PersistentBase. When the Persistent is non-empty, * a new storage cell is created pointing to the same object, and no flags are * set. */ template Global(const PersistentBase &that);

/* * Pass allows returning globals from functions, etc. / Global Pass(); }; ```

See the V8 documentation for Global for further information.

Nan::WeakCallbackInfo

Nan::WeakCallbackInfo is used as an argument when setting a persistent reference as weak. You may need to free any external resources attached to the object. It is a mirror of v8:WeakCallbackInfo as found in newer versions of V8.

Definition:

```c++ template class WeakCallbackInfo { public: typedef void (*Callback)(const WeakCallbackInfo& data);

v8::Isolate *GetIsolate() const;

/ * Get the parameter that was associated with the weak handle. / T GetParameter() const;

/ * Get pointer from internal field, index can be 0 or 1. / void GetInternalField(int index) const; }; ```

Example usage:

```c++ void weakCallback(const WeakCallbackInfo &data) { int *parameter = data.GetParameter(); delete parameter; }

Persistent obj; int *data = new int(0); obj.SetWeak(data, callback, WeakCallbackType::kParameter); ```

See the V8 documentation for WeakCallbackInfo for further information.

Nan::WeakCallbackType

Represents the type of a weak callback. A weak callback of type kParameter makes the supplied parameter to Nan::PersistentBase::SetWeak available through WeakCallbackInfo::GetParameter. A weak callback of type kInternalFields uses up to two internal fields at indices 0 and 1 on the Nan::PersistentBase<v8::Object> being made weak. Note that only v8::Objects and derivatives can have internal fields.

Definition:

c++ enum class WeakCallbackType { kParameter, kInternalFields };