chromium/v8/include/v8-object.h

// 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;

/**
 * A private symbol
 *
 * This is an experimental feature. Use at your own risk.
 */
class V8_EXPORT Private : public Data { … };

/**
 * An instance of a Property Descriptor, see Ecma-262 6.2.4.
 *
 * Properties in a descriptor are present or absent. If you do not set
 * `enumerable`, `configurable`, and `writable`, they are absent. If `value`,
 * `get`, or `set` are absent, but you must specify them in the constructor, use
 * empty handles.
 *
 * Accessors `get` and `set` must be callable or undefined if they are present.
 *
 * \note Only query properties if they are present, i.e., call `x()` only if
 * `has_x()` returns true.
 *
 * \code
 * // var desc = {writable: false}
 * v8::PropertyDescriptor d(Local<Value>()), false);
 * d.value(); // error, value not set
 * if (d.has_writable()) {
 *   d.writable(); // false
 * }
 *
 * // var desc = {value: undefined}
 * v8::PropertyDescriptor d(v8::Undefined(isolate));
 *
 * // var desc = {get: undefined}
 * v8::PropertyDescriptor d(v8::Undefined(isolate), Local<Value>()));
 * \endcode
 */
class V8_EXPORT PropertyDescriptor { … };

/**
 * PropertyAttribute.
 */
enum PropertyAttribute { … };

/**
 * Accessor[Getter|Setter] are used as callback functions when setting|getting
 * a particular data property. See Object::SetNativeDataProperty and
 * ObjectTemplate::SetNativeDataProperty methods.
 */
AccessorNameGetterCallback;

AccessorNameSetterCallback;

/**
 * Access control specifications.
 *
 * Some accessors should be accessible across contexts. These
 * accessors have an explicit access control parameter which specifies
 * the kind of cross-context access that should be allowed.
 *
 */
enum V8_DEPRECATE_SOON(
    "This enum is no longer used and will be removed in V8 12.9.")
    AccessControl { … };

/**
 * Property filter bits. They can be or'ed to build a composite filter.
 */
enum PropertyFilter { … };

/**
 * Options for marking whether callbacks may trigger JS-observable side effects.
 * Side-effect-free callbacks are allowlisted during debug evaluation with
 * throwOnSideEffect. It applies when calling a Function, FunctionTemplate,
 * or an Accessor callback. For Interceptors, please see
 * PropertyHandlerFlags's kHasNoSideEffect.
 * Callbacks that only cause side effects to the receiver are allowlisted if
 * invoked on receiver objects that are created within the same debug-evaluate
 * call, as these objects are temporary and the side effect does not escape.
 */
enum class SideEffectType { … };

/**
 * Keys/Properties filter enums:
 *
 * KeyCollectionMode limits the range of collected properties. kOwnOnly limits
 * the collected properties to the given Object only. kIncludesPrototypes will
 * include all keys of the objects's prototype chain as well.
 */
enum class KeyCollectionMode { … };

/**
 * kIncludesIndices allows for integer indices to be collected, while
 * kSkipIndices will exclude integer indices from being collected.
 */
enum class IndexFilter { … };

/**
 * kConvertToString will convert integer indices to strings.
 * kKeepNumbers will return numbers for integer indices.
 */
enum class KeyConversionMode { … };

/**
 * Integrity level for objects.
 */
enum class IntegrityLevel { … };

/**
 * A JavaScript object (ECMA-262, 4.3.3)
 */
class V8_EXPORT Object : public Value { … };

// --- Implementation ---

Local<Data> Object::GetInternalField(int index) { … }

void* Object::GetAlignedPointerFromInternalField(v8::Isolate* isolate,
                                                 int index) { … }

void* Object::GetAlignedPointerFromInternalField(int index) { … }

// static
template <CppHeapPointerTag tag, typename T>
T* Object::Unwrap(v8::Isolate* isolate, const v8::Local<v8::Object>& wrapper) { … }

// static
template <CppHeapPointerTag tag, typename T>
T* Object::Unwrap(v8::Isolate* isolate, const PersistentBase<Object>& wrapper) { … }

// static
template <CppHeapPointerTag tag, typename T>
T* Object::Unwrap(v8::Isolate* isolate,
                  const BasicTracedReference<Object>& wrapper) { … }

// static
template <typename T>
T* Object::Unwrap(v8::Isolate* isolate, const v8::Local<v8::Object>& wrapper,
                  CppHeapPointerTagRange tag_range) { … }

// static
template <typename T>
T* Object::Unwrap(v8::Isolate* isolate, const PersistentBase<Object>& wrapper,
                  CppHeapPointerTagRange tag_range) { … }

// static
template <typename T>
T* Object::Unwrap(v8::Isolate* isolate,
                  const BasicTracedReference<Object>& wrapper,
                  CppHeapPointerTagRange tag_range) { … }

// static
template <CppHeapPointerTag tag>
void Object::Wrap(v8::Isolate* isolate, const v8::Local<v8::Object>& wrapper,
                  void* wrappable) { … }

// static
template <CppHeapPointerTag tag>
void Object::Wrap(v8::Isolate* isolate, const PersistentBase<Object>& wrapper,
                  void* wrappable) { … }

// static
template <CppHeapPointerTag tag>
void Object::Wrap(v8::Isolate* isolate,
                  const BasicTracedReference<Object>& wrapper,
                  void* wrappable) { … }

// static
void Object::Wrap(v8::Isolate* isolate, const v8::Local<v8::Object>& wrapper,
                  void* wrappable, CppHeapPointerTag tag) { … }

// static
void Object::Wrap(v8::Isolate* isolate, const PersistentBase<Object>& wrapper,
                  void* wrappable, CppHeapPointerTag tag) { … }

// static
void Object::Wrap(v8::Isolate* isolate,
                  const BasicTracedReference<Object>& wrapper, void* wrappable,
                  CppHeapPointerTag tag) { … }

Private* Private::Cast(Data* data) { … }

Object* Object::Cast(v8::Value* value) { … }

}  // namespace v8

#endif  // INCLUDE_V8_OBJECT_H_