www.aleph1.co.uk Git - yaffs-website/blob - node_modules/nan/doc/persistent.md

   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://developers.google.com/v8/embed#handles).
  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   /**
  47    * If non-empty, destroy the underlying storage cell
  48    * IsEmpty() will return true after this call.
  49    */
  50   bool IsEmpty();
  51
  52   void Empty();
  53
  54   template<typename S> bool operator==(const PersistentBase<S> &that);
  55
  56   template<typename S> bool operator==(const v8::Local<S> &that);
  57
  58   template<typename S> bool operator!=(const PersistentBase<S> &that);
  59
  60   template<typename S> bool operator!=(const v8::Local<S> &that);
  61
  62    /**
  63    *  Install a finalization callback on this object.
  64    *  NOTE: There is no guarantee as to *when* or even *if* the callback is
  65    *  invoked. The invocation is performed solely on a best effort basis.
  66    *  As always, GC-based finalization should *not* be relied upon for any
  67    *  critical form of resource management! At the moment you can either
  68    *  specify a parameter for the callback or the location of two internal
  69    *  fields in the dying object.
  70    */
  71   template<typename P>
  72   void SetWeak(P *parameter,
  73                typename WeakCallbackInfo<P>::Callback callback,
  74                WeakCallbackType type);
  75
  76   void ClearWeak();
  77
  78   /**
  79    * Marks the reference to this object independent. Garbage collector is free
  80    * to ignore any object groups containing this object. Weak callback for an
  81    * independent handle should not assume that it will be preceded by a global
  82    * GC prologue callback or followed by a global GC epilogue callback.
  83    */
  84   void MarkIndependent() const;
  85
  86   bool IsIndependent() const;
  87
  88   /** Checks if the handle holds the only reference to an object. */
  89   bool IsNearDeath() const;
  90
  91   /** Returns true if the handle's reference is weak.  */
  92   bool IsWeak() const
  93 };
  94 ```
  95
  96 See the V8 documentation for [`PersistentBase`](https://v8docs.nodesource.com/io.js-3.0/d4/dca/classv8_1_1_persistent_base.html) for further information.
  97
  98 **Tip:** To get a `v8::Local` reference to the original object back from a `PersistentBase` or `Persistent` object:
  99
 100 ```c++
 101 v8::Local<v8::Object> object = Nan::New(persistent);
 102 ```
 103
 104 <a name="api_nan_non_copyable_persistent_traits"></a>
 105 ### Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits
 106
 107 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.
 108
 109 Definition:
 110
 111 _(note: this is implemented as `Nan::NonCopyablePersistentTraits` for older versions of V8 and the native `v8::NonCopyablePersistentTraits` is used for newer versions of V8)_
 112
 113 ```c++
 114 template<typename T> class NonCopyablePersistentTraits {
 115  public:
 116   typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent;
 117
 118   static const bool kResetInDestructor = false;
 119
 120   template<typename S, typename M>
 121   static void Copy(const Persistent<S, M> &source,
 122                    NonCopyablePersistent *dest);
 123
 124   template<typename O> static void Uncompilable();
 125 };
 126 ```
 127
 128 See the V8 documentation for [`NonCopyablePersistentTraits`](https://v8docs.nodesource.com/io.js-3.0/de/d73/classv8_1_1_non_copyable_persistent_traits.html) for further information.
 129
 130 <a name="api_nan_copyable_persistent_traits"></a>
 131 ### Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits
 132
 133 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..
 134
 135 Definition:
 136
 137 _(note: this is implemented as `Nan::CopyablePersistentTraits` for older versions of V8 and the native `v8::NonCopyablePersistentTraits` is used for newer versions of V8)_
 138
 139 ```c++
 140 template<typename T>
 141 class CopyablePersistentTraits {
 142  public:
 143   typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent;
 144
 145   static const bool kResetInDestructor = true;
 146
 147   template<typename S, typename M>
 148   static void Copy(const Persistent<S, M> &source,
 149                    CopyablePersistent *dest);
 150 };
 151 ```
 152
 153 See the V8 documentation for [`CopyablePersistentTraits`](https://v8docs.nodesource.com/io.js-3.0/da/d5c/structv8_1_1_copyable_persistent_traits.html) for further information.
 154
 155 <a name="api_nan_persistent"></a>
 156 ### Nan::Persistent
 157
 158 A type of `PersistentBase` which allows copy and assignment. Copy, assignment and destructor behavior is controlled by the traits class `M`.
 159
 160 Definition:
 161
 162 ```c++
 163 template<typename T, typename M = NonCopyablePersistentTraits<T> >
 164 class Persistent;
 165
 166 template<typename T, typename M> class Persistent : public PersistentBase<T> {
 167  public:
 168  /**
 169   * A Persistent with no storage cell.
 170   */
 171   Persistent();
 172
 173   /**
 174    * Construct a Persistent from a v8::Local. When the v8::Local is non-empty, a
 175    * new storage cell is created pointing to the same object, and no flags are
 176    * set.
 177    */
 178   template<typename S> Persistent(v8::Local<S> that);
 179
 180   /**
 181    * Construct a Persistent from a Persistent. When the Persistent is non-empty,
 182    * a new storage cell is created pointing to the same object, and no flags are
 183    * set.
 184    */
 185   Persistent(const Persistent &that);
 186
 187   /**
 188    * The copy constructors and assignment operator create a Persistent exactly
 189    * as the Persistent constructor, but the Copy function from the traits class
 190    * is called, allowing the setting of flags based on the copied Persistent.
 191    */
 192   Persistent &operator=(const Persistent &that);
 193
 194   template <typename S, typename M2>
 195   Persistent &operator=(const Persistent<S, M2> &that);
 196
 197   /**
 198    * The destructor will dispose the Persistent based on the kResetInDestructor
 199    * flags in the traits class.  Since not calling dispose can result in a
 200    * memory leak, it is recommended to always set this flag.
 201    */
 202   ~Persistent();
 203 };
 204 ```
 205
 206 See the V8 documentation for [`Persistent`](https://v8docs.nodesource.com/io.js-3.0/d2/d78/classv8_1_1_persistent.html) for further information.
 207
 208 <a name="api_nan_global"></a>
 209 ### Nan::Global
 210
 211 A type of `PersistentBase` which has move semantics.
 212
 213 ```c++
 214 template<typename T> class Global : public PersistentBase<T> {
 215  public:
 216   /**
 217    * A Global with no storage cell.
 218    */
 219   Global();
 220
 221   /**
 222    * Construct a Global from a v8::Local. When the v8::Local is non-empty, a new
 223    * storage cell is created pointing to the same object, and no flags are set.
 224    */
 225   template<typename S> Global(v8::Local<S> that);
 226   /**
 227    * Construct a Global from a PersistentBase. When the Persistent is non-empty,
 228    * a new storage cell is created pointing to the same object, and no flags are
 229    * set.
 230    */
 231   template<typename S> Global(const PersistentBase<S> &that);
 232
 233   /**
 234    * Pass allows returning globals from functions, etc.
 235    */
 236   Global Pass();
 237 };
 238 ```
 239
 240 See the V8 documentation for [`Global`](https://v8docs.nodesource.com/io.js-3.0/d5/d40/classv8_1_1_global.html) for further information.
 241
 242 <a name="api_nan_weak_callback_info"></a>
 243 ### Nan::WeakCallbackInfo
 244
 245 `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.
 246
 247 Definition:
 248
 249 ```c++
 250 template<typename T> class WeakCallbackInfo {
 251  public:
 252   typedef void (*Callback)(const WeakCallbackInfo<T>& data);
 253
 254   v8::Isolate *GetIsolate() const;
 255
 256   /**
 257    * Get the parameter that was associated with the weak handle.
 258    */
 259   T *GetParameter() const;
 260
 261   /**
 262    * Get pointer from internal field, index can be 0 or 1.
 263    */
 264   void *GetInternalField(int index) const;
 265 };
 266 ```
 267
 268 Example usage:
 269
 270 ```c++
 271 void weakCallback(const WeakCallbackInfo<int> &data) {
 272   int *parameter = data.GetParameter();
 273   delete parameter;
 274 }
 275
 276 Persistent<v8::Object> obj;
 277 int *data = new int(0);
 278 obj.SetWeak(data, callback, WeakCallbackType::kParameter);
 279 ```
 280
 281 See the V8 documentation for [`WeakCallbackInfo`](https://v8docs.nodesource.com/io.js-3.0/d8/d06/classv8_1_1_weak_callback_info.html) for further information.
 282
 283 <a name="api_nan_weak_callback_type"></a>
 284 ### Nan::WeakCallbackType
 285
 286 Represents the type of a weak callback.
 287 A weak callback of type `kParameter` makes the supplied parameter to `Nan::PersistentBase::SetWeak` available through `WeakCallbackInfo::GetParameter`.
 288 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.
 289 Note that only `v8::Object`s and derivatives can have internal fields.
 290
 291 Definition:
 292
 293 ```c++
 294 enum class WeakCallbackType { kParameter, kInternalFields };
 295 ```