node-v16.15.0-headers.tar.gz

// Copyright 2012 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. /** \mainpage V8 API Reference Guide * * V8 is Google's open source JavaScript engine. * * This set of documents provides reference material generated from the * V8 header file, include/v8.h. * * For other documentation see https://v8.dev/. */ #ifndef INCLUDE_V8_H_ #define INCLUDE_V8_H_ #include <stddef.h> #include <stdint.h> #include <stdio.h> #include <atomic> #include <memory> #include <string> #include <type_traits> #include <utility> #include <vector> #include "cppgc/common.h" #include "v8-internal.h" // NOLINT(build/include_directory) #include "v8-version.h" // NOLINT(build/include_directory) #include "v8config.h" // NOLINT(build/include_directory) // We reserve the V8_* prefix for macros defined in V8 public API and // assume there are no name conflicts with the embedder's code. /** * The v8 JavaScript engine. */ namespace v8 { class AccessorSignature; class Array; class ArrayBuffer; class BigInt; class BigIntObject; class Boolean; class BooleanObject; class CFunction; class CallHandlerHelper; class Context; class CppHeap; class CTypeInfo; class Data; class Date; class EscapableHandleScope; class External; class Function; class FunctionTemplate; class HeapProfiler; class ImplementationUtilities; class Int32; class Integer; class Isolate; class Isolate; class MicrotaskQueue; class Name; class Number; class NumberObject; class Object; class ObjectOperationDescriptor; class ObjectTemplate; class Platform; class Primitive; class PrimitiveArray; class Private; class Promise; class PropertyDescriptor; class Proxy; class RawOperationDescriptor; class Script; class SharedArrayBuffer; class Signature; class StackFrame; class StackTrace; class StartupData; class String; class StringObject; class Symbol; class SymbolObject; class TracedReferenceBase; class Uint32; class Utils; class Value; class WasmMemoryObject; class WasmModuleObject; template <class K, class V, class T> class GlobalValueMap; template <class K, class V, class T> class PersistentValueMapBase; template<class T> class NonCopyablePersistentTraits; template <class T, class M = NonCopyablePersistentTraits<T>> class Persistent; template <class T> class BasicTracedReference; template <class T> class Eternal; template <class T> class Global; template <class T> class Local; template <class T> class Maybe; template <class T> class MaybeLocal; template <class T> class TracedGlobal; template <class T> class TracedReference; template<class K, class V, class T> class PersistentValueMap; template<class T, class P> class WeakCallbackObject; template <class T> class PersistentBase; template <class V, class T> class PersistentValueVector; template<typename T> class FunctionCallbackInfo; template<typename T> class PropertyCallbackInfo; template<typename T> class ReturnValue; namespace internal { class BasicTracedReferenceExtractor; class ExternalString; class FunctionCallbackArguments; class GlobalHandles; class Heap; class HeapObject; class Isolate; class LocalEmbedderHeapTracer; class MicrotaskQueue; class PropertyCallbackArguments; class ReadOnlyHeap; class ScopedExternalStringLock; class ThreadLocalTop; struct ScriptStreamingData; enum class ArgumentsType; template <ArgumentsType> class Arguments; template <typename T> class CustomArguments; namespace wasm { class NativeModule; class StreamingDecoder; } // namespace wasm } // namespace internal namespace metrics { class Recorder; } // namespace metrics namespace debug { class ConsoleCallArguments; } // namespace debug // --- Handles --- /** * An object reference managed by the v8 garbage collector. * * All objects returned from v8 have to be tracked by the garbage * collector so that it knows that the objects are still alive. Also, * because the garbage collector may move objects, it is unsafe to * point directly to an object. Instead, all objects are stored in * handles which are known by the garbage collector and updated * whenever an object moves. Handles should always be passed by value * (except in cases like out-parameters) and they should never be * allocated on the heap. * * There are two types of handles: local and persistent handles. * * Local handles are light-weight and transient and typically used in * local operations. They are managed by HandleScopes. That means that a * HandleScope must exist on the stack when they are created and that they are * only valid inside of the HandleScope active during their creation. * For passing a local handle to an outer HandleScope, an EscapableHandleScope * and its Escape() method must be used. * * Persistent handles can be used when storing objects across several * independent operations and have to be explicitly deallocated when they're no * longer used. * * It is safe to extract the object stored in the handle by * dereferencing the handle (for instance, to extract the Object* from * a Local<Object>); the value will still be governed by a handle * behind the scenes and the same rules apply to these values as to * their handles. */ template <class T> class Local { public: V8_INLINE Local() : val_(nullptr) {} template <class S> V8_INLINE Local(Local<S> that) : val_(reinterpret_cast<T*>(*that)) { /** * This check fails when trying to convert between incompatible * handles. For example, converting from a Local<String> to a * Local<Number>. */ static_assert(std::is_base_of<T, S>::value, "type check"); } /** * Returns true if the handle is empty. */ V8_INLINE bool IsEmpty() const { return val_ == nullptr; } /** * Sets the handle to be empty. IsEmpty() will then return true. */ V8_INLINE void Clear() { val_ = nullptr; } V8_INLINE T* operator->() const { return val_; } V8_INLINE T* operator*() const { return val_; } /** * Checks whether two handles are the same. * Returns true if both are empty, or if the objects to which they refer * are identical. * * If both handles refer to JS objects, this is the same as strict equality. * For primitives, such as numbers or strings, a `false` return value does not * indicate that the values aren't equal in the JavaScript sense. * Use `Value::StrictEquals()` to check primitives for equality. */ template <class S> V8_INLINE bool operator==(const Local<S>& that) const { internal::Address* a = reinterpret_cast<internal::Address*>(this->val_); internal::Address* b = reinterpret_cast<internal::Address*>(that.val_); if (a == nullptr) return b == nullptr; if (b == nullptr) return false; return *a == *b; } template <class S> V8_INLINE bool operator==( const PersistentBase<S>& that) const { internal::Address* a = reinterpret_cast<internal::Address*>(this->val_); internal::Address* b = reinterpret_cast<internal::Address*>(that.val_); if (a == nullptr) return b == nullptr; if (b == nullptr) return false; return *a == *b; } /** * Checks whether two handles are different. * Returns true if only one of the handles is empty, or if * the objects to which they refer are different. * * If both handles refer to JS objects, this is the same as strict * non-equality. For primitives, such as numbers or strings, a `true` return * value does not indicate that the values aren't equal in the JavaScript * sense. Use `Value::StrictEquals()` to check primitives for equality. */ 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); } /** * Cast a handle to a subclass, e.g. Local<Value> to Local<Object>. * This is only valid if the handle actually refers to a value of the * target type. */