v8-object.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_OBJECT_H_
#define INCLUDE_V8_OBJECT_H_
 
#include "v8-internal.h"           // NOLINT(build/include_directory)
#include "v8-local-handle.h"       // NOLINT(build/include_directory)
#include "v8-maybe.h"              // NOLINT(build/include_directory)
#include "v8-persistent-handle.h"  // NOLINT(build/include_directory)
#include "v8-primitive.h"          // NOLINT(build/include_directory)
#include "v8-sandbox.h"            // NOLINT(build/include_directory)
#include "v8-traced-handle.h"      // NOLINT(build/include_directory)
#include "v8-value.h"              // NOLINT(build/include_directory)
#include "v8config.h"              // NOLINT(build/include_directory)
 
namespace v8 {
 
class Array;
class Function;
class FunctionTemplate;
template <typename T>
class PropertyCallbackInfo;
 
class V8_EXPORT Private : public Data {
 public:
  Local<Value> Name() const;
 
  static Local<Private> New(Isolate* isolate,
                            Local<String> name = Local<String>());
 
  static Local<Private> ForApi(Isolate* isolate, Local<String> name);
 
  V8_INLINE static Private* Cast(Data* data);
 
 private:
  Private();
 
  static void CheckCast(Data* that);
};
 
class V8_EXPORT PropertyDescriptor {
 public:
  // GenericDescriptor
  PropertyDescriptor();
 
  // DataDescriptor
  explicit PropertyDescriptor(Local<Value> value);
 
  // DataDescriptor with writable property
  PropertyDescriptor(Local<Value> value, bool writable);
 
  // AccessorDescriptor
  PropertyDescriptor(Local<Value> get, Local<Value> set);
 
  ~PropertyDescriptor();
 
  Local<Value> value() const;
  bool has_value() const;
 
  Local<Value> get() const;
  bool has_get() const;
  Local<Value> set() const;
  bool has_set() const;
 
  void set_enumerable(bool enumerable);
  bool enumerable() const;
  bool has_enumerable() const;
 
  void set_configurable(bool configurable);
  bool configurable() const;
  bool has_configurable() const;
 
  bool writable() const;
  bool has_writable() const;
 
  struct PrivateData;
  PrivateData* get_private() const { return private_; }
 
  PropertyDescriptor(const PropertyDescriptor&) = delete;
  void operator=(const PropertyDescriptor&) = delete;
 
