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

#include <vector>

#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.

#ifdef V8_OS_WIN

// Setup for Windows DLL export/import. When building the V8 DLL the

// BUILDING_V8_SHARED needs to be defined. When building a program which uses

// the V8 DLL USING_V8_SHARED needs to be defined. When either building the V8

// static library or building a program which uses the V8 static library neither

// BUILDING_V8_SHARED nor USING_V8_SHARED should be defined.

#ifdef BUILDING_V8_SHARED

# define V8_EXPORT __declspec(dllexport)

#elif USING_V8_SHARED

# define V8_EXPORT __declspec(dllimport)

#else

# define V8_EXPORT

#endif // BUILDING_V8_SHARED

#else // V8_OS_WIN

// Setup for Linux shared library export.

#if V8_HAS_ATTRIBUTE_VISIBILITY

# ifdef BUILDING_V8_SHARED

# define V8_EXPORT __attribute__ ((visibility("default")))

# else

# define V8_EXPORT

# endif

#else

# define V8_EXPORT

#endif

#endif // V8_OS_WIN

/**

* 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 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 WasmCompiledModule;

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

class LocalEmbedderHeapTracer;

class NeverReadOnlySpaceObject;

class Object;

struct ScriptStreamingData;

template<typename T> class CustomArguments;

class PropertyCallbackArguments;

class FunctionCallbackArguments;

class GlobalHandles;

namespace wasm {

class NativeModule;

class StreamingDecoder;

} // namespace wasm

/**

* Configuration of tagging scheme.

*/

const int kApiPointerSize = sizeof(void*); // NOLINT

const int kApiDoubleSize = sizeof(double); // NOLINT

const int kApiIntSize = sizeof(int); // NOLINT

const int kApiInt64Size = sizeof(int64_t); // NOLINT

// Tag information for HeapObject.

const int kHeapObjectTag = 1;

const int kWeakHeapObjectTag = 3;

const int kHeapObjectTagSize = 2;

const intptr_t kHeapObjectTagMask = (1 << kHeapObjectTagSize) - 1;

// Tag information for Smi.

const int kSmiTag = 0;

const int kSmiTagSize = 1;

const intptr_t kSmiTagMask = (1 << kSmiTagSize) - 1;

template <size_t tagged_ptr_size>

struct SmiTagging;

template <int kSmiShiftSize>

V8_INLINE internal::Object* IntToSmi(int value) {

int smi_shift_bits = kSmiTagSize + kSmiShiftSize;

intptr_t tagged_value =

(static_cast<intptr_t>(value) << smi_shift_bits) | kSmiTag;

return reinterpret_cast<internal::Object*>(tagged_value);

}

// Smi constants for systems where tagged pointer is a 32-bit value.

template <>

struct SmiTagging<4> {

enum { kSmiShiftSize = 0, kSmiValueSize = 31 };

static int SmiShiftSize() { return kSmiShiftSize; }

static int SmiValueSize() { return kSmiValueSize; }

V8_INLINE static int SmiToInt(const internal::Object* value) {

int shift_bits = kSmiTagSize + kSmiShiftSize;

// Throw away top 32 bits and shift down (requires >> to be sign extending).

return static_cast<int>(reinterpret_cast<intptr_t>(value)) >> shift_bits;

}

V8_INLINE static internal::Object* IntToSmi(int value) {

return internal::IntToSmi<kSmiShiftSize>(value);

}

V8_INLINE static constexpr bool IsValidSmi(intptr_t value) {

// To be representable as an tagged small integer, the two

// most-significant bits of 'value' must be either 00 or 11 due to

// sign-extension. To check this we add 01 to the two

// most-significant bits, and check if the most-significant bit is 0

//

// CAUTION: The original code below:

// bool result = ((value + 0x40000000) & 0x80000000) == 0;

// may lead to incorrect results according to the C language spec, and

// in fact doesn't work correctly with gcc4.1.1 in some cases: The

// compiler may produce undefined results in case of signed integer

// overflow. The computation must be done w/ unsigned ints.

return static_cast<uintptr_t>(value) + 0x40000000U < 0x80000000U;

}

};

