v8-local-handle.h

Go to the documentation of this file.

// Copyright 2021 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
 
#ifndef INCLUDE_V8_LOCAL_HANDLE_H_
#define INCLUDE_V8_LOCAL_HANDLE_H_
 
#include <stddef.h>
 
#include <type_traits>
#include <vector>
 
#include "v8-handle-base.h"  // NOLINT(build/include_directory)
#include "v8-internal.h"     // NOLINT(build/include_directory)
 
namespace v8 {
 
template <class T>
class LocalBase;
template <class T>
class Local;
template <class T>
class LocalVector;
template <class F>
class MaybeLocal;
 
template <class T>
class Eternal;
template <class T>
class Global;
 
template <class T>
class NonCopyablePersistentTraits;
template <class T>
class PersistentBase;
template <class T, class M = NonCopyablePersistentTraits<T>>
class Persistent;
 
class TracedReferenceBase;
template <class T>
class BasicTracedReference;
template <class F>
class TracedReference;
 
class Boolean;
class Context;
class EscapableHandleScope;
template <class F>
class FunctionCallbackInfo;
class Isolate;
class Object;
template <class F1, class F2, class F3>
class PersistentValueMapBase;
class Primitive;
class Private;
template <class F>
class PropertyCallbackInfo;
template <class F>
class ReturnValue;
class String;
template <class F>
class Traced;
class TypecheckWitness;
class Utils;
 
namespace debug {
class ConsoleCallArguments;
}
 
namespace internal {
template <typename T>
class CustomArguments;
template <typename T>
class LocalUnchecked;
class SamplingHeapProfiler;
}  // namespace internal
 
namespace api_internal {
// Called when ToLocalChecked is called on an empty Local.
V8_EXPORT void ToLocalEmpty();
}  // namespace api_internal

class V8_EXPORT V8_NODISCARD HandleScope {
 public:
  explicit HandleScope(Isolate* isolate);
 
  ~HandleScope();

  static int NumberOfHandles(Isolate* isolate);
 
  V8_INLINE Isolate* GetIsolate() const {
    return reinterpret_cast<Isolate*>(i_isolate_);
  }
 
  HandleScope(const HandleScope&) = delete;
  void operator=(const HandleScope&) = delete;
 
  static internal::Address* CreateHandleForCurrentIsolate(
      internal::Address value);
 
 protected:
  V8_INLINE HandleScope() = default;
 
  void Initialize(Isolate* isolate);
 
  static internal::Address* CreateHandle(internal::Isolate* i_isolate,
                                         internal::Address value);
 
 private:
  // Declaring operator new and delete as deleted is not spec compliant.
  // Therefore declare them private instead to disable dynamic alloc
  void* operator new(size_t size);
  void* operator new[](size_t size);
  void operator delete(void*, size_t);
  void operator delete[](void*, size_t);
 
  internal::Isolate* i_isolate_;
  internal::Address* prev_next_;
  internal::Address* prev_limit_;
#ifdef V8_ENABLE_CHECKS
  int scope_level_ = 0;
#endif
 
  // LocalBase<T>::New uses CreateHandle with an Isolate* parameter.
  template <typename T>
  friend class LocalBase;
 
  // Object::GetInternalField and Context::GetEmbedderData use CreateHandle with
  // a HeapObject in their shortcuts.
  friend class Object;
  friend class Context;
};

#ifdef V8_ENABLE_DIRECT_HANDLE
 
template <typename T>
class LocalBase : public api_internal::DirectHandleBase {
 protected:
  template <class F>
  friend class Local;
 
  V8_INLINE LocalBase() = default;
 
  V8_INLINE explicit LocalBase(internal::Address ptr) : DirectHandleBase(ptr) {}
 
  template <typename S>
  V8_INLINE LocalBase(const LocalBase<S>& other) : DirectHandleBase(other) {}
 
  V8_INLINE static LocalBase<T> New(Isolate* isolate, internal::Address value) {
    return LocalBase<T>(value);
  }
 
  V8_INLINE static LocalBase<T> New(Isolate* isolate, T* that) {
    return LocalBase<T>::New(isolate,
                             internal::ValueHelper::ValueAsAddress(that));
  }
 
  V8_INLINE static LocalBase<T> FromSlot(internal::Address* slot) {
    if (slot == nullptr) return LocalBase<T>();
    return LocalBase<T>(*slot);
  }
 
