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.
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)
template<typenameT> classPersistentBase {public: /** * If non-empty, destroy the underlying storage cell */voidReset(); /** * 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<typenameS> voidReset(const v8::Local<S> &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<typenameS> voidReset(constPersistentBase<S> &other); /** * If non-empty, destroy the underlying storage cell * IsEmpty() will return true after this call. */boolIsEmpty();voidEmpty();template<typenameS> booloperator==(constPersistentBase<S> &that);template<typenameS> booloperator==(const v8::Local<S> &that);template<typenameS> booloperator!=(constPersistentBase<S> &that);template<typenameS> booloperator!=(const v8::Local<S> &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<typenameP>voidSetWeak(P*parameter,typename WeakCallbackInfo<P>::Callback callback,WeakCallbackType type);voidClearWeak(); /** * 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. */voidMarkIndependent() const;boolIsIndependent() const; /** Checks if the handle holds the only reference to an object. */boolIsNearDeath() const; /** Returns true if the handle's reference is weak. */boolIsWeak() 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:
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)
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)
A type of PersistentBase which allows copy and assignment. Copy, assignment and destructor behavior is controlled by the traits class M.
Definition:
template<typenameT,typenameM= NonCopyablePersistentTraits<T> >classPersistent;template<typenameT,typenameM> classPersistent:publicPersistentBase<T> {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<typenameS> Persistent(v8::Local<S> 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(constPersistent&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=(constPersistent&that);template <typenameS,typenameM2>Persistent&operator=(constPersistent<S,M2> &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.
template<typenameT> classGlobal:publicPersistentBase<T> {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<typenameS> Global(v8::Local<S> 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<typenameS> Global(const PersistentBase<S>&that); /** * Pass allows returning globals from functions, etc. */GlobalPass();};
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:
template<typenameT> classWeakCallbackInfo {public:typedefvoid (*Callback)(constWeakCallbackInfo<T>& 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;};
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.