// Smi constants for systems where tagged pointer is a 64-bit value.

template <>

struct SmiTagging<8> {

enum { kSmiShiftSize = 31, kSmiValueSize = 32 };

static int SmiShiftSize() { return kSmiShiftSize; }

static int SmiValueSize() { return kSmiValueSize; }

V8_INLINE static int SmiToInt(const internal::Object* value) {

int shift_bits = kSmiTagSize + kSmiShiftSize;

// Shift down and throw away top 32 bits.

return static_cast<int>(reinterpret_cast<intptr_t>(value) >> shift_bits);

}

V8_INLINE static internal::Object* IntToSmi(int value) {

return internal::IntToSmi<kSmiShiftSize>(value);

}

V8_INLINE static constexpr bool IsValidSmi(intptr_t value) {

// To be representable as a long smi, the value must be a 32-bit integer.

return (value == static_cast<int32_t>(value));

}

};

#if V8_COMPRESS_POINTERS

static_assert(

kApiPointerSize == kApiInt64Size,

"Pointer compression can be enabled only for 64-bit architectures");

typedef SmiTagging<4> PlatformSmiTagging;

#else

typedef SmiTagging<kApiPointerSize> PlatformSmiTagging;

#endif

const int kSmiShiftSize = PlatformSmiTagging::kSmiShiftSize;

const int kSmiValueSize = PlatformSmiTagging::kSmiValueSize;

const int kSmiMinValue = (static_cast<unsigned int>(-1)) << (kSmiValueSize - 1);

const int kSmiMaxValue = -(kSmiMinValue + 1);

constexpr bool SmiValuesAre31Bits() { return kSmiValueSize == 31; }

constexpr bool SmiValuesAre32Bits() { return kSmiValueSize == 32; }

} // 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_(0) {}

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_ == 0; }

/**

* Sets the handle to be empty. IsEmpty() will then return true.

*/

V8_INLINE void Clear() { val_ = 0; }

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::Object** a = reinterpret_cast<internal::Object**>(this->val_);

internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);

if (a == 0) return b == 0;

if (b == 0) return false;

return *a == *b;

}

template <class S> V8_INLINE bool operator==(

const PersistentBase<S>& that) const {

internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);

internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);

if (a == 0) return b == 0;

if (b == 0) 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 of another handle.

* The referee is kept alive by the local handle even when

* the original handle is destroyed/disposed.

*/

V8_INLINE static Local<T> New(Isolate* isolate, Local<T> that);

V8_INLINE static Local<T> New(Isolate* isolate,

const PersistentBase<T>& that);

private:

friend class Utils;

template<class F> friend class Eternal;

template<class F> friend class PersistentBase;

template<class F, class M> friend class Persistent;

template<class F> friend class Local;

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;

explicit V8_INLINE Local(T* that) : val_(that) {}

V8_INLINE static Local<T> New(Isolate* isolate, T* that);

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

/**

* A MaybeLocal<> is a wrapper around Local<> that enforces a check whether

* the Local<> is empty before it can be used.

*

* If an API method returns a MaybeLocal<>, the API method can potentially fail

* either because an exception is thrown, or because an exception is pending,

* e.g. because a previous API call threw an exception that hasn't been caught

* yet, or because a TerminateExecution exception was thrown. In that case, an

* empty MaybeLocal is returned.

*/

template <class T>

