Handle< T > Class Template Reference

#include <v8.h>

Inheritance diagram for Handle< T >:

Public Member Functions
V8_INLINE	Handle ()
template<class S >
V8_INLINE	Handle (Handle< 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 Handle< S > &that) const
template<class S >
V8_INLINE bool	operator== (const PersistentBase< S > &that) const
template<class S >
V8_INLINE bool	operator!= (const Handle< S > &that) const
template<class S >
V8_INLINE bool	operator!= (const Persistent< S > &that) const
template<class S >
V8_INLINE Handle< S >	As ()

Static Public Member Functions
template<class S >
static V8_INLINE Handle< T >	Cast (Handle< S > that)
static V8_INLINE Handle< T >	New (Isolate *isolate, Handle< T > that)
static V8_INLINE Handle< T >	New (Isolate *isolate, const PersistentBase< T > &that)

Friends
class	Utils
template<class F , class M >
class	Persistent
template<class F >
class	PersistentBase
template<class F >
class	Handle
template<class F >
class	Local
template<class F >
class	FunctionCallbackInfo
template<class F >
class	PropertyCallbackInfo
template<class F >
class	internal::CustomArguments
class	Context
class	HandleScope
class	Object
class	Private
Handle< Primitive >	Undefined (Isolate *isolate)
Handle< Primitive >	Null (Isolate *isolate)
Handle< Boolean >	True (Isolate *isolate)
Handle< Boolean >	False (Isolate *isolate)

Detailed Description

template<class T>
class v8::Handle< 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. 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 Handle<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 196 of file v8.h.

Constructor & Destructor Documentation

Handle() [1/2]

V8_INLINE Handle ( )

inline

Creates an empty handle.

Definition at line 201 of file v8.h.

Referenced by Extension::GetNativeFunctionTemplate().

Handle() [2/2]

V8_INLINE Handle ( Handle< S >  that )

inline

Creates a handle for the contents of the specified handle. This constructor allows you to pass handles as arguments by value and to assign between handles. However, if you try to assign between incompatible handles, for instance from a Handle<String> to a Handle<Number> it will cause a compile-time error. Assigning between compatible handles, for instance assigning a Handle<String> to a variable declared as Handle<Value>, is legal because String is a subclass of Value.

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

Definition at line 213 of file v8.h.

Member Function Documentation

As()

V8_INLINE Handle<S> As ( )

inline

Definition at line 284 of file v8.h.

References Handle< T >::Handle.

Cast()

static V8_INLINE Handle<T> Cast ( Handle< S >  that )

inlinestatic

Definition at line 275 of file v8.h.

References Handle< T >::Handle.

Clear()

V8_INLINE void Clear ( )

inline

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

Definition at line 231 of file v8.h.

IsEmpty()

V8_INLINE bool IsEmpty ( ) const

inline

Returns true if the handle is empty.

Definition at line 226 of file v8.h.

New() [1/2]

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

inlinestatic

Definition at line 291 of file v8.h.

New() [2/2]

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

inlinestatic

Definition at line 288 of file v8.h.

operator!=() [1/2]

V8_INLINE bool operator!= ( const Handle< 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. The handles' references are not checked.

Definition at line 266 of file v8.h.

operator!=() [2/2]

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

inline

Definition at line 270 of file v8.h.

operator*()

V8_INLINE T* operator* ( ) const

inline

Definition at line 235 of file v8.h.

Referenced by Eternal< T >::Get().

operator->()

V8_INLINE T* operator-> ( ) const

inline

Definition at line 233 of file v8.h.

Referenced by Context::Scope::Scope(), Script::V8_DEPRECATED(), and Context::Scope::~Scope().

operator==() [1/2]

V8_INLINE bool operator== ( const Handle< 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. The handles' references are not checked.

Definition at line 243 of file v8.h.

operator==() [2/2]

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

inline

Definition at line 251 of file v8.h.

Friends And Related Function Documentation

Context

friend class Context

friend

Definition at line 309 of file v8.h.

False

Handle<Boolean> False ( Isolate *  isolate )

friend

Definition at line 6622 of file v8.h.

Referenced by Boolean::New().

FunctionCallbackInfo

friend class FunctionCallbackInfo

friend

Definition at line 302 of file v8.h.

Handle

friend class Handle

friend

Definition at line 300 of file v8.h.

Referenced by Handle< T >::As(), Handle< T >::Cast(), Extension::GetNativeFunctionTemplate(), and Local< T >::Local().

HandleScope

friend class HandleScope

friend

Definition at line 310 of file v8.h.

internal::CustomArguments

friend class internal::CustomArguments

friend

Definition at line 304 of file v8.h.

Local

friend class Local

friend

Definition at line 301 of file v8.h.

Referenced by Local< T >::As(), FunctionCallbackInfo< T >::Callee(), Local< T >::Cast(), FunctionCallbackInfo< T >::Data(), PropertyCallbackInfo< T >::Data(), String::Empty(), EscapableHandleScope::Escape(), PersistentValueMap< K, V, Traits >::Get(), Eternal< T >::Get(), PersistentValueVector< V, Traits >::Get(), Context::GetEmbedderData(), Object::GetInternalField(), FunctionCallbackInfo< T >::Holder(), PropertyCallbackInfo< T >::Holder(), PersistentValueMap< K, V, Traits >::PersistentValueReference::NewLocal(), FunctionCallbackInfo< T >::operator[](), FunctionCallbackInfo< T >::This(), and PropertyCallbackInfo< T >::This().

Null

Handle<Primitive> Null ( Isolate *  isolate )

friend

Definition at line 6604 of file v8.h.

Object

friend class Object

friend

Definition at line 311 of file v8.h.

Persistent

friend class Persistent

friend

Definition at line 298 of file v8.h.

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

PersistentBase

friend class PersistentBase

friend

Definition at line 299 of file v8.h.

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

Private

friend class Private

friend

Definition at line 312 of file v8.h.

PropertyCallbackInfo

friend class PropertyCallbackInfo

friend

Definition at line 303 of file v8.h.

True

Handle<Boolean> True ( Isolate *  isolate )

friend

Definition at line 6613 of file v8.h.

Referenced by Boolean::New().

Undefined

Handle<Primitive> Undefined ( Isolate *  isolate )

friend

Definition at line 6595 of file v8.h.

Utils

friend class Utils

friend

Definition at line 297 of file v8.h.

---

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

• include/v8.h