Handle< T > Class Template Reference

#include <v8.h>

Inheritance diagram for Handle< T >:

Public Member Functions
	Handle ()
	Handle (T *val)
template<class S >
	Handle (Handle< S > that)
bool	IsEmpty () const
void	Clear ()
T *	operator-> () const
T *	operator* () const
template<class S >
bool	operator== (Handle< S > that) const
template<class S >
bool	operator!= (Handle< S > that) const
template<class S >
Handle< S >	As ()
template<typename T >
	Handle (T *obj)
template<typename T >
	Handle (T *obj, Isolate *isolate)

Static Public Member Functions
template<class S >
static Handle< T >	Cast (Handle< S > that)

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 104 of file v8.h.

Constructor & Destructor Documentation

Handle ( )

inline

Creates an empty handle.

Definition at line 178 of file v8.h.

Handle ( T *  val )

inlineexplicit

Creates a new handle for the specified value.

Definition at line 183 of file v8.h.

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 195 of file v8.h.

Handle

(

T *

obj

)

Definition at line 49 of file handles-inl.h.

References ASSERT, HandleScope::CreateHandle(), and v8::internal::GetIsolateForHandle().

Handle	(	T *	obj,
		Isolate *	isolate
	)

Definition at line 56 of file handles-inl.h.

References ASSERT, and HandleScope::CreateHandle().

Member Function Documentation

Handle<S> As ( )

inline

Definition at line 252 of file v8.h.

Referenced by CheckOwnProperties(), CheckProperties(), CThrowCountDown(), HasOwnPropertyIndexedPropertyQuery(), HasOwnPropertyNamedPropertyQuery(), HasOwnPropertyNamedPropertyQuery2(), TEST(), and THREADED_TEST().

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

inlinestatic

Definition at line 243 of file v8.h.

Referenced by Handle< Value >::As(), Shell::GetCompletions(), RunCppCycle(), Shell::System(), TEST(), THREADED_TEST(), and WhammyPropertyGetter().

void Clear ( )

inline

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

Definition at line 213 of file v8.h.

Referenced by TEST(), THREADED_TEST(), and WhammyPropertyGetter().

bool IsEmpty ( ) const

inline

Returns true if the handle is empty.

Definition at line 208 of file v8.h.

Referenced by V8::AddMessageListener(), AnalyzeStackOfEvalWithSourceURL(), String::AsciiValue::AsciiValue(), DeclarationContext::Check(), Shell::CreateEvaluationContext(), SourceGroup::Execute(), ExecuteString(), Shell::ExecuteString(), CpuProfiler::FindProfile(), v8::internal::GetKeysInFixedArrayFor(), CpuProfiler::GetProfile(), JSObject::GetPropertyAttributeWithInterceptor(), Whammy::getScript(), JSObject::HasElementWithInterceptor(), LocalContext::IsReady(), Load(), Shell::Load(), Loop(), main(), Script::New(), FunctionTemplate::New(), Signature::New(), Context::New(), PrintExtension::Print(), JsHttpRequestProcessor::Process(), Read(), Shell::Read(), ReportException(), Shell::ReportException(), ShellThread::Run(), RunMain(), v8::internal::RUNTIME_FUNCTION(), ObjectTemplate::SetAccessCheckCallbacks(), FunctionTemplate::SetCallHandler(), CpuProfiler::StopProfiling(), TEST(), THREADED_TEST(), v8::ThrowException(), String::Utf8Value::Utf8Value(), String::Value::Value(), and WhammyPropertyGetter().

bool operator!= ( 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 239 of file v8.h.

T * operator* ( ) const

inline

Definition at line 217 of file v8.h.

T* operator-> ( ) const

inline

Definition at line 215 of file v8.h.

bool operator== ( 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 225 of file v8.h.

Referenced by Handle< Value >::operator!=().

---

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

• include/v8.h
• src/handles-inl.h