class MaybeLocal {

public:

V8_INLINE MaybeLocal() : val_(nullptr) {}

template <class S>

V8_INLINE MaybeLocal(Local<S> that)

: val_(reinterpret_cast<T*>(*that)) {

TYPE_CHECK(T, S);

}

V8_INLINE bool IsEmpty() const { return val_ == nullptr; }

/**

* Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,

* |false| is returned and |out| is left untouched.

*/

template <class S>

V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {

out->val_ = IsEmpty() ? nullptr : this->val_;

return !IsEmpty();

}

/**

* Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,

* V8 will crash the process.

*/

V8_INLINE Local<T> ToLocalChecked();

/**

* Converts this MaybeLocal<> to a Local<>, using a default value if this

* MaybeLocal<> is empty.

*/

template <class S>

V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {

return IsEmpty() ? default_value : Local<S>(val_);

}

private:

T* val_;

};

/**

* Eternal handles are set-once handles that live for the lifetime of the

* isolate.

*/

template <class T> class Eternal {

public:

V8_INLINE Eternal() : val_(nullptr) {}

template <class S>

V8_INLINE Eternal(Isolate* isolate, Local<S> handle) : val_(nullptr) {

Set(isolate, handle);

}

// Can only be safely called if already set.

V8_INLINE Local<T> Get(Isolate* isolate) const;

V8_INLINE bool IsEmpty() const { return val_ == nullptr; }

template<class S> V8_INLINE void Set(Isolate* isolate, Local<S> handle);

private:

T* val_;

};

static const int kInternalFieldsInWeakCallback = 2;

static const int kEmbedderFieldsInWeakCallback = 2;

template <typename T>

class WeakCallbackInfo {

public:

typedef void (*Callback)(const WeakCallbackInfo<T>& data);

WeakCallbackInfo(Isolate* isolate, T* parameter,

void* embedder_fields[kEmbedderFieldsInWeakCallback],

Callback* callback)

: isolate_(isolate), parameter_(parameter), callback_(callback) {

for (int i = 0; i < kEmbedderFieldsInWeakCallback; ++i) {

embedder_fields_[i] = embedder_fields[i];

}

}

V8_INLINE Isolate* GetIsolate() const { return isolate_; }

V8_INLINE T* GetParameter() const { return parameter_; }

V8_INLINE void* GetInternalField(int index) const;

// When first called, the embedder MUST Reset() the Global which triggered the

// callback. The Global itself is unusable for anything else. No v8 other api

// calls may be called in the first callback. Should additional work be

// required, the embedder must set a second pass callback, which will be

// called after all the initial callbacks are processed.

// Calling SetSecondPassCallback on the second pass will immediately crash.

void SetSecondPassCallback(Callback callback) const { *callback_ = callback; }

private:

Isolate* isolate_;

T* parameter_;

Callback* callback_;

void* embedder_fields_[kEmbedderFieldsInWeakCallback];

};

// kParameter will pass a void* parameter back to the callback, kInternalFields

// will pass the first two internal fields back to the callback, kFinalizer

// will pass a void* parameter back, but is invoked before the object is

// actually collected, so it can be resurrected. In the last case, it is not

// possible to request a second pass callback.

enum class WeakCallbackType { kParameter, kInternalFields, kFinalizer };

/**

* An object reference that is independent of any handle scope. Where

* a Local handle only lives as long as the HandleScope in which it was

* allocated, a PersistentBase handle remains valid until it is explicitly

* disposed using Reset().

*

* A persistent handle contains a reference to a storage cell within

* the V8 engine which holds an object value and which is updated by

* the garbage collector whenever the object is moved. A new storage

* cell can be created using the constructor or PersistentBase::Reset and

* existing handles can be disposed using PersistentBase::Reset.

*

*/

template <class T> class PersistentBase {

public:

/**

* If non-empty, destroy the underlying storage cell

* IsEmpty() will return true after this call.

*/

V8_INLINE void Reset();

/**

* If non-empty, destroy the underlying storage cell

* and create a new one with the contents of other if other is non empty

*/

template <class S>

V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);

/**

* If non-empty, destroy the underlying storage cell

* and create a new one with the contents of other if other is non empty

*/

template <class S>

V8_INLINE void Reset(Isolate* isolate, const PersistentBase<S>& other);

