File Explorer

1// Copyright 2021 the V8 project authors. All rights reserved.2// Use of this source code is governed by a BSD-style license that can be3// found in the LICENSE file.4 5#ifndef INCLUDE_V8_PERSISTENT_HANDLE_H_6#define INCLUDE_V8_PERSISTENT_HANDLE_H_7 8#include "v8-internal.h"            // NOLINT(build/include_directory)9#include "v8-local-handle.h"        // NOLINT(build/include_directory)10#include "v8-weak-callback-info.h"  // NOLINT(build/include_directory)11#include "v8config.h"               // NOLINT(build/include_directory)12 13namespace v8 {14 15class Isolate;16template <class K, class V, class T>17class PersistentValueMapBase;18template <class T>19class Global;20template <class T>21class PersistentBase;22template <class K, class V, class T>23class PersistentValueMap;24class Value;25 26namespace api_internal {27V8_EXPORT internal::Address* Eternalize(v8::Isolate* isolate, Value* handle);28V8_EXPORT internal::Address* CopyGlobalReference(internal::Address* from);29V8_EXPORT void DisposeGlobal(internal::Address* global_handle);30V8_EXPORT void MakeWeak(internal::Address** location_addr);31V8_EXPORT void* ClearWeak(internal::Address* location);32V8_EXPORT void AnnotateStrongRetainer(internal::Address* location,33                                      const char* label);34V8_EXPORT internal::Address* GlobalizeReference(internal::Isolate* isolate,35                                                internal::Address value);36V8_EXPORT void MoveGlobalReference(internal::Address** from,37                                   internal::Address** to);38}  // namespace api_internal39 40/**41 * Eternal handles are set-once handles that live for the lifetime of the42 * isolate.43 */44template <class T>45class Eternal : public api_internal::IndirectHandleBase {46 public:47  V8_INLINE Eternal() = default;48 49  /**50   * Constructor for handling automatic up casting.51   */52  template <class S>53    requires(std::is_base_of_v<T, S>)54  V8_INLINE Eternal(Isolate* isolate, Local<S> handle) {55    Set(isolate, handle);56  }57 58  // Can only be safely called if already set.59  V8_INLINE Local<T> Get(Isolate* isolate) const {60    // The eternal handle will never go away, so as with the roots, we don't61    // even need to open a handle.62    return Local<T>::FromSlot(slot());63  }64 65  template <class S>66    requires(std::is_base_of_v<T, S>)67  void Set(Isolate* isolate, Local<S> handle) {68    slot() =69        api_internal::Eternalize(isolate, *handle.template UnsafeAs<Value>());70  }71};72 73namespace api_internal {74V8_EXPORT void MakeWeak(internal::Address* location, void* data,75                        WeakCallbackInfo<void>::Callback weak_callback,76                        WeakCallbackType type);77}  // namespace api_internal78 79/**80 * An object reference that is independent of any handle scope.  Where81 * a Local handle only lives as long as the HandleScope in which it was82 * allocated, a PersistentBase handle remains valid until it is explicitly83 * disposed using Reset().84 *85 * A persistent handle contains a reference to a storage cell within86 * the V8 engine which holds an object value and which is updated by87 * the garbage collector whenever the object is moved.  A new storage88 * cell can be created using the constructor or PersistentBase::Reset and89 * existing handles can be disposed using PersistentBase::Reset.90 *91 */92template <class T>93class PersistentBase : public api_internal::IndirectHandleBase {94 public:95  /**96   * If non-empty, destroy the underlying storage cell97   * IsEmpty() will return true after this call.98   */99  V8_INLINE void Reset();100 101  /**102   * If non-empty, destroy the underlying storage cell103   * and create a new one with the contents of other if other is non empty104   */105  template <class S>106  V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);107 108  /**109   * If non-empty, destroy the underlying storage cell110   * and create a new one with the contents of other if other is non empty111   */112  template <class S>113  V8_INLINE void Reset(Isolate* isolate, const PersistentBase<S>& other);114 115  V8_INLINE Local<T> Get(Isolate* isolate) const {116    return Local<T>::New(isolate, *this);117  }118 119  template <class S>120  V8_INLINE bool operator==(const PersistentBase<S>& that) const {121    return internal::HandleHelper::EqualHandles(*this, that);122  }123 124  template <class S>125  V8_INLINE bool operator==(const Local<S>& that) const {126    return internal::HandleHelper::EqualHandles(*this, that);127  }128 129  template <class S>130  V8_INLINE bool operator!=(const PersistentBase<S>& that) const {131    return !operator==(that);132  }133 134  template <class S>135  V8_INLINE bool operator!=(const Local<S>& that) const {136    return !operator==(that);137  }138 139  /**140   * Install a finalization callback on this object.141   * NOTE: There is no guarantee as to *when* or even *if* the callback is142   * invoked. The invocation is performed solely on a best effort basis.143   * As always, GC-based finalization should *not* be relied upon for any144   * critical form of resource management!145   *146   * The callback is supposed to reset the handle. No further V8 API may be147   * called in this callback. In case additional work involving V8 needs to be148   * done, a second callback can be scheduled using149   * WeakCallbackInfo<void>::SetSecondPassCallback.150   */151  template <typename P>152  V8_INLINE void SetWeak(P* parameter,153                         typename WeakCallbackInfo<P>::Callback callback,154                         WeakCallbackType type);155 156  /**157   * Turns this handle into a weak phantom handle without finalization callback.158   * The handle will be reset automatically when the garbage collector detects159   * that the object is no longer reachable.160   */161  V8_INLINE void SetWeak();162 163  template <typename P>164  V8_INLINE P* ClearWeak();165 166  // TODO(dcarney): remove this.167  V8_INLINE void ClearWeak() { ClearWeak<void>(); }168 169  /**170   * Annotates the strong handle with the given label, which is then used by the171   * heap snapshot generator as a name of the edge from the root to the handle.172   * The function does not take ownership of the label and assumes that the173   * label is valid as long as the handle is valid.174   */175  V8_INLINE void AnnotateStrongRetainer(const char* label);176 177  /** Returns true if the handle's reference is weak.  */178  V8_INLINE bool IsWeak() const;179 180  /**181   * Assigns a wrapper class ID to the handle.182   */183  V8_INLINE void SetWrapperClassId(uint16_t class_id);184 185  /**186   * Returns the class ID previously assigned to this handle or 0 if no class ID187   * was previously assigned.188   */189  V8_INLINE uint16_t WrapperClassId() const;190 191  PersistentBase(const PersistentBase& other) = delete;192  void operator=(const PersistentBase&) = delete;193 194 private:195  friend class Isolate;196  friend class Utils;197  template <class F>198  friend class Local;199  template <class F1, class F2>200  friend class Persistent;201  template <class F>202  friend class Global;203  template <class F>204  friend class PersistentBase;205  template <class F>206  friend class ReturnValue;207  template <class F1, class F2, class F3>208  friend class PersistentValueMapBase;209  friend class Object;210  friend class internal::ValueHelper;211 212  V8_INLINE PersistentBase() = default;213 214  V8_INLINE explicit PersistentBase(internal::Address* location)215      : IndirectHandleBase(location) {}216 217  V8_INLINE static internal::Address* New(Isolate* isolate, T* that);218};219 220/**221 * Default traits for Persistent. This class does not allow222 * use of the copy constructor or assignment operator.223 * At present kResetInDestructor is not set, but that will change in a future224 * version.225 */226template <class T>227class NonCopyablePersistentTraits {228 public:229  using NonCopyablePersistent = Persistent<T, NonCopyablePersistentTraits<T>>;230  static const bool kResetInDestructor = false;231  template <class S, class M>232  V8_INLINE static void Copy(const Persistent<S, M>& source,233                             NonCopyablePersistent* dest) {234    static_assert(sizeof(S) < 0,235                  "NonCopyablePersistentTraits::Copy is not instantiable");236  }237};238 239/**240 * A PersistentBase which allows copy and assignment.241 *242 * Copy, assignment and destructor behavior is controlled by the traits243 * class M.244 *245 * CAVEAT: Persistent objects do not have proper destruction behavior by default246 * and as such will leak the object without explicit clear. Consider using247 * `v8::Global` instead which has proper destruction and move semantics.248 */249template <class T, class M>250class Persistent : public PersistentBase<T> {251 public:252  /**253   * A Persistent with no storage cell.254   */255  V8_INLINE Persistent() = default;256 257  /**258   * Construct a Persistent from a Local with automatic up casting.259   * When the Local is non-empty, a new storage cell is created260   * pointing to the same object, and no flags are set.261   */262  template <class S>263    requires(std::is_base_of_v<T, S>)264  V8_INLINE Persistent(Isolate* isolate, Local<S> that)265      : PersistentBase<T>(266            PersistentBase<T>::New(isolate, that.template value<S>())) {}267 268  /**269   * Construct a Persistent from a Persistent with automatic up casting.270   * When the Persistent is non-empty, a new storage cell is created271   * pointing to the same object, and no flags are set.272   */273  template <class S, class M2>274    requires(std::is_base_of_v<T, S>)275  V8_INLINE Persistent(Isolate* isolate, const Persistent<S, M2>& that)276      : PersistentBase<T>(277            PersistentBase<T>::New(isolate, that.template value<S>())) {}278 279  /**280   * The copy constructors and assignment operator create a Persistent281   * exactly as the Persistent constructor, but the Copy function from the282   * traits class is called, allowing the setting of flags based on the283   * copied Persistent.284   */285  V8_INLINE Persistent(const Persistent& that) : PersistentBase<T>() {286    Copy(that);287  }288  template <class S, class M2>289  V8_INLINE Persistent(const Persistent<S, M2>& that) : PersistentBase<T>() {290    Copy(that);291  }292  V8_INLINE Persistent& operator=(const Persistent& that) {293    Copy(that);294    return *this;295  }296  template <class S, class M2>297  V8_INLINE Persistent& operator=(const Persistent<S, M2>& that) {298    Copy(that);299    return *this;300  }301 302  /**303   * The destructor will dispose the Persistent based on the304   * kResetInDestructor flags in the traits class.  Since not calling dispose305   * can result in a memory leak, it is recommended to always set this flag.306   */307  V8_INLINE ~Persistent() {308    if (M::kResetInDestructor) this->Reset();309  }310 311  // TODO(dcarney): this is pretty useless, fix or remove312  template <class S, class M2>313  V8_INLINE static Persistent<T, M>& Cast(const Persistent<S, M2>& that) {314#ifdef V8_ENABLE_CHECKS315    // If we're going to perform the type check then we have to check316    // that the handle isn't empty before doing the checked cast.317    if (!that.IsEmpty()) T::Cast(that.template value<S>());318#endif319    return reinterpret_cast<Persistent<T, M>&>(320        const_cast<Persistent<S, M2>&>(that));321  }322 323  // TODO(dcarney): this is pretty useless, fix or remove324  template <class S, class M2>325  V8_INLINE Persistent<S, M2>& As() const {326    return Persistent<S, M2>::Cast(*this);327  }328 329 private:330  friend class Isolate;331  friend class Utils;332  template <class F>333  friend class Local;334  template <class F1, class F2>335  friend class Persistent;336  template <class F>337  friend class ReturnValue;338 339  template <class S, class M2>340  V8_INLINE void Copy(const Persistent<S, M2>& that);341};342 343/**344 * A PersistentBase which has move semantics.345 *346 * Note: Persistent class hierarchy is subject to future changes.347 */348template <class T>349class Global : public PersistentBase<T> {350 public:351  /**352   * A Global with no storage cell.353   */354  V8_INLINE Global() = default;355 356  /**357   * Construct a Global from a Local with automatic up casting.358   * When the Local is non-empty, a new storage cell is created359   * pointing to the same object, and no flags are set.360   */361  template <class S>362    requires(std::is_base_of_v<T, S>)363  V8_INLINE Global(Isolate* isolate, Local<S> that)364      : PersistentBase<T>(365            PersistentBase<T>::New(isolate, that.template value<S>())) {}366 367  /**368   * Construct a Global from a PersistentBase with automatic up casting.369   * When the Persistent is non-empty, a new storage cell is created370   * pointing to the same object, and no flags are set.371   */372  template <class S>373    requires(std::is_base_of_v<T, S>)374  V8_INLINE Global(Isolate* isolate, const PersistentBase<S>& that)375      : PersistentBase<T>(376            PersistentBase<T>::New(isolate, that.template value<S>())) {}377 378  /**379   * Move constructor.380   */381  V8_INLINE Global(Global&& other);382 383  V8_INLINE ~Global() { this->Reset(); }384 385  /**386   * Move via assignment.387   */388  template <class S>389  V8_INLINE Global& operator=(Global<S>&& rhs);390 391  /**392   * Pass allows returning uniques from functions, etc.393   */394  Global Pass() { return static_cast<Global&&>(*this); }395 396  /*397   * For compatibility with Chromium's base::Bind (base::Passed).398   */399  using MoveOnlyTypeForCPP03 = void;400 401  Global(const Global&) = delete;402  void operator=(const Global&) = delete;403 404 private:405  template <class F>406  friend class ReturnValue;407};408 409// UniquePersistent is an alias for Global for historical reason.410template <class T>411using UniquePersistent = Global<T>;412 413/**414 * Interface for iterating through all the persistent handles in the heap.415 */416class V8_EXPORT PersistentHandleVisitor {417 public:418  virtual ~PersistentHandleVisitor() = default;419  virtual void VisitPersistentHandle(Persistent<Value>* value,420                                     uint16_t class_id) {}421};422 423template <class T>424internal::Address* PersistentBase<T>::New(Isolate* isolate, T* that) {425  if (internal::ValueHelper::IsEmpty(that)) return nullptr;426  return api_internal::GlobalizeReference(427      reinterpret_cast<internal::Isolate*>(isolate),428      internal::ValueHelper::ValueAsAddress(that));429}430 431template <class T, class M>432template <class S, class M2>433void Persistent<T, M>::Copy(const Persistent<S, M2>& that) {434  static_assert(std::is_base_of<T, S>::value, "type check");435  this->Reset();436  if (that.IsEmpty()) return;437  this->slot() = api_internal::CopyGlobalReference(that.slot());438  M::Copy(that, this);439}440 441template <class T>442bool PersistentBase<T>::IsWeak() const {443  using I = internal::Internals;444  if (this->IsEmpty()) return false;445  return I::GetNodeState(this->slot()) == I::kNodeStateIsWeakValue;446}447 448template <class T>449void PersistentBase<T>::Reset() {450  if (this->IsEmpty()) return;451  api_internal::DisposeGlobal(this->slot());452  this->Clear();453}454 455/**456 * If non-empty, destroy the underlying storage cell457 * and create a new one with the contents of other if other is non empty458 */459template <class T>460template <class S>461void PersistentBase<T>::Reset(Isolate* isolate, const Local<S>& other) {462  static_assert(std::is_base_of<T, S>::value, "type check");463  Reset();464  if (other.IsEmpty()) return;465  this->slot() = New(isolate, *other);466}467 468/**469 * If non-empty, destroy the underlying storage cell470 * and create a new one with the contents of other if other is non empty471 */472template <class T>473template <class S>474void PersistentBase<T>::Reset(Isolate* isolate,475                              const PersistentBase<S>& other) {476  static_assert(std::is_base_of<T, S>::value, "type check");477  Reset();478  if (other.IsEmpty()) return;479  this->slot() = New(isolate, other.template value<S>());480}481 482template <class T>483template <typename P>484V8_INLINE void PersistentBase<T>::SetWeak(485    P* parameter, typename WeakCallbackInfo<P>::Callback callback,486    WeakCallbackType type) {487  using Callback = WeakCallbackInfo<void>::Callback;488#if (__GNUC__ >= 8) && !defined(__clang__)489#pragma GCC diagnostic push490#pragma GCC diagnostic ignored "-Wcast-function-type"491#endif492#if __clang__493#pragma clang diagnostic push494#pragma clang diagnostic ignored "-Wcast-function-type"495#endif496  api_internal::MakeWeak(this->slot(), parameter,497                         reinterpret_cast<Callback>(callback), type);498#if __clang__499#pragma clang diagnostic pop500#endif501#if (__GNUC__ >= 8) && !defined(__clang__)502#pragma GCC diagnostic pop503#endif504}505 506template <class T>507void PersistentBase<T>::SetWeak() {508  api_internal::MakeWeak(&this->slot());509}510 511template <class T>512template <typename P>513P* PersistentBase<T>::ClearWeak() {514  return reinterpret_cast<P*>(api_internal::ClearWeak(this->slot()));515}516 517template <class T>518void PersistentBase<T>::AnnotateStrongRetainer(const char* label) {519  api_internal::AnnotateStrongRetainer(this->slot(), label);520}521 522template <class T>523void PersistentBase<T>::SetWrapperClassId(uint16_t class_id) {524  using I = internal::Internals;525  if (this->IsEmpty()) return;526  uint8_t* addr = reinterpret_cast<uint8_t*>(slot()) + I::kNodeClassIdOffset;527  *reinterpret_cast<uint16_t*>(addr) = class_id;528}529 530template <class T>531uint16_t PersistentBase<T>::WrapperClassId() const {532  using I = internal::Internals;533  if (this->IsEmpty()) return 0;534  uint8_t* addr = reinterpret_cast<uint8_t*>(slot()) + I::kNodeClassIdOffset;535  return *reinterpret_cast<uint16_t*>(addr);536}537 538template <class T>539Global<T>::Global(Global&& other) : PersistentBase<T>(other.slot()) {540  if (!other.IsEmpty()) {541    api_internal::MoveGlobalReference(&other.slot(), &this->slot());542    other.Clear();543  }544}545 546template <class T>547template <class S>548Global<T>& Global<T>::operator=(Global<S>&& rhs) {549  static_assert(std::is_base_of<T, S>::value, "type check");550  if (this != &rhs) {551    this->Reset();552    if (!rhs.IsEmpty()) {553      this->slot() = rhs.slot();554      api_internal::MoveGlobalReference(&rhs.slot(), &this->slot());555      rhs.Clear();556    }557  }558  return *this;559}560 561}  // namespace v8562 563#endif  // INCLUDE_V8_PERSISTENT_HANDLE_H_564