  V8_INLINE static LocalBase<T> FromRepr(
      internal::ValueHelper::InternalRepresentationType repr) {
    return LocalBase<T>(repr);
  }
};
 
#else  // !V8_ENABLE_DIRECT_HANDLE
 
template <typename T>
class LocalBase : public api_internal::IndirectHandleBase {
 protected:
  template <class F>
  friend class Local;
 
  V8_INLINE LocalBase() = default;
 
  V8_INLINE explicit LocalBase(internal::Address* location)
      : IndirectHandleBase(location) {}
 
  template <typename S>
  V8_INLINE LocalBase(const LocalBase<S>& other) : IndirectHandleBase(other) {}
 
  V8_INLINE static LocalBase<T> New(Isolate* isolate, internal::Address value) {
    return LocalBase(HandleScope::CreateHandle(
        reinterpret_cast<internal::Isolate*>(isolate), value));
  }
 
  V8_INLINE static LocalBase<T> New(Isolate* isolate, T* that) {
    if (internal::ValueHelper::IsEmpty(that)) return LocalBase<T>();
    return LocalBase<T>::New(isolate,
                             internal::ValueHelper::ValueAsAddress(that));
  }
 
  V8_INLINE static LocalBase<T> FromSlot(internal::Address* slot) {
    return LocalBase<T>(slot);
  }
 
