1 ## Persistent references
3 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.
5 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.
7 - <a href="#api_nan_persistent_base"><b><code>Nan::PersistentBase & v8::PersistentBase</code></b></a>
8 - <a href="#api_nan_non_copyable_persistent_traits"><b><code>Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits</code></b></a>
9 - <a href="#api_nan_copyable_persistent_traits"><b><code>Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits</code></b></a>
10 - <a href="#api_nan_persistent"><b><code>Nan::Persistent</code></b></a>
11 - <a href="#api_nan_global"><b><code>Nan::Global</code></b></a>
12 - <a href="#api_nan_weak_callback_info"><b><code>Nan::WeakCallbackInfo</code></b></a>
13 - <a href="#api_nan_weak_callback_type"><b><code>Nan::WeakCallbackType</code></b></a>
15 Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://developers.google.com/v8/embed#handles).
17 <a name="api_nan_persistent_base"></a>
18 ### Nan::PersistentBase & v8::PersistentBase
20 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()`.
24 _(note: this is implemented as `Nan::PersistentBase` for older versions of V8 and the native `v8::PersistentBase` is used for newer versions of V8)_
27 template<typename T> class PersistentBase {
30 * If non-empty, destroy the underlying storage cell
35 * If non-empty, destroy the underlying storage cell and create a new one with
36 * the contents of another if it is also non-empty
38 template<typename S> void Reset(const v8::Local<S> &other);
41 * If non-empty, destroy the underlying storage cell and create a new one with
42 * the contents of another if it is also non-empty
44 template<typename S> void Reset(const PersistentBase<S> &other);
46 /** Returns true if the handle is empty. */
50 * If non-empty, destroy the underlying storage cell
51 * IsEmpty() will return true after this call.
55 template<typename S> bool operator==(const PersistentBase<S> &that);
57 template<typename S> bool operator==(const v8::Local<S> &that);
59 template<typename S> bool operator!=(const PersistentBase<S> &that);
61 template<typename S> bool operator!=(const v8::Local<S> &that);
64 * Install a finalization callback on this object.
65 * NOTE: There is no guarantee as to *when* or even *if* the callback is
66 * invoked. The invocation is performed solely on a best effort basis.
67 * As always, GC-based finalization should *not* be relied upon for any
68 * critical form of resource management! At the moment you can either
69 * specify a parameter for the callback or the location of two internal
70 * fields in the dying object.
73 void SetWeak(P *parameter,
74 typename WeakCallbackInfo<P>::Callback callback,
75 WeakCallbackType type);
80 * Marks the reference to this object independent. Garbage collector is free
81 * to ignore any object groups containing this object. Weak callback for an
82 * independent handle should not assume that it will be preceded by a global
83 * GC prologue callback or followed by a global GC epilogue callback.
85 void MarkIndependent() const;
87 bool IsIndependent() const;
89 /** Checks if the handle holds the only reference to an object. */
90 bool IsNearDeath() const;
92 /** Returns true if the handle's reference is weak. */
97 See the V8 documentation for [`PersistentBase`](https://v8docs.nodesource.com/node-8.11/d4/dca/classv8_1_1_persistent_base.html) for further information.
99 **Tip:** To get a `v8::Local` reference to the original object back from a `PersistentBase` or `Persistent` object:
102 v8::Local<v8::Object> object = Nan::New(persistent);
105 <a name="api_nan_non_copyable_persistent_traits"></a>
106 ### Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits
108 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.
112 _(note: this is implemented as `Nan::NonCopyablePersistentTraits` for older versions of V8 and the native `v8::NonCopyablePersistentTraits` is used for newer versions of V8)_
115 template<typename T> class NonCopyablePersistentTraits {
117 typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent;
119 static const bool kResetInDestructor = false;
121 template<typename S, typename M>
122 static void Copy(const Persistent<S, M> &source,
123 NonCopyablePersistent *dest);
125 template<typename O> static void Uncompilable();
129 See the V8 documentation for [`NonCopyablePersistentTraits`](https://v8docs.nodesource.com/node-8.11/de/d73/classv8_1_1_non_copyable_persistent_traits.html) for further information.
131 <a name="api_nan_copyable_persistent_traits"></a>
132 ### Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits
134 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..
138 _(note: this is implemented as `Nan::CopyablePersistentTraits` for older versions of V8 and the native `v8::NonCopyablePersistentTraits` is used for newer versions of V8)_
142 class CopyablePersistentTraits {
144 typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent;
146 static const bool kResetInDestructor = true;
148 template<typename S, typename M>
149 static void Copy(const Persistent<S, M> &source,
150 CopyablePersistent *dest);
154 See the V8 documentation for [`CopyablePersistentTraits`](https://v8docs.nodesource.com/node-8.11/da/d5c/structv8_1_1_copyable_persistent_traits.html) for further information.
156 <a name="api_nan_persistent"></a>
159 A type of `PersistentBase` which allows copy and assignment. Copy, assignment and destructor behavior is controlled by the traits class `M`.
164 template<typename T, typename M = NonCopyablePersistentTraits<T> >
167 template<typename T, typename M> class Persistent : public PersistentBase<T> {
170 * A Persistent with no storage cell.
175 * Construct a Persistent from a v8::Local. When the v8::Local is non-empty, a
176 * new storage cell is created pointing to the same object, and no flags are
179 template<typename S> Persistent(v8::Local<S> that);
182 * Construct a Persistent from a Persistent. When the Persistent is non-empty,
183 * a new storage cell is created pointing to the same object, and no flags are
186 Persistent(const Persistent &that);
189 * The copy constructors and assignment operator create a Persistent exactly
190 * as the Persistent constructor, but the Copy function from the traits class
191 * is called, allowing the setting of flags based on the copied Persistent.
193 Persistent &operator=(const Persistent &that);
195 template <typename S, typename M2>
196 Persistent &operator=(const Persistent<S, M2> &that);
199 * The destructor will dispose the Persistent based on the kResetInDestructor
200 * flags in the traits class. Since not calling dispose can result in a
201 * memory leak, it is recommended to always set this flag.
207 See the V8 documentation for [`Persistent`](https://v8docs.nodesource.com/node-8.11/d2/d78/classv8_1_1_persistent.html) for further information.
209 <a name="api_nan_global"></a>
212 A type of `PersistentBase` which has move semantics.
215 template<typename T> class Global : public PersistentBase<T> {
218 * A Global with no storage cell.
223 * Construct a Global from a v8::Local. When the v8::Local is non-empty, a new
224 * storage cell is created pointing to the same object, and no flags are set.
226 template<typename S> Global(v8::Local<S> that);
228 * Construct a Global from a PersistentBase. When the Persistent is non-empty,
229 * a new storage cell is created pointing to the same object, and no flags are
232 template<typename S> Global(const PersistentBase<S> &that);
235 * Pass allows returning globals from functions, etc.
241 See the V8 documentation for [`Global`](https://v8docs.nodesource.com/node-8.11/d5/d40/classv8_1_1_global.html) for further information.
243 <a name="api_nan_weak_callback_info"></a>
244 ### Nan::WeakCallbackInfo
246 `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.
251 template<typename T> class WeakCallbackInfo {
253 typedef void (*Callback)(const WeakCallbackInfo<T>& data);
255 v8::Isolate *GetIsolate() const;
258 * Get the parameter that was associated with the weak handle.
260 T *GetParameter() const;
263 * Get pointer from internal field, index can be 0 or 1.
265 void *GetInternalField(int index) const;
272 void weakCallback(const WeakCallbackInfo<int> &data) {
273 int *parameter = data.GetParameter();
277 Persistent<v8::Object> obj;
278 int *data = new int(0);
279 obj.SetWeak(data, callback, WeakCallbackType::kParameter);
282 See the V8 documentation for [`WeakCallbackInfo`](https://v8docs.nodesource.com/node-8.11/d8/d06/classv8_1_1_weak_callback_info.html) for further information.
284 <a name="api_nan_weak_callback_type"></a>
285 ### Nan::WeakCallbackType
287 Represents the type of a weak callback.
288 A weak callback of type `kParameter` makes the supplied parameter to `Nan::PersistentBase::SetWeak` available through `WeakCallbackInfo::GetParameter`.
289 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.
290 Note that only `v8::Object`s and derivatives can have internal fields.
295 enum class WeakCallbackType { kParameter, kInternalFields };