V8_INLINE bool IsEmpty() const { return val_ == NULL; }

V8_INLINE void Empty() { val_ = 0; }

V8_INLINE Local<T> Get(Isolate* isolate) const {

return Local<T>::New(isolate, *this);

}

template <class S>

V8_INLINE bool operator==(const PersistentBase<S>& that) const {

internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);

internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);

if (a == NULL) return b == NULL;

if (b == NULL) return false;

return *a == *b;

}

template <class S>

V8_INLINE bool operator==(const Local<S>& that) const {

internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);

internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);

if (a == NULL) return b == NULL;

if (b == NULL) return false;

return *a == *b;

}

template <class S>

V8_INLINE bool operator!=(const PersistentBase<S>& that) const {

return !operator==(that);

}

template <class S>

V8_INLINE bool operator!=(const Local<S>& that) const {

return !operator==(that);

}

/**

* Install a finalization callback on this object.

* NOTE: There is no guarantee as to *when* or even *if* the callback is

* invoked. The invocation is performed solely on a best effort basis.

* As always, GC-based finalization should *not* be relied upon for any

* critical form of resource management!

*/

template <typename P>

V8_INLINE void SetWeak(P* parameter,

typename WeakCallbackInfo<P>::Callback callback,

WeakCallbackType type);

/**

* Turns this handle into a weak phantom handle without finalization callback.

* The handle will be reset automatically when the garbage collector detects

* that the object is no longer reachable.

* A related function Isolate::NumberOfPhantomHandleResetsSinceLastCall

* returns how many phantom handles were reset by the garbage collector.

*/

V8_INLINE void SetWeak();

template<typename P>

V8_INLINE P* ClearWeak();

// TODO(dcarney): remove this.

V8_INLINE void ClearWeak() { ClearWeak<void>(); }

/**

* Annotates the strong handle with the given label, which is then used by the

* heap snapshot generator as a name of the edge from the root to the handle.

* The function does not take ownership of the label and assumes that the

* label is valid as long as the handle is valid.

*/

V8_INLINE void AnnotateStrongRetainer(const char* label);

/**

* Allows the embedder to tell the v8 garbage collector that a certain object

* is alive. Only allowed when the embedder is asked to trace its heap by

* EmbedderHeapTracer.

*/

V8_INLINE void RegisterExternalReference(Isolate* isolate) const;

/**

* Marks the reference to this object independent. Garbage collector is free

* to ignore any object groups containing this object. Weak callback for an

* independent handle should not assume that it will be preceded by a global

* GC prologue callback or followed by a global GC epilogue callback.

*/

V8_DEPRECATE_SOON(

"Objects are always considered independent. "

"Use MarkActive to avoid collecting otherwise dead weak handles.",

V8_INLINE void MarkIndependent());

/**

* Marks the reference to this object as active. The scavenge garbage

* collection should not reclaim the objects marked as active, even if the

* object held by the handle is otherwise unreachable.

*

* This bit is cleared after the each garbage collection pass.

*/

V8_INLINE void MarkActive();

V8_DEPRECATE_SOON("See MarkIndependent.",

V8_INLINE bool IsIndependent() const);

/** Checks if the handle holds the only reference to an object. */

V8_INLINE bool IsNearDeath() const;

/** Returns true if the handle's reference is weak. */

V8_INLINE bool IsWeak() const;

/**

* Assigns a wrapper class ID to the handle. See RetainedObjectInfo interface

* description in v8-profiler.h for details.

*/

V8_INLINE void SetWrapperClassId(uint16_t class_id);

/**

* Returns the class ID previously assigned to this handle or 0 if no class ID

* was previously assigned.

*/

V8_INLINE uint16_t WrapperClassId() const;

PersistentBase(const PersistentBase& other) = delete; // NOLINT

void operator=(const PersistentBase&) = delete;

private:

friend class Isolate;

friend class Utils;

template<class F> friend class Local;

template<class F1, class F2> friend class Persistent;

template <class F>

friend class Global;

template<class F> friend class PersistentBase;

template<class F> friend class ReturnValue;

template <class F1, class F2, class F3>

friend class PersistentValueMapBase;

template<class F1, class F2> friend class PersistentValueVector;

friend class Object;

explicit V8_INLINE PersistentBase(T* val) : val_(val) {}

V8_INLINE static T* New(Isolate* isolate, T* that);

T* val_;

};

/**

* Default traits for Persistent. This class does not allow

* use of the copy constructor or assignment operator.

* At present kResetInDestructor is not set, but that will change in a future

* version.

*/

template<class T>

class NonCopyablePersistentTraits {

public:

typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent;

static const bool kResetInDestructor = false;

template<class S, class M>

V8_INLINE static void Copy(const Persistent<S, M>& source,

NonCopyablePersistent* dest) {

Uncompilable<Object>();

}

// TODO(dcarney): come up with a good compile error here.

template<class O> V8_INLINE static void Uncompilable() {

TYPE_CHECK(O, Primitive);

}

};

/**

* Helper class traits to allow copying and assignment of Persistent.

* This will clone the contents of storage cell, but not any of the flags, etc.

*/

template<class T>

struct CopyablePersistentTraits {

typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent;

static const bool kResetInDestructor = true;

template<class S, class M>

static V8_INLINE void Copy(const Persistent<S, M>& source,

CopyablePersistent* dest) {

// do nothing, just allow copy

}

};

/**

* A PersistentBase which allows copy and assignment.

*

* Copy, assignment and destructor behavior is controlled by the traits

* class M.

*

* Note: Persistent class hierarchy is subject to future changes.

*/

template <class T, class M> class Persistent : public PersistentBase<T> {

public:

/**

* A Persistent with no storage cell.

*/

V8_INLINE Persistent() : PersistentBase<T>(0) { }

/**

* Construct a Persistent from a Local.

* When the Local is non-empty, a new storage cell is created

* pointing to the same object, and no flags are set.

*/

template <class S>

V8_INLINE Persistent(Isolate* isolate, Local<S> that)

: PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {

TYPE_CHECK(T, S);

}

/**

* Construct a Persistent from a Persistent.

* When the Persistent is non-empty, a new storage cell is created

* pointing to the same object, and no flags are set.

*/

template <class S, class M2>

V8_INLINE Persistent(Isolate* isolate, const Persistent<S, M2>& that)

: PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {

TYPE_CHECK(T, S);

}

/**

* The copy constructors and assignment operator create a Persistent

* exactly as the Persistent constructor, but the Copy function from the

* traits class is called, allowing the setting of flags based on the

* copied Persistent.

*/

V8_INLINE Persistent(const Persistent& that) : PersistentBase<T>(0) {

Copy(that);

}

template <class S, class M2>

V8_INLINE Persistent(const Persistent<S, M2>& that) : PersistentBase<T>(0) {

Copy(that);

}

V8_INLINE Persistent& operator=(const Persistent& that) { // NOLINT

Copy(that);

return *this;

}

template <class S, class M2>

V8_INLINE Persistent& operator=(const Persistent<S, M2>& that) { // NOLINT

Copy(that);

return *this;

}

/**

* The destructor will dispose the Persistent based on the

* kResetInDestructor flags in the traits class. Since not calling dispose

* can result in a memory leak, it is recommended to always set this flag.

*/

V8_INLINE ~Persistent() {

if (M::kResetInDestructor) this->Reset();

}

// TODO(dcarney): this is pretty useless, fix or remove

template <class S>

V8_INLINE static Persistent<T>& Cast(const Persistent<S>& that) { // NOLINT

#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()) T::Cast(*that);

#endif

return reinterpret_cast<Persistent<T>&>(const_cast<Persistent<S>&>(that));

}

// TODO(dcarney): this is pretty useless, fix or remove

template <class S>

V8_INLINE Persistent<S>& As() const { // NOLINT

return Persistent<S>::Cast(*this);

}

private:

friend class Isolate;

friend class Utils;

template<class F> friend class Local;

template<class F1, class F2> friend class Persistent;

template<class F> friend class ReturnValue;

explicit V8_INLINE Persistent(T* that) : PersistentBase<T>(that) {}

V8_INLINE T* operator*() const { return this->val_; }

template<class S, class M2>

V8_INLINE void Copy(const Persistent<S, M2>& that);

};

/**

* A PersistentBase which has move semantics.

*

* Note: Persistent class hierarchy is subject to future changes.

*/

template <class T>

class Global : public PersistentBase<T> {

public:

/**

* A Global with no storage cell.

*/

V8_INLINE Global() : PersistentBase<T>(nullptr) {}

/**

* Construct a Global from a Local.

* When the Local is non-empty, a new storage cell is created

* pointing to the same object, and no flags are set.

*/

template <class S>

V8_INLINE Global(Isolate* isolate, Local<S> that)

: PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {

TYPE_CHECK(T, S);

}

/**

* Construct a Global from a PersistentBase.

* When the Persistent is non-empty, a new storage cell is created

* pointing to the same object, and no flags are set.

*/

template <class S>

V8_INLINE Global(Isolate* isolate, const PersistentBase<S>& that)

: PersistentBase<T>(PersistentBase<T>::New(isolate, that.val_)) {

TYPE_CHECK(T, S);

}

/**

* Move constructor.

*/

V8_INLINE Global(Global&& other) : PersistentBase<T>(other.val_) { // NOLINT

other.val_ = nullptr;

}

V8_INLINE ~Global() { this->Reset(); }

/**

* Move via assignment.

*/

template <class S>

V8_INLINE Global& operator=(Global<S>&& rhs) { // NOLINT

TYPE_CHECK(T, S);

if (this != &rhs) {

this->Reset();

this->val_ = rhs.val_;

rhs.val_ = nullptr;

}

return *this;

}

/**

* Pass allows returning uniques from functions, etc.

*/

Global Pass() { return static_cast<Global&&>(*this); } // NOLINT

/*

* For compatibility with Chromium's base::Bind (base::Passed).

*/

typedef void MoveOnlyTypeForCPP03;

Global(const Global&) = delete;

void operator=(const Global&) = delete;

private:

template <class F>

friend class ReturnValue;

V8_INLINE T* operator*() const { return this->val_; }

};

// UniquePersistent is an alias for Global for historical reason.

template <class T>

using UniquePersistent = Global<T>;

/**

* A stack-allocated class that governs a number of local handles.

* After a handle scope has been created, all local handles will be

* allocated within that handle scope until either the handle scope is

* deleted or another handle scope is created. If there is already a

* handle scope and a new one is created, all allocations will take

* place in the new handle scope until it is deleted. After that,

* new handles will again be allocated in the original handle scope.

*

* After the handle scope of a local handle has been deleted the

* garbage collector will no longer track the object stored in the

* handle and may deallocate it. The behavior of accessing a handle

* for which the handle scope has been deleted is undefined.

*/

class V8_EXPORT HandleScope {

public:

explicit HandleScope(Isolate* isolate);

~HandleScope();

/**

* Counts the number of allocated handles.

*/

static int NumberOfHandles(Isolate* isolate);

V8_INLINE Isolate* GetIsolate() const {

return reinterpret_cast<Isolate*>(isolate_);

}

HandleScope(const HandleScope&) = delete;

void operator=(const HandleScope&) = delete;

protected:

V8_INLINE HandleScope() {}

void Initialize(Isolate* isolate);

static internal::Object** CreateHandle(internal::Isolate* isolate,

internal::Object* 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);

// Uses heap_object to obtain the current Isolate.

static internal::Object** CreateHandle(

internal::NeverReadOnlySpaceObject* heap_object, internal::Object* value);