 private:
  PrivateData* private_;
};
 
enum PropertyAttribute {
  None = 0,
  ReadOnly = 1 << 0,
  DontEnum = 1 << 1,
  DontDelete = 1 << 2
};
 
using AccessorGetterCallback V8_DEPRECATE_SOON(
    "Use AccessorNameGetterCallback signature instead") =
    void (*)(Local<String> property, const PropertyCallbackInfo<Value>& info);
using AccessorNameGetterCallback =
    void (*)(Local<Name> property, const PropertyCallbackInfo<Value>& info);
 
using AccessorSetterCallback V8_DEPRECATE_SOON(
    "Use AccessorNameSetterCallback signature instead") =
    void (*)(Local<String> property, Local<Value> value,
             const PropertyCallbackInfo<void>& info);
using AccessorNameSetterCallback =
    void (*)(Local<Name> property, Local<Value> value,
             const PropertyCallbackInfo<void>& info);
 
enum AccessControl {
  DEFAULT = 0,
};
 
enum PropertyFilter {
  ALL_PROPERTIES = 0,
  ONLY_WRITABLE = 1,
  ONLY_ENUMERABLE = 2,
  ONLY_CONFIGURABLE = 4,
  SKIP_STRINGS = 8,
  SKIP_SYMBOLS = 16
};
 
enum class SideEffectType {
  kHasSideEffect,
  kHasNoSideEffect,
  kHasSideEffectToReceiver
};
 
enum class KeyCollectionMode { kOwnOnly, kIncludePrototypes };
 
enum class IndexFilter { kIncludeIndices, kSkipIndices };
 
enum class KeyConversionMode { kConvertToString, kKeepNumbers, kNoNumbers };
 
enum class IntegrityLevel { kFrozen, kSealed };
 
class V8_EXPORT Object : public Value {
 public:
  V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context,
                                        Local<Value> key, Local<Value> value);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context, uint32_t index,
                                        Local<Value> value);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> CreateDataProperty(Local<Context> context,
                                                       Local<Name> key,
                                                       Local<Value> value);
  V8_WARN_UNUSED_RESULT Maybe<bool> CreateDataProperty(Local<Context> context,
                                                       uint32_t index,
                                                       Local<Value> value);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> DefineOwnProperty(
      Local<Context> context, Local<Name> key, Local<Value> value,
      PropertyAttribute attributes = None);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> DefineProperty(
      Local<Context> context, Local<Name> key, PropertyDescriptor& descriptor);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
                                              Local<Value> key);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
                                              uint32_t index);
 
  V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute> GetPropertyAttributes(
      Local<Context> context, Local<Value> key);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetOwnPropertyDescriptor(
      Local<Context> context, Local<Name> key);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
                                        Local<Value> key);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
                                           Local<Value> key);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context, uint32_t index);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
                                           uint32_t index);
 
  V8_DEPRECATE_SOON("Use SetNativeDataProperty instead")
  V8_WARN_UNUSED_RESULT Maybe<bool> SetAccessor(
      Local<Context> context, Local<Name> name,
      AccessorNameGetterCallback getter,
      AccessorNameSetterCallback setter = nullptr,
      MaybeLocal<Value> data = MaybeLocal<Value>(),
      AccessControl deprecated_settings = DEFAULT,
      PropertyAttribute attribute = None,
      SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
      SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
 
  void SetAccessorProperty(Local<Name> name, Local<Function> getter,
                           Local<Function> setter = Local<Function>(),
                           PropertyAttribute attributes = None);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> SetNativeDataProperty(
      Local<Context> context, Local<Name> name,
      AccessorNameGetterCallback getter,
      AccessorNameSetterCallback setter = nullptr,
      Local<Value> data = Local<Value>(), PropertyAttribute attributes = None,
      SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
      SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> SetLazyDataProperty(
      Local<Context> context, Local<Name> name,
      AccessorNameGetterCallback getter, Local<Value> data = Local<Value>(),
      PropertyAttribute attributes = None,
      SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
      SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
 
  Maybe<bool> HasPrivate(Local<Context> context, Local<Private> key);
  Maybe<bool> SetPrivate(Local<Context> context, Local<Private> key,
                         Local<Value> value);
  Maybe<bool> DeletePrivate(Local<Context> context, Local<Private> key);
  MaybeLocal<Value> GetPrivate(Local<Context> context, Local<Private> key);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetPropertyNames(
      Local<Context> context);
  V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetPropertyNames(
      Local<Context> context, KeyCollectionMode mode,
      PropertyFilter property_filter, IndexFilter index_filter,
      KeyConversionMode key_conversion = KeyConversionMode::kKeepNumbers);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetOwnPropertyNames(
      Local<Context> context);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetOwnPropertyNames(
      Local<Context> context, PropertyFilter filter,
      KeyConversionMode key_conversion = KeyConversionMode::kKeepNumbers);
 
  // V8_DEPRECATE_SOON(
  //     "V8 will stop providing access to hidden prototype (i.e. "
  //     "JSGlobalObject). Use GetPrototypeV2() instead. "
  //     "See http://crbug.com/333672197.")
  Local<Value> GetPrototype();
 
  Local<Value> GetPrototypeV2();
 
  // V8_DEPRECATE_SOON(
  //     "V8 will stop providing access to hidden prototype (i.e. "
  //     "JSGlobalObject). Use SetPrototypeV2() instead. "
  //     "See http://crbug.com/333672197.")
  V8_WARN_UNUSED_RESULT Maybe<bool> SetPrototype(Local<Context> context,
                                                 Local<Value> prototype);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> SetPrototypeV2(Local<Context> context,
                                                   Local<Value> prototype);
 
  Local<Object> FindInstanceInPrototypeChain(Local<FunctionTemplate> tmpl);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<String> ObjectProtoToString(
      Local<Context> context);
 
  Local<String> GetConstructorName();
 
  Maybe<bool> SetIntegrityLevel(Local<Context> context, IntegrityLevel level);
 
  int InternalFieldCount() const;
 
  V8_INLINE static int InternalFieldCount(
      const PersistentBase<Object>& object) {
    return object.template value<Object>()->InternalFieldCount();
  }
 
  V8_INLINE static int InternalFieldCount(
      const BasicTracedReference<Object>& object) {
    return object.template value<Object>()->InternalFieldCount();
  }
 
  V8_INLINE Local<Data> GetInternalField(int index);
 
  void SetInternalField(int index, Local<Data> data);
 
  V8_INLINE void* GetAlignedPointerFromInternalField(int index);
  V8_INLINE void* GetAlignedPointerFromInternalField(v8::Isolate* isolate,
                                                     int index);
 
  V8_INLINE static void* GetAlignedPointerFromInternalField(
      const PersistentBase<Object>& object, int index) {
    return object.template value<Object>()->GetAlignedPointerFromInternalField(
        index);
  }
 
  V8_INLINE static void* GetAlignedPointerFromInternalField(
      const BasicTracedReference<Object>& object, int index) {
    return object.template value<Object>()->GetAlignedPointerFromInternalField(
        index);
  }
 
  void SetAlignedPointerInInternalField(int index, void* value);
  void SetAlignedPointerInInternalFields(int argc, int indices[],
                                         void* values[]);
 
  template <CppHeapPointerTag tag, typename T = void>
  static V8_INLINE T* Unwrap(v8::Isolate* isolate,
                             const v8::Local<v8::Object>& wrapper);
  template <CppHeapPointerTag tag, typename T = void>
  static V8_INLINE T* Unwrap(v8::Isolate* isolate,
                             const PersistentBase<Object>& wrapper);
  template <CppHeapPointerTag tag, typename T = void>
  static V8_INLINE T* Unwrap(v8::Isolate* isolate,
                             const BasicTracedReference<Object>& wrapper);
 
  template <CppHeapPointerTag tag>
  static V8_INLINE void Wrap(v8::Isolate* isolate,
                             const v8::Local<v8::Object>& wrapper,
                             void* wrappable);
  template <CppHeapPointerTag tag>
  static V8_INLINE void Wrap(v8::Isolate* isolate,
                             const PersistentBase<Object>& wrapper,
                             void* wrappable);
  template <CppHeapPointerTag tag>
  static V8_INLINE void Wrap(v8::Isolate* isolate,
                             const BasicTracedReference<Object>& wrapper,
                             void* wrappable);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> HasOwnProperty(Local<Context> context,
                                                   Local<Name> key);
  V8_WARN_UNUSED_RESULT Maybe<bool> HasOwnProperty(Local<Context> context,
                                                   uint32_t index);
  V8_WARN_UNUSED_RESULT Maybe<bool> HasRealNamedProperty(Local<Context> context,
                                                         Local<Name> key);
  V8_WARN_UNUSED_RESULT Maybe<bool> HasRealIndexedProperty(
      Local<Context> context, uint32_t index);
  V8_WARN_UNUSED_RESULT Maybe<bool> HasRealNamedCallbackProperty(
      Local<Context> context, Local<Name> key);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetRealNamedPropertyInPrototypeChain(
      Local<Context> context, Local<Name> key);
 
  V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute>
  GetRealNamedPropertyAttributesInPrototypeChain(Local<Context> context,
                                                 Local<Name> key);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetRealNamedProperty(
      Local<Context> context, Local<Name> key);
 
  V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute> GetRealNamedPropertyAttributes(
      Local<Context> context, Local<Name> key);
 
  bool HasNamedLookupInterceptor() const;
 
  bool HasIndexedLookupInterceptor() const;
 
  int GetIdentityHash();
 
  // TODO(dcarney): take an isolate and optionally bail out?
  Local<Object> Clone();
 
  MaybeLocal<Context> GetCreationContext();
 
  Local<Context> GetCreationContextChecked();
 
  V8_INLINE static MaybeLocal<Context> GetCreationContext(
      const PersistentBase<Object>& object) {
    return object.template value<Object>()->GetCreationContext();
  }
 
  void* GetAlignedPointerFromEmbedderDataInCreationContext(int index);
 
  bool IsCallable() const;
 
  bool IsConstructor() const;
 
  bool IsApiWrapper() const;
 
  bool IsUndetectable() const;
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> CallAsFunction(Local<Context> context,
                                                         Local<Value> recv,
                                                         int argc,
                                                         Local<Value> argv[]);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> CallAsConstructor(
      Local<Context> context, int argc, Local<Value> argv[]);
 
  Isolate* GetIsolate();
 
  V8_INLINE static Isolate* GetIsolate(const TracedReference<Object>& handle) {
    return handle.template value<Object>()->GetIsolate();
  }
 
  MaybeLocal<Array> PreviewEntries(bool* is_key_value);
 
  static Local<Object> New(Isolate* isolate);
 
  static Local<Object> New(Isolate* isolate, Local<Value> prototype_or_null,
                           Local<Name>* names, Local<Value>* values,
                           size_t length);
 
  V8_INLINE static Object* Cast(Value* obj);
 
  bool IsCodeLike(Isolate* isolate) const;
 
 private:
  static void* Unwrap(v8::Isolate* isolate, internal::Address wrapper_obj,
                      CppHeapPointerTag tag);
  static void Wrap(v8::Isolate* isolate, internal::Address wrapper_obj,
                   CppHeapPointerTag tag, void* wrappable);
 
  Object();
  static void CheckCast(Value* obj);
  Local<Data> SlowGetInternalField(int index);
  void* SlowGetAlignedPointerFromInternalField(int index);
  void* SlowGetAlignedPointerFromInternalField(v8::Isolate* isolate, int index);
};
 
// --- Implementation ---
 
Local<Data> Object::GetInternalField(int index) {
#ifndef V8_ENABLE_CHECKS
  using A = internal::Address;
  using I = internal::Internals;
  A obj = internal::ValueHelper::ValueAsAddress(this);
  // Fast path: If the object is a plain JSObject, which is the common case, we
  // know where to find the internal fields and can return the value directly.
  int instance_type = I::GetInstanceType(obj);
  if (I::CanHaveInternalField(instance_type)) {
    int offset = I::kJSAPIObjectWithEmbedderSlotsHeaderSize +
                 (I::kEmbedderDataSlotSize * index);
    A value = I::ReadRawField<A>(obj, offset);
#ifdef V8_COMPRESS_POINTERS
    // We read the full pointer value and then decompress it in order to avoid
    // dealing with potential endiannes issues.
    value = I::DecompressTaggedField(obj, static_cast<uint32_t>(value));
#endif
 
    auto isolate = reinterpret_cast<v8::Isolate*>(
        internal::IsolateFromNeverReadOnlySpaceObject(obj));
    return Local<Data>::New(isolate, value);
  }
#endif
  return SlowGetInternalField(index);
}
 
void* Object::GetAlignedPointerFromInternalField(v8::Isolate* isolate,
                                                 int index) {
#if !defined(V8_ENABLE_CHECKS)
  using A = internal::Address;
  using I = internal::Internals;
  A obj = internal::ValueHelper::ValueAsAddress(this);
  // Fast path: If the object is a plain JSObject, which is the common case, we
  // know where to find the internal fields and can return the value directly.
  auto instance_type = I::GetInstanceType(obj);
  if (V8_LIKELY(I::CanHaveInternalField(instance_type))) {
    int offset = I::kJSAPIObjectWithEmbedderSlotsHeaderSize +
                 (I::kEmbedderDataSlotSize * index) +
                 I::kEmbedderDataSlotExternalPointerOffset;
    A value =
        I::ReadExternalPointerField<internal::kEmbedderDataSlotPayloadTag>(
            isolate, obj, offset);
    return reinterpret_cast<void*>(value);
  }
#endif
  return SlowGetAlignedPointerFromInternalField(isolate, index);
}
 
void* Object::GetAlignedPointerFromInternalField(int index) {
#if !defined(V8_ENABLE_CHECKS)
  using A = internal::Address;
  using I = internal::Internals;
  A obj = internal::ValueHelper::ValueAsAddress(this);
  // Fast path: If the object is a plain JSObject, which is the common case, we
  // know where to find the internal fields and can return the value directly.
  auto instance_type = I::GetInstanceType(obj);
  if (V8_LIKELY(I::CanHaveInternalField(instance_type))) {
    int offset = I::kJSAPIObjectWithEmbedderSlotsHeaderSize +
                 (I::kEmbedderDataSlotSize * index) +
                 I::kEmbedderDataSlotExternalPointerOffset;
    Isolate* isolate = I::GetIsolateForSandbox(obj);
    A value =
        I::ReadExternalPointerField<internal::kEmbedderDataSlotPayloadTag>(
            isolate, obj, offset);
    return reinterpret_cast<void*>(value);
  }
#endif
  return SlowGetAlignedPointerFromInternalField(index);
}
 
// static
template <CppHeapPointerTag tag, typename T>
T* Object::Unwrap(v8::Isolate* isolate, const v8::Local<v8::Object>& wrapper) {
  auto obj = internal::ValueHelper::ValueAsAddress(*wrapper);
#if !defined(V8_ENABLE_CHECKS)
  return internal::ReadCppHeapPointerField<tag, T>(
      isolate, obj, internal::Internals::kJSObjectHeaderSize);
#else   // defined(V8_ENABLE_CHECKS)
  return reinterpret_cast<T*>(Unwrap(isolate, obj, tag));
#endif  // defined(V8_ENABLE_CHECKS)
}
 
// static
template <CppHeapPointerTag tag, typename T>
T* Object::Unwrap(v8::Isolate* isolate, const PersistentBase<Object>& wrapper) {
  auto obj =
      internal::ValueHelper::ValueAsAddress(wrapper.template value<Object>());
#if !defined(V8_ENABLE_CHECKS)
  return internal::ReadCppHeapPointerField<tag, T>(
      isolate, obj, internal::Internals::kJSObjectHeaderSize);
#else   // defined(V8_ENABLE_CHECKS)
 
  return reinterpret_cast<T*>(Unwrap(isolate, obj, tag));
#endif  // defined(V8_ENABLE_CHECKS)
}
 
// static
template <CppHeapPointerTag tag, typename T>
T* Object::Unwrap(v8::Isolate* isolate,
                  const BasicTracedReference<Object>& wrapper) {
  auto obj =
      internal::ValueHelper::ValueAsAddress(wrapper.template value<Object>());
#if !defined(V8_ENABLE_CHECKS)
  return internal::ReadCppHeapPointerField<tag, T>(
      isolate, obj, internal::Internals::kJSObjectHeaderSize);
#else   // defined(V8_ENABLE_CHECKS)
  return reinterpret_cast<T*>(Unwrap(isolate, obj, tag));
#endif  // defined(V8_ENABLE_CHECKS)
}
 
// static
template <CppHeapPointerTag tag>
void Object::Wrap(v8::Isolate* isolate, const v8::Local<v8::Object>& wrapper,
                  void* wrappable) {
  auto obj = internal::ValueHelper::ValueAsAddress(*wrapper);
  Wrap(isolate, obj, tag, wrappable);
}
 
// static
template <CppHeapPointerTag tag>
void Object::Wrap(v8::Isolate* isolate, const PersistentBase<Object>& wrapper,
                  void* wrappable) {
  auto obj =
      internal::ValueHelper::ValueAsAddress(wrapper.template value<Object>());
  Wrap(isolate, obj, tag, wrappable);
}
 
// static
template <CppHeapPointerTag tag>
void Object::Wrap(v8::Isolate* isolate,
                  const BasicTracedReference<Object>& wrapper,
                  void* wrappable) {
  auto obj =
      internal::ValueHelper::ValueAsAddress(wrapper.template value<Object>());
  Wrap(isolate, obj, tag, wrappable);
}
 
Private* Private::Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(data);
#endif
  return reinterpret_cast<Private*>(data);
}
 
Object* Object::Cast(v8::Value* value) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(value);
#endif
  return static_cast<Object*>(value);
}
 
}  // namespace v8
 
#endif  // INCLUDE_V8_OBJECT_H_