node-v12.21.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 http://code.google.com/apis/v8/ */ #ifndef INCLUDE_V8_H_ #define INCLUDE_V8_H_ #include <stddef.h> #include <stdint.h> #include <stdio.h> #include <memory> #include <string> #include <type_traits> #include <utility> #include <vector> #include "v8-internal.h" // NOLINT(build/include) #include "v8-version.h" // NOLINT(build/include) #include "v8config.h" // NOLINT(build/include) // 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 Context; class Data; class Date; class External; class Function; class FunctionTemplate; class HeapProfiler; class ImplementationUtilities; class Int32; class Integer; class Isolate; template <class T> class Maybe; class MicrotaskQueue; class Name; class Number; class NumberObject; class Object; class ObjectOperationDescriptor; class ObjectTemplate; class Platform; class Primitive; class Promise; class PropertyDescriptor; class Proxy; class RawOperationDescriptor; class Script; class SharedArrayBuffer; class Signature; class StartupData; class StackFrame; class StackTrace; class String; class StringObject; class Symbol; class SymbolObject; class PrimitiveArray; class Private; class Uint32; class Utils; class Value; class WasmModuleObject; template <class T> class Local; template <class T> class MaybeLocal; template <class T> class Eternal; template<class T> class NonCopyablePersistentTraits; template<class T> class PersistentBase; template <class T, class M = NonCopyablePersistentTraits<T> > class Persistent; template <class T> class Global; template <class T> class TracedGlobal; template<class K, class V, class T> class PersistentValueMap; template <class K, class V, class T> class PersistentValueMapBase; template <class K, class V, class T> class GlobalValueMap; template<class V, class T> class PersistentValueVector; template<class T, class P> class WeakCallbackObject; class FunctionTemplate; class ObjectTemplate; template<typename T> class FunctionCallbackInfo; template<typename T> class PropertyCallbackInfo; class StackTrace; class StackFrame; class Isolate; class CallHandlerHelper; class EscapableHandleScope; template<typename T> class ReturnValue; namespace internal { class Arguments; class DeferredHandles; class Heap; class HeapObject; class ExternalString; class Isolate; class LocalEmbedderHeapTracer; class MicrotaskQueue; class NeverReadOnlySpaceObject; struct ScriptStreamingData; template<typename T> class CustomArguments; class PropertyCallbackArguments; class FunctionCallbackArguments; class GlobalHandles; class ScopedExternalStringLock; class ThreadLocalTop; namespace wasm { class NativeModule; class StreamingDecoder; } // namespace wasm } // namespace internal namespace debug { class ConsoleCallArguments; } // namespace debug // --- Handles --- #define TYPE_CHECK(T, S) \ while (false) { \ *(static_cast<T* volatile*>(0)) = static_cast<S*>(0); \ } /** * 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>. */ TYPE_CHECK(T, S); } /** * 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. * The handles' references are not checked. */ 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. * The handles' references are not checked. */ 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. */ 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)); } /** * Calling this is equivalent to Local<S>::Cast(). * In particular, this is only valid if the handle actually refers to a value * of the target type. */ template <class S> V8_INLINE Local<S> As() const { return Local<S>::Cast(*this); } /** * Create a local handle for the content o