v8  9.4.146 (node 16.13.0)
V8 is Google's open source JavaScript engine
Public Member Functions | Static Public Member Functions | Friends
Local< T > Class Template Reference

#include <v8.h>

Public Member Functions

V8_INLINE Local ()
 
template<class S >
V8_INLINE Local (Local< S > that)
 
V8_INLINE bool IsEmpty () const
 
V8_INLINE void Clear ()
 
V8_INLINE T * operator-> () const
 
V8_INLINE T * operator* () const
 
template<class S >
V8_INLINE bool operator== (const Local< S > &that) const
 
template<class S >
V8_INLINE bool operator== (const PersistentBase< S > &that) const
 
template<class S >
V8_INLINE bool operator!= (const Local< S > &that) const
 
template<class S >
V8_INLINE bool operator!= (const Persistent< S > &that) const
 
template<class S >
V8_INLINE Local< S > As () const
 

Static Public Member Functions

template<class S >
static V8_INLINE Local< T > Cast (Local< S > that)
 
static V8_INLINE Local< T > New (Isolate *isolate, Local< T > that)
 
static V8_INLINE Local< T > New (Isolate *isolate, const PersistentBase< T > &that)
 
static V8_INLINE Local< T > New (Isolate *isolate, const BasicTracedReference< T > &that)
 

Friends

class TracedReferenceBase
 
class Utils
 
template<class F >
class Eternal
 
template<class F >
class PersistentBase
 
template<class F , class M >
class Persistent
 
template<class F >
class Local
 
template<class F >
class MaybeLocal
 
template<class F >
class FunctionCallbackInfo
 
template<class F >
class PropertyCallbackInfo
 
class String
 
class Object
 
class Context
 
class Isolate
 
class Private
 
template<class F >
class internal::CustomArguments
 
class HandleScope
 
class EscapableHandleScope
 
template<class F1 , class F2 , class F3 >
class PersistentValueMapBase
 
template<class F1 , class F2 >
class PersistentValueVector
 
template<class F >
class ReturnValue
 
template<class F >
class Traced
 
template<class F >
class TracedGlobal
 
template<class F >
class BasicTracedReference
 
template<class F >
class TracedReference
 
Local< Primitive > Undefined (Isolate *isolate)
 
Local< Primitive > Null (Isolate *isolate)
 
Local< Boolean > True (Isolate *isolate)
 
Local< Boolean > False (Isolate *isolate)
 

Detailed Description

template<class T>
class v8::Local< T >

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.

Definition at line 201 of file v8.h.

Constructor & Destructor Documentation

◆ Local() [1/2]

V8_INLINE Local ( )
inline

Definition at line 203 of file v8.h.

Referenced by V8InspectorClient::ensureDefaultContextInGroup(), TracedReferenceBase::Get(), and Extension::GetNativeFunctionTemplate().

◆ Local() [2/2]

V8_INLINE Local ( Local< S >  that)
inline

This check fails when trying to convert between incompatible handles. For example, converting from a Local<String> to a Local<Number>.

Definition at line 205 of file v8.h.

Member Function Documentation

◆ As()

V8_INLINE Local<S> As ( ) const
inline

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.

Definition at line 297 of file v8.h.

References Local< T >::Local.

◆ Cast()

static V8_INLINE Local<T> Cast ( Local< S >  that)
inlinestatic

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.

Definition at line 282 of file v8.h.

References Local< T >::Local.

◆ Clear()

V8_INLINE void Clear ( )
inline

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

Definition at line 223 of file v8.h.

◆ IsEmpty()

V8_INLINE bool IsEmpty ( ) const
inline

Returns true if the handle is empty.

Definition at line 218 of file v8.h.

Referenced by ScriptOrigin::ScriptOrigin().

◆ New() [1/3]

Local< T > New ( Isolate *  isolate,
const BasicTracedReference< T > &  that 
)
static

Definition at line 10919 of file v8.h.

◆ New() [2/3]

Local< T > New ( Isolate *  isolate,
const PersistentBase< T > &  that 
)
static

Definition at line 10914 of file v8.h.

◆ New() [3/3]

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

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.

Definition at line 10909 of file v8.h.

◆ operator!=() [1/2]

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

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.

Definition at line 268 of file v8.h.

◆ operator!=() [2/2]

V8_INLINE bool operator!= ( const Persistent< S > &  that) const
inline

Definition at line 272 of file v8.h.

◆ operator*()

V8_INLINE T* operator* ( ) const
inline

Definition at line 227 of file v8.h.

◆ operator->()

V8_INLINE T* operator-> ( ) const
inline

Definition at line 225 of file v8.h.

Referenced by Context::Scope::Scope(), ScriptOrigin::ScriptOrigin(), and Context::Scope::~Scope().

◆ operator==() [1/2]

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

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.

Definition at line 240 of file v8.h.

◆ operator==() [2/2]

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

Definition at line 248 of file v8.h.

Friends And Related Function Documentation

◆ BasicTracedReference

friend class BasicTracedReference
friend

Definition at line 345 of file v8.h.

