1 | ## Persistent references
|
2 |
|
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.
|
4 |
|
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.
|
6 |
|
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>
|
14 |
|
15 | Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://v8.dev/docs/embed#handles-and-garbage-collection).
|
16 |
|
17 | <a name="api_nan_persistent_base"></a>
|
18 | ### Nan::PersistentBase & v8::PersistentBase
|
19 |
|
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()`.
|
21 |
|
22 | Definition:
|
23 |
|
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)_
|
25 |
|
26 | ```c++
|
27 | template<typename T> class PersistentBase {
|
28 | public:
|
29 | /**
|
30 | * If non-empty, destroy the underlying storage cell
|
31 | */
|
32 | void Reset();
|
33 |
|
34 | /**
|
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
|
37 | */
|
38 | template<typename S> void Reset(const v8::Local<S> &other);
|
39 |
|
40 | /**
|
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
|
43 | */
|
44 | template<typename S> void Reset(const PersistentBase<S> &other);
|
45 |
|
46 | /** Returns true if the handle is empty. */
|
47 | bool IsEmpty() const;
|
48 |
|
49 | /**
|
50 | * If non-empty, destroy the underlying storage cell
|
51 | * IsEmpty() will return true after this call.
|
52 | */
|
53 | void Empty();
|
54 |
|
55 | template<typename S> bool operator==(const PersistentBase<S> &that);
|
56 |
|
57 | template<typename S> bool operator==(const v8::Local<S> &that);
|
58 |
|
59 | template<typename S> bool operator!=(const PersistentBase<S> &that);
|
60 |
|
61 | template<typename S> bool operator!=(const v8::Local<S> &that);
|
62 |
|
63 | /**
|
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.
|
71 | */
|
72 | template<typename P>
|
73 | void SetWeak(P *parameter,
|
74 | typename WeakCallbackInfo<P>::Callback callback,
|
75 | WeakCallbackType type);
|
76 |
|
77 | void ClearWeak();
|
78 |
|
79 | /**
|
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.
|
84 | */
|
85 | void MarkIndependent() const;
|
86 |
|
87 | bool IsIndependent() const;
|
88 |
|
89 | /** Checks if the handle holds the only reference to an object. */
|
90 | bool IsNearDeath() const;
|
91 |
|
92 | /** Returns true if the handle's reference is weak. */
|
93 | bool IsWeak() const
|
94 | };
|
95 | ```
|
96 |
|
97 | See the V8 documentation for [`PersistentBase`](https://v8docs.nodesource.com/node-8.16/d4/dca/classv8_1_1_persistent_base.html) for further information.
|
98 |
|
99 | **Tip:** To get a `v8::Local` reference to the original object back from a `PersistentBase` or `Persistent` object:
|
100 |
|
101 | ```c++
|
102 | v8::Local<v8::Object> object = Nan::New(persistent);
|
103 | ```
|
104 |
|
105 | <a name="api_nan_non_copyable_persistent_traits"></a>
|
106 | ### Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits
|
107 |
|
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.
|
109 |
|
110 | Definition:
|
111 |
|
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)_
|
113 |
|
114 | ```c++
|
115 | template<typename T> class NonCopyablePersistentTraits {
|
116 | public:
|
117 | typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent;
|
118 |
|
119 | static const bool kResetInDestructor = false;
|
120 |
|
121 | template<typename S, typename M>
|
122 | static void Copy(const Persistent<S, M> &source,
|
123 | NonCopyablePersistent *dest);
|
124 |
|
125 | template<typename O> static void Uncompilable();
|
126 | };
|
127 | ```
|
128 |
|
129 | See the V8 documentation for [`NonCopyablePersistentTraits`](https://v8docs.nodesource.com/node-8.16/de/d73/classv8_1_1_non_copyable_persistent_traits.html) for further information.
|
130 |
|
131 | <a name="api_nan_copyable_persistent_traits"></a>
|
132 | ### Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits
|
133 |
|
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..
|
135 |
|
136 | Definition:
|
137 |
|
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)_
|
139 |
|
140 | ```c++
|
141 | template<typename T>
|
142 | class CopyablePersistentTraits {
|
143 | public:
|
144 | typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent;
|
145 |
|
146 | static const bool kResetInDestructor = true;
|
147 |
|
148 | template<typename S, typename M>
|
149 | static void Copy(const Persistent<S, M> &source,
|
150 | CopyablePersistent *dest);
|
151 | };
|
152 | ```
|
153 |
|
154 | See the V8 documentation for [`CopyablePersistentTraits`](https://v8docs.nodesource.com/node-8.16/da/d5c/structv8_1_1_copyable_persistent_traits.html) for further information.
|
155 |
|
156 | <a name="api_nan_persistent"></a>
|
157 | ### Nan::Persistent
|
158 |
|
159 | A type of `PersistentBase` which allows copy and assignment. Copy, assignment and destructor behavior is controlled by the traits class `M`.
|
160 |
|
161 | Definition:
|
162 |
|
163 | ```c++
|
164 | template<typename T, typename M = NonCopyablePersistentTraits<T> >
|
165 | class Persistent;
|
166 |
|
167 | template<typename T, typename M> class Persistent : public PersistentBase<T> {
|
168 | public:
|
169 | /**
|
170 | * A Persistent with no storage cell.
|
171 | */
|
172 | Persistent();
|
173 |
|
174 | /**
|
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
|
177 | * set.
|
178 | */
|
179 | template<typename S> Persistent(v8::Local<S> that);
|
180 |
|
181 | /**
|
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
|
184 | * set.
|
185 | */
|
186 | Persistent(const Persistent &that);
|
187 |
|
188 | /**
|
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.
|
192 | */
|
193 | Persistent &operator=(const Persistent &that);
|
194 |
|
195 | template <typename S, typename M2>
|
196 | Persistent &operator=(const Persistent<S, M2> &that);
|
197 |
|
198 | /**
|
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.
|
202 | */
|
203 | ~Persistent();
|
204 | };
|
205 | ```
|
206 |
|
207 | See the V8 documentation for [`Persistent`](https://v8docs.nodesource.com/node-8.16/d2/d78/classv8_1_1_persistent.html) for further information.
|
208 |
|
209 | <a name="api_nan_global"></a>
|
210 | ### Nan::Global
|
211 |
|
212 | A type of `PersistentBase` which has move semantics.
|
213 |
|
214 | ```c++
|
215 | template<typename T> class Global : public PersistentBase<T> {
|
216 | public:
|
217 | /**
|
218 | * A Global with no storage cell.
|
219 | */
|
220 | Global();
|
221 |
|
222 | /**
|
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.
|
225 | */
|
226 | template<typename S> Global(v8::Local<S> that);
|
227 | /**
|
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
|
230 | * set.
|
231 | */
|
232 | template<typename S> Global(const PersistentBase<S> &that);
|
233 |
|
234 | /**
|
235 | * Pass allows returning globals from functions, etc.
|
236 | */
|
237 | Global Pass();
|
238 | };
|
239 | ```
|
240 |
|
241 | See the V8 documentation for [`Global`](https://v8docs.nodesource.com/node-8.16/d5/d40/classv8_1_1_global.html) for further information.
|
242 |
|
243 | <a name="api_nan_weak_callback_info"></a>
|
244 | ### Nan::WeakCallbackInfo
|
245 |
|
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.
|
247 |
|
248 | Definition:
|
249 |
|
250 | ```c++
|
251 | template<typename T> class WeakCallbackInfo {
|
252 | public:
|
253 | typedef void (*Callback)(const WeakCallbackInfo<T>& data);
|
254 |
|
255 | v8::Isolate *GetIsolate() const;
|
256 |
|
257 | /**
|
258 | * Get the parameter that was associated with the weak handle.
|
259 | */
|
260 | T *GetParameter() const;
|
261 |
|
262 | /**
|
263 | * Get pointer from internal field, index can be 0 or 1.
|
264 | */
|
265 | void *GetInternalField(int index) const;
|
266 | };
|
267 | ```
|
268 |
|
269 | Example usage:
|
270 |
|
271 | ```c++
|
272 | void weakCallback(const WeakCallbackInfo<int> &data) {
|
273 | int *parameter = data.GetParameter();
|
274 | delete parameter;
|
275 | }
|
276 |
|
277 | Persistent<v8::Object> obj;
|
278 | int *data = new int(0);
|
279 | obj.SetWeak(data, callback, WeakCallbackType::kParameter);
|
280 | ```
|
281 |
|
282 | See the V8 documentation for [`WeakCallbackInfo`](https://v8docs.nodesource.com/node-8.16/d8/d06/classv8_1_1_weak_callback_info.html) for further information.
|
283 |
|
284 | <a name="api_nan_weak_callback_type"></a>
|
285 | ### Nan::WeakCallbackType
|
286 |
|
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.
|
291 |
|
292 | Definition:
|
293 |
|
294 | ```c++
|
295 | enum class WeakCallbackType { kParameter, kInternalFields };
|
296 | ```
|