  V8_INLINE static LocalBase<T> FromRepr(
      internal::ValueHelper::InternalRepresentationType repr) {
    return LocalBase<T>(repr);
  }
};
 
#endif  // V8_ENABLE_DIRECT_HANDLE

template <class T>
class V8_TRIVIAL_ABI Local : public LocalBase<T>,
#ifdef V8_ENABLE_LOCAL_OFF_STACK_CHECK
                             public api_internal::StackAllocated<true>
#else
                             public api_internal::StackAllocated<false>
#endif
{
 public:
  V8_INLINE Local() = default;

  template <class S>
    requires std::is_base_of_v<T, S>
  V8_INLINE Local(Local<S> that) : LocalBase<T>(that) {}
 
  V8_INLINE T* operator->() const { return this->template value<T>(); }
 
  V8_INLINE T* operator*() const { return this->operator->(); }

 
  template <class S>
  V8_INLINE bool operator==(const Local<S>& that) const {
    return internal::HandleHelper::EqualHandles(*this, that);
  }
 
  template <class S>
  V8_INLINE bool operator==(const PersistentBase<S>& that) const {
    return internal::HandleHelper::EqualHandles(*this, that);
  }
 
  template <class S>
  V8_INLINE bool operator!=(const Local<S>& that) const {
    return !operator==(that);
  }
 
  template <class S>
  V8_INLINE bool operator!=(const Persistent<S>& that) const {
    return !operator==(that);
  }

  template <class S>
  V8_INLINE static Local<T> Cast(Local<S> that) {
#ifdef V8_ENABLE_CHECKS
    // If we're going to perform the type check then we have to check
    // that the handle isn't empty before doing the checked cast.
    if (that.IsEmpty()) return Local<T>();
    T::Cast(that.template value<S>());
#endif
    return Local<T>(LocalBase<T>(that));
  }

  template <class S>
  V8_INLINE Local<S> As() const {
    return Local<S>::Cast(*this);
  }

  V8_INLINE static Local<T> New(Isolate* isolate, Local<T> that) {
    return New(isolate, that.template value<T, true>());
  }
 
  V8_INLINE static Local<T> New(Isolate* isolate,
                                const PersistentBase<T>& that) {
    return New(isolate, that.template value<T, true>());
  }
 
  V8_INLINE static Local<T> New(Isolate* isolate,
                                const BasicTracedReference<T>& that) {
    return New(isolate, that.template value<T, true>());
  }
 
 private:
  friend class TracedReferenceBase;
  friend class Utils;
  template <class F>
  friend class Eternal;
  template <class F>
  friend class Global;
  template <class F>
  friend class Local;
  template <class F>
  friend class MaybeLocal;
  template <class F, class M>
  friend class Persistent;
  template <class F>
  friend class FunctionCallbackInfo;
  template <class F>
  friend class PropertyCallbackInfo;
  friend class String;
  friend class Object;
  friend class Context;
  friend class Isolate;
  friend class Private;
  template <class F>
  friend class internal::CustomArguments;
  friend Local<Primitive> Undefined(Isolate* isolate);
  friend Local<Primitive> Null(Isolate* isolate);
  friend Local<Boolean> True(Isolate* isolate);
  friend Local<Boolean> False(Isolate* isolate);
  friend class HandleScope;
  friend class EscapableHandleScope;
  friend class InternalEscapableScope;
  template <class F1, class F2, class F3>
  friend class PersistentValueMapBase;
  template <class F>
  friend class ReturnValue;
  template <class F>
  friend class Traced;
  friend class internal::SamplingHeapProfiler;
  friend class internal::HandleHelper;
  friend class debug::ConsoleCallArguments;
  friend class internal::LocalUnchecked<T>;
 
  explicit Local(no_checking_tag do_not_check)
      : LocalBase<T>(), StackAllocated(do_not_check) {}
  explicit Local(const Local<T>& other, no_checking_tag do_not_check)
      : LocalBase<T>(other), StackAllocated(do_not_check) {}
 
  V8_INLINE explicit Local(const LocalBase<T>& other) : LocalBase<T>(other) {}
 
  V8_INLINE static Local<T> FromRepr(
      internal::ValueHelper::InternalRepresentationType repr) {
    return Local<T>(LocalBase<T>::FromRepr(repr));
  }
 
  V8_INLINE static Local<T> FromSlot(internal::Address* slot) {
    return Local<T>(LocalBase<T>::FromSlot(slot));
  }
 
#ifdef V8_ENABLE_DIRECT_HANDLE
  friend class TypecheckWitness;
 
  V8_INLINE static Local<T> FromAddress(internal::Address ptr) {
    return Local<T>(LocalBase<T>(ptr));
  }
#endif  // V8_ENABLE_DIRECT_HANDLE
 
  V8_INLINE static Local<T> New(Isolate* isolate, internal::Address value) {
    return Local<T>(LocalBase<T>::New(isolate, value));
  }
 
  V8_INLINE static Local<T> New(Isolate* isolate, T* that) {
    return Local<T>(LocalBase<T>::New(isolate, that));
  }
 
  // Unsafe cast, should be avoided.
  template <class S>
  V8_INLINE Local<S> UnsafeAs() const {
    return Local<S>(LocalBase<S>(*this));
  }
};
 
namespace internal {
// A local variant that is suitable for off-stack allocation.
// Used internally by LocalVector<T>. Not to be used directly!
template <typename T>
class V8_TRIVIAL_ABI LocalUnchecked : public Local<T> {
 public:
  LocalUnchecked() : Local<T>(Local<T>::do_not_check) {}
 
#if defined(V8_ENABLE_LOCAL_OFF_STACK_CHECK) && V8_HAS_ATTRIBUTE_TRIVIAL_ABI
  // In this case, the check is also enforced in the copy constructor and we
  // need to suppress it.
  LocalUnchecked(
      const LocalUnchecked& other) noexcept  // NOLINT(runtime/explicit)
      : Local<T>(other, Local<T>::do_not_check) {}
  LocalUnchecked& operator=(const LocalUnchecked&) noexcept = default;
#endif
 
  // Implicit conversion from Local.
  LocalUnchecked(const Local<T>& other) noexcept  // NOLINT(runtime/explicit)
      : Local<T>(other, Local<T>::do_not_check) {}
};
 
#ifdef V8_ENABLE_DIRECT_HANDLE
// Off-stack allocated direct locals must be registered as strong roots.
// For off-stack indirect locals, this is not necessary.
 
template <typename T>
class StrongRootAllocator<LocalUnchecked<T>> : public StrongRootAllocatorBase {
 public:
  using value_type = LocalUnchecked<T>;
  static_assert(std::is_standard_layout_v<value_type>);
  static_assert(sizeof(value_type) == sizeof(Address));
 
  template <typename HeapOrIsolateT>
  explicit StrongRootAllocator(HeapOrIsolateT* heap_or_isolate)
      : StrongRootAllocatorBase(heap_or_isolate) {}
  template <typename U>
  StrongRootAllocator(const StrongRootAllocator<U>& other) noexcept
      : StrongRootAllocatorBase(other) {}
 
  value_type* allocate(size_t n) {
    return reinterpret_cast<value_type*>(allocate_impl(n));
  }
  void deallocate(value_type* p, size_t n) noexcept {
    return deallocate_impl(reinterpret_cast<Address*>(p), n);
  }
};
#endif  // V8_ENABLE_DIRECT_HANDLE
}  // namespace internal
 
template <typename T>
class LocalVector {
 private:
  using element_type = internal::LocalUnchecked<T>;
 
#ifdef V8_ENABLE_DIRECT_HANDLE
  using allocator_type = internal::StrongRootAllocator<element_type>;
 
  static allocator_type make_allocator(Isolate* isolate) noexcept {
    return allocator_type(isolate);
  }
#else
  using allocator_type = std::allocator<element_type>;
 
  static allocator_type make_allocator(Isolate* isolate) noexcept {
    return allocator_type();
  }
#endif  // V8_ENABLE_DIRECT_HANDLE
 
  using vector_type = std::vector<element_type, allocator_type>;
 
 public:
  using value_type = Local<T>;
  using reference = value_type&;
  using const_reference = const value_type&;
  using size_type = size_t;
  using difference_type = ptrdiff_t;
  using iterator =
      internal::WrappedIterator<typename vector_type::iterator, Local<T>>;
  using const_iterator =
      internal::WrappedIterator<typename vector_type::const_iterator,
                                const Local<T>>;
 
  explicit LocalVector(Isolate* isolate) : backing_(make_allocator(isolate)) {}
  LocalVector(Isolate* isolate, size_t n)
      : backing_(n, make_allocator(isolate)) {}
  explicit LocalVector(Isolate* isolate, std::initializer_list<Local<T>> init)
      : backing_(make_allocator(isolate)) {
    if (init.size() == 0) return;
    backing_.reserve(init.size());
    backing_.insert(backing_.end(), init.begin(), init.end());
  }
 
  iterator begin() noexcept { return iterator(backing_.begin()); }
  const_iterator begin() const noexcept {
    return const_iterator(backing_.begin());
  }
  iterator end() noexcept { return iterator(backing_.end()); }
  const_iterator end() const noexcept { return const_iterator(backing_.end()); }
 
  size_t size() const noexcept { return backing_.size(); }
  bool empty() const noexcept { return backing_.empty(); }
  void reserve(size_t n) { backing_.reserve(n); }
  void shrink_to_fit() { backing_.shrink_to_fit(); }
 
  Local<T>& operator[](size_t n) { return backing_[n]; }
  const Local<T>& operator[](size_t n) const { return backing_[n]; }
 
  Local<T>& at(size_t n) { return backing_.at(n); }
  const Local<T>& at(size_t n) const { return backing_.at(n); }
 
  Local<T>& front() { return backing_.front(); }
  const Local<T>& front() const { return backing_.front(); }
  Local<T>& back() { return backing_.back(); }
  const Local<T>& back() const { return backing_.back(); }
 
  Local<T>* data() noexcept { return backing_.data(); }
  const Local<T>* data() const noexcept { return backing_.data(); }
 
  iterator insert(const_iterator pos, const Local<T>& value) {
    return iterator(backing_.insert(pos.base(), value));
  }
 
  template <typename InputIt>
  iterator insert(const_iterator pos, InputIt first, InputIt last) {
    return iterator(backing_.insert(pos.base(), first, last));
  }
 
  iterator insert(const_iterator pos, std::initializer_list<Local<T>> init) {
    return iterator(backing_.insert(pos.base(), init.begin(), init.end()));
  }
 
  LocalVector<T>& operator=(std::initializer_list<Local<T>> init) {
    backing_.clear();
    backing_.reserve(init.size());
    backing_.insert(backing_.end(), init.begin(), init.end());
    return *this;
  }
 
  void push_back(const Local<T>& x) { backing_.push_back(x); }
  void pop_back() { backing_.pop_back(); }
 
  template <typename... Args>
  void emplace_back(Args&&... args) {
    backing_.push_back(value_type{std::forward<Args>(args)...});
  }
 
  void clear() noexcept { backing_.clear(); }
  void resize(size_t n) { backing_.resize(n); }
  void swap(LocalVector<T>& other) { backing_.swap(other.backing_); }
 
  friend bool operator==(const LocalVector<T>& x, const LocalVector<T>& y) {
    return x.backing_ == y.backing_;
  }
  friend bool operator!=(const LocalVector<T>& x, const LocalVector<T>& y) {
    return x.backing_ != y.backing_;
  }
  friend bool operator<(const LocalVector<T>& x, const LocalVector<T>& y) {
    return x.backing_ < y.backing_;
  }
  friend bool operator>(const LocalVector<T>& x, const LocalVector<T>& y) {
    return x.backing_ > y.backing_;
  }
  friend bool operator<=(const LocalVector<T>& x, const LocalVector<T>& y) {
    return x.backing_ <= y.backing_;
  }
  friend bool operator>=(const LocalVector<T>& x, const LocalVector<T>& y) {
    return x.backing_ >= y.backing_;
  }
 
 private:
  vector_type backing_;
};
 
#if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
// Handle is an alias for Local for historical reasons.
template <class T>
using Handle = Local<T>;
#endif

template <class T>
class MaybeLocal {
 public:
  V8_INLINE MaybeLocal() = default;
  template <class S>
    requires std::is_base_of_v<T, S>
  V8_INLINE MaybeLocal(Local<S> that) : local_(that) {}
  template <class S>
    requires std::is_base_of_v<T, S>
  V8_INLINE MaybeLocal(MaybeLocal<S> that) : local_(that.local_) {}
 
  V8_INLINE bool IsEmpty() const { return local_.IsEmpty(); }

  template <class S>
  V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {
    *out = local_;
    return !IsEmpty();
  }

  V8_INLINE Local<T> ToLocalChecked() {
    if (V8_UNLIKELY(IsEmpty())) api_internal::ToLocalEmpty();
    return local_;
  }

  template <class S>
  V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
    return IsEmpty() ? default_value : Local<S>(local_);
  }

  template <class S>
  V8_INLINE static MaybeLocal<T> Cast(MaybeLocal<S> that) {
    return MaybeLocal<T>{Local<T>::Cast(that.local_)};
  }

  template <class S>
  V8_INLINE MaybeLocal<S> As() const {
    return MaybeLocal<S>::Cast(*this);
  }
 
 private:
  Local<T> local_;
 
  template <typename S>
  friend class MaybeLocal;
};

class V8_EXPORT V8_NODISCARD EscapableHandleScopeBase : public HandleScope {
 public:
  explicit EscapableHandleScopeBase(Isolate* isolate);
  V8_INLINE ~EscapableHandleScopeBase() = default;
 
  EscapableHandleScopeBase(const EscapableHandleScopeBase&) = delete;
  void operator=(const EscapableHandleScopeBase&) = delete;
  void* operator new(size_t size) = delete;
  void* operator new[](size_t size) = delete;
  void operator delete(void*, size_t) = delete;
  void operator delete[](void*, size_t) = delete;
 
 protected:
  internal::Address* EscapeSlot(internal::Address* escape_value);
 
 private:
  internal::Address* escape_slot_;
};
 
class V8_EXPORT V8_NODISCARD EscapableHandleScope
    : public EscapableHandleScopeBase {
 public:
  explicit EscapableHandleScope(Isolate* isolate)
      : EscapableHandleScopeBase(isolate) {}
  V8_INLINE ~EscapableHandleScope() = default;
  template <class T>
  V8_INLINE Local<T> Escape(Local<T> value) {
#ifdef V8_ENABLE_DIRECT_HANDLE
    return value;
#else
    if (value.IsEmpty()) return value;
    return Local<T>::FromSlot(EscapeSlot(value.slot()));
#endif
  }
 
  template <class T>
  V8_INLINE MaybeLocal<T> EscapeMaybe(MaybeLocal<T> value) {
    return Escape(value.FromMaybe(Local<T>()));
  }
};

class V8_EXPORT V8_NODISCARD SealHandleScope {
 public:
  explicit SealHandleScope(Isolate* isolate);
  ~SealHandleScope();
 
  SealHandleScope(const SealHandleScope&) = delete;
  void operator=(const SealHandleScope&) = delete;
  void* operator new(size_t size) = delete;
  void* operator new[](size_t size) = delete;
  void operator delete(void*, size_t) = delete;
  void operator delete[](void*, size_t) = delete;
 
 private:
  internal::Isolate* const i_isolate_;
  internal::Address* prev_limit_;
  int prev_sealed_level_;
};
 
}  // namespace v8
 
#endif  // INCLUDE_V8_LOCAL_HANDLE_H_