Referenced by BasicTracedReference< T >::As(), TracedGlobal< T >::Reset(), TracedReference< T >::Reset(), TracedGlobal< T >::TracedGlobal(), and TracedReference< T >::TracedReference().

◆ Context

friend class Context
friend

Definition at line 325 of file v8.h.

◆ EscapableHandleScope

friend class EscapableHandleScope
friend

Definition at line 334 of file v8.h.

◆ Eternal

friend class Eternal
friend

Definition at line 315 of file v8.h.

◆ False

Local<Boolean> False ( Isolate *  isolate)
friend

Definition at line 12228 of file v8.h.

Referenced by Boolean::New().

◆ FunctionCallbackInfo

friend class FunctionCallbackInfo
friend

Definition at line 321 of file v8.h.

◆ HandleScope

friend class HandleScope
friend

Definition at line 333 of file v8.h.

◆ internal::CustomArguments

friend class internal::CustomArguments
friend

Definition at line 328 of file v8.h.

◆ Isolate

friend class Isolate
friend

Definition at line 326 of file v8.h.

◆ Local

friend class Local
friend

Definition at line 318 of file v8.h.

Referenced by Local< T >::As(), Local< T >::Cast(), FunctionCallbackInfo< T >::Data(), PropertyCallbackInfo< T >::Data(), String::Empty(), V8InspectorClient::ensureDefaultContextInGroup(), EscapableHandleScope::Escape(), EscapableHandleScope::EscapeMaybe(), MaybeLocal< T >::FromMaybe(), ReturnValue< T >::Get(), PersistentValueMapBase< K, V, Traits >::Get(), Eternal< T >::Get(), PersistentBase< T >::Get(), BasicTracedReference< T >::Get(), PersistentValueVector< V, Traits >::Get(), TracedReferenceBase::Get(), Isolate::GetDataFromSnapshotOnce(), Context::GetDataFromSnapshotOnce(), Context::GetEmbedderData(), Object::GetInternalField(), Extension::GetNativeFunctionTemplate(), FunctionCallbackInfo< T >::Holder(), PropertyCallbackInfo< T >::Holder(), PersistentValueMapBase< K, V, Traits >::PersistentValueReference::NewLocal(), FunctionCallbackInfo< T >::NewTarget(), FunctionCallbackInfo< T >::operator[](), PersistentValueMap< K, V, Traits >::SetUnique(), GlobalValueMap< K, V, Traits >::SetUnique(), FunctionCallbackInfo< T >::This(), PropertyCallbackInfo< T >::This(), and MaybeLocal< T >::ToLocalChecked().

◆ MaybeLocal

friend class MaybeLocal
friend

Definition at line 320 of file v8.h.

Referenced by V8InspectorClient::memoryInfo().

◆ Null

Local<Primitive> Null ( Isolate *  isolate)
friend

Definition at line 12210 of file v8.h.

◆ Object

friend class Object
friend

Definition at line 324 of file v8.h.

◆ Persistent

friend class Persistent
friend

Persistent is a way to create a strong pointer from an off-heap object to another on-heap object. As long as the Persistent handle is alive the GC will keep the object pointed to alive. The Persistent handle is always a GC root from the point of view of the GC. Persistent must be constructed and destructed in the same thread.

Definition at line 317 of file v8.h.

Referenced by Persistent< T, M >::As(), and Persistent< T, M >::Cast().

◆ PersistentBase

friend class PersistentBase
friend

Definition at line 316 of file v8.h.

Referenced by Global< T >::Global(), and Persistent< T, M >::Persistent().

◆ PersistentValueMapBase

friend class PersistentValueMapBase
friend

Definition at line 336 of file v8.h.

◆ PersistentValueVector

friend class PersistentValueVector
friend

Definition at line 337 of file v8.h.

◆ Private

friend class Private
friend

Definition at line 327 of file v8.h.

◆ PropertyCallbackInfo

friend class PropertyCallbackInfo
friend

Definition at line 322 of file v8.h.

◆ ReturnValue

friend class ReturnValue
friend

Definition at line 339 of file v8.h.

Referenced by FunctionCallbackInfo< T >::GetReturnValue(), and PropertyCallbackInfo< T >::GetReturnValue().

◆ String

friend class String
friend

Definition at line 323 of file v8.h.

◆ Traced

friend class Traced
friend

Definition at line 341 of file v8.h.

◆ TracedGlobal

friend class TracedGlobal
friend

Definition at line 343 of file v8.h.

Referenced by TracedGlobal< T >::As().

◆ TracedReference

friend class TracedReference
friend

Definition at line 347 of file v8.h.

Referenced by TracedReference< T >::As().

◆ TracedReferenceBase

friend class TracedReferenceBase
friend

Definition at line 313 of file v8.h.

◆ True

Local<Boolean> True ( Isolate *  isolate)
friend

Definition at line 12219 of file v8.h.

Referenced by Boolean::New().

◆ Undefined

Local<Primitive> Undefined ( Isolate *  isolate)
friend

Definition at line 12201 of file v8.h.

◆ Utils

friend class Utils
friend

Definition at line 314 of file v8.h.

The documentation for this class was generated from the following files: