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 "v8-internal.h"  // NOLINT(build/include_directory)
 
namespace v8 {
 
class Boolean;
template <class T>
class BasicTracedReference;
class Context;
class EscapableHandleScope;
template <class F>
class Eternal;
template <class F>
class FunctionCallbackInfo;
class Isolate;
template <class F>
class MaybeLocal;
template <class T>
class NonCopyablePersistentTraits;
class Object;
template <class T, class M = NonCopyablePersistentTraits<T>>
class Persistent;
template <class T>
class PersistentBase;
template <class F1, class F2, class F3>
class PersistentValueMapBase;
template <class F1, class F2>
class PersistentValueVector;
class Primitive;
class Private;
template <class F>
class PropertyCallbackInfo;
template <class F>
class ReturnValue;
class String;
template <class F>
class Traced;
template <class F>
class TracedReference;
class TracedReferenceBase;
class Utils;
 
namespace debug {
class ConsoleCallArguments;
}
 
namespace internal {
template <typename T>
class CustomArguments;
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_;
 
  // Local::New uses CreateHandle with an Isolate* parameter.
  template <class F>
  friend class Local;
 
  // Object::GetInternalField and Context::GetEmbedderData use CreateHandle with
  // a HeapObject in their shortcuts.
  friend class Object;
  friend class Context;
};
 
namespace internal {
 
class HandleHelper final {
 public:
  template <typename T1, typename T2>
  V8_INLINE static bool EqualHandles(const T1& lhs, const T2& rhs) {
    if (lhs.IsEmpty()) return rhs.IsEmpty();
    if (rhs.IsEmpty()) return false;
    return lhs.address() == rhs.address();
  }
};
 
}  // namespace internal
 
template <class T>
class Local {
 public:
  V8_INLINE Local() : val_(internal::ValueHelper::EmptyValue<T>()) {}
 
  template <class S>
  V8_INLINE Local(Local<S> that) : val_(reinterpret_cast<T*>(*that)) {
    static_assert(std::is_base_of<T, S>::value, "type check");
  }
 
  V8_INLINE bool IsEmpty() const {
    return val_ == internal::ValueHelper::EmptyValue<T>();
  }
 
  V8_INLINE void Clear() { val_ = internal::ValueHelper::EmptyValue<T>(); }
 
  V8_INLINE T* operator->() const { return val_; }
 
  V8_INLINE T* operator*() const { return val_; }
 
  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>();
#endif
    return Local<T>(T::Cast(*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.val_);
  }
 
  V8_INLINE static Local<T> New(Isolate* isolate,
                                const PersistentBase<T>& that) {
    return New(isolate, internal::ValueHelper::SlotAsValue<T>(that.val_));
  }
 
  V8_INLINE static Local<T> New(Isolate* isolate,
                                const BasicTracedReference<T>& that) {
    return New(isolate, internal::ValueHelper::SlotAsValue<T>(*that));
  }
 
 private:
  friend class TracedReferenceBase;
  friend class Utils;
  template <class F>
  friend class Eternal;
  template <class F>
  friend class MaybeLocal;
  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;
  template <class F1, class F2, class F3>
  friend class PersistentValueMapBase;
  template <class F1, class F2>
  friend class PersistentValueVector;
  template <class F>
  friend class ReturnValue;
  template <class F>
  friend class Traced;
  friend class internal::SamplingHeapProfiler;
  friend class internal::HandleHelper;
  friend class debug::ConsoleCallArguments;
 
  explicit V8_INLINE Local(T* that) : val_(that) {}
 
  V8_INLINE internal::Address address() const {
    return internal::ValueHelper::ValueAsAddress(val_);
  }
 
  V8_INLINE static Local<T> FromSlot(internal::Address* slot) {
    return Local<T>(internal::ValueHelper::SlotAsValue<T>(slot));
  }
 
  V8_INLINE static Local<T> New(Isolate* isolate, T* that) {
#ifdef V8_ENABLE_CONSERVATIVE_STACK_SCANNING
    return Local<T>(that);
#else
    if (that == nullptr) return Local<T>();
    internal::Address* p = reinterpret_cast<internal::Address*>(that);
    return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
        reinterpret_cast<internal::Isolate*>(isolate), *p)));
#endif
  }
 
  T* val_;
};
 
#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() : val_(internal::ValueHelper::EmptyValue<T>()) {}
  template <class S>
  V8_INLINE MaybeLocal(Local<S> that) : val_(reinterpret_cast<T*>(*that)) {
    static_assert(std::is_base_of<T, S>::value, "type check");
  }
 
  V8_INLINE bool IsEmpty() const {
    return val_ == internal::ValueHelper::EmptyValue<T>();
  }
 
  template <class S>
  V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {
    out->val_ = IsEmpty() ? internal::ValueHelper::EmptyValue<T>() : this->val_;
    return !IsEmpty();
  }
 
  V8_INLINE Local<T> ToLocalChecked() {
    if (V8_UNLIKELY(IsEmpty())) api_internal::ToLocalEmpty();
    return Local<T>(val_);
  }
 
  template <class S>
  V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
    return IsEmpty() ? default_value : Local<S>(val_);
  }
 
 private:
  T* val_;
};
 
class V8_EXPORT V8_NODISCARD EscapableHandleScope : public HandleScope {
 public:
  explicit EscapableHandleScope(Isolate* isolate);
  V8_INLINE ~EscapableHandleScope() = default;
 
  template <class T>
  V8_INLINE Local<T> Escape(Local<T> value) {
#ifdef V8_ENABLE_CONSERVATIVE_STACK_SCANNING
    return value;
#else
    internal::Address* slot =
        Escape(reinterpret_cast<internal::Address*>(*value));
    return Local<T>(reinterpret_cast<T*>(slot));
#endif
  }
 
  template <class T>
  V8_INLINE MaybeLocal<T> EscapeMaybe(MaybeLocal<T> value) {
    return Escape(value.FromMaybe(Local<T>()));
  }
 
  EscapableHandleScope(const EscapableHandleScope&) = delete;
  void operator=(const EscapableHandleScope&) = delete;
 
 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::Address* Escape(internal::Address* escape_value);
  internal::Address* escape_slot_;
};
 
class V8_EXPORT V8_NODISCARD SealHandleScope {
 public:
  explicit SealHandleScope(Isolate* isolate);
  ~SealHandleScope();
 
  SealHandleScope(const SealHandleScope&) = delete;
  void operator=(const SealHandleScope&) = delete;
 
 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* const i_isolate_;
  internal::Address* prev_limit_;
  int prev_sealed_level_;
};
 
}  // namespace v8
 
#endif  // INCLUDE_V8_LOCAL_HANDLE_H_