Public Member Functions | Static Public Member Functions | Friends | List of all members
v8::Local< T > Class Template Reference

#include <v8.h>

Inheritance diagram for v8::Local< T >:
[legend]

Public Member Functions

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

Static Public Member Functions

template<class S >
static Local< T > Cast (Local< S > that)
 
static Local< T > New (Isolate *isolate, Local< T > that)
 
static Local< T > New (Isolate *isolate, const PersistentBase< T > &that)
 
static 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< PrimitiveUndefined (Isolate *isolate)
 
Local< PrimitiveNull (Isolate *isolate)
 
Local< BooleanTrue (Isolate *isolate)
 
Local< BooleanFalse (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.

Examples
process.cc, and shell.cc.

Constructor & Destructor Documentation

◆ Local() [1/2]

template<class T >
v8::Local< T >::Local ( )
inline

◆ Local() [2/2]

template<class T >
template<class S >
v8::Local< T >::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>.

Member Function Documentation

◆ As()

template<class T >
template<class S >
Local<S> v8::Local< T >::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.

Here is the call graph for this function:

◆ Cast()

template<class T >
template<class S >
static Local<T> v8::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.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ Clear()

template<class T >
void v8::Local< T >::Clear ( )
inline

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

◆ IsEmpty()

template<class T >
bool v8::Local< T >::IsEmpty ( ) const
inline

Returns true if the handle is empty.

Examples
shell.cc.
Here is the caller graph for this function:

◆ New() [1/3]

template<class T >
Local< T > v8::Local< T >::New ( Isolate isolate,
const BasicTracedReference< T > &  that 
)
inlinestatic

◆ New() [2/3]

template<class T >
Local< T > v8::Local< T >::New ( Isolate isolate,
const PersistentBase< T > &  that 
)
inlinestatic

◆ New() [3/3]

template<class T >
Local< T > v8::Local< T >::New ( Isolate isolate,
Local< T >  that 
)
inlinestatic

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.

Examples
process.cc.
Here is the caller graph for this function:

◆ operator!=() [1/2]

template<class T >
template<class S >
bool v8::Local< T >::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.

Here is the call graph for this function:

◆ operator!=() [2/2]

template<class T >
template<class S >
bool v8::Local< T >::operator!= ( const Persistent< S > &  that) const
inline
Here is the call graph for this function:

◆ operator*()

template<class T >
T* v8::Local< T >::operator* ( ) const
inline

◆ operator->()

template<class T >
T* v8::Local< T >::operator-> ( ) const
inline

◆ operator==() [1/2]

template<class T >
template<class S >
bool v8::Local< T >::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.

Here is the caller graph for this function:

◆ operator==() [2/2]

template<class T >
template<class S >
bool v8::Local< T >::operator== ( const PersistentBase< S > &  that) const
inline

Friends And Related Function Documentation

◆ BasicTracedReference

template<class T >
template<class F >
friend class BasicTracedReference
friend

◆ Context

template<class T >
friend class Context
friend

◆ EscapableHandleScope

template<class T >
friend class EscapableHandleScope
friend

◆ Eternal

template<class T >
template<class F >
friend class Eternal
friend

◆ False

template<class T >
Local<Boolean> False ( Isolate isolate)
friend

◆ FunctionCallbackInfo

template<class T >
template<class F >
friend class FunctionCallbackInfo
friend

◆ HandleScope

template<class T >
friend class HandleScope
friend

◆ internal::CustomArguments

template<class T >
template<class F >
friend class internal::CustomArguments
friend

◆ Isolate

template<class T >
friend class Isolate
friend

◆ Local

template<class T >
template<class F >
friend class Local
friend

◆ MaybeLocal

template<class T >
template<class F >
friend class MaybeLocal
friend

◆ Null

template<class T >
Local<Primitive> Null ( Isolate isolate)
friend

◆ Object

template<class T >
friend class Object
friend

◆ Persistent

template<class T >
template<class F , class M >
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.

◆ PersistentBase

template<class T >
template<class F >
friend class PersistentBase
friend

◆ PersistentValueMapBase

template<class T >
template<class F1 , class F2 , class F3 >
friend class PersistentValueMapBase
friend

◆ PersistentValueVector

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

◆ Private

template<class T >
friend class Private
friend

◆ PropertyCallbackInfo

template<class T >
template<class F >
friend class PropertyCallbackInfo
friend

◆ ReturnValue

template<class T >
template<class F >
friend class ReturnValue
friend

◆ String

template<class T >
friend class String
friend

◆ Traced

template<class T >
template<class F >
friend class Traced
friend

◆ TracedGlobal

template<class T >
template<class F >
friend class TracedGlobal
friend

◆ TracedReference

template<class T >
template<class F >
friend class TracedReference
friend

◆ TracedReferenceBase

template<class T >
friend class TracedReferenceBase
friend

◆ True

template<class T >
Local<Boolean> True ( Isolate isolate)
friend

◆ Undefined

template<class T >
Local<Primitive> Undefined ( Isolate isolate)
friend

◆ Utils

template<class T >
friend class Utils
friend

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