V8 Project
Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Friends | List of all members
v8::Handle< T > Class Template Reference

An object reference managed by the v8 garbage collector. More...

#include <v8.h>

+ Inheritance diagram for v8::Handle< T >:
+ Collaboration diagram for v8::Handle< T >:

Public Member Functions

 Handle ()
 Creates an empty handle. More...
 
template<class S >
 Handle (Handle< S > that)
 Creates a handle for the contents of the specified handle. More...
 
bool IsEmpty () const
 Returns true if the handle is empty. More...
 
void Clear ()
 Sets the handle to be empty. More...
 
T * operator-> () const
 
T * operator* () const
 
template<class S >
bool operator== (const Handle< S > &that) const
 Checks whether two handles are the same. More...
 
template<class S >
bool operator== (const PersistentBase< S > &that) const
 
template<class S >
bool operator!= (const Handle< S > &that) const
 Checks whether two handles are different. More...
 
template<class S >
bool operator!= (const Persistent< S > &that) const
 
template<class S >
Handle< S > As ()
 

Static Public Member Functions

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

Private Member Functions

 Handle (T *val)
 Creates a new handle for the specified value. More...
 

Static Private Member Functions

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

Private Attributes

T * val_
 

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

Constructor & Destructor Documentation

◆ Handle() [1/3]

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

Creates an empty handle.

Definition at line 203 of file v8.h.

203 : val_(0) {}
v8::Handle::val_
T * val_
Definition: v8.h:323

◆ Handle() [2/3]

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

216  : val_(reinterpret_cast<T*>(*that)) {
217  /**
218  * This check fails when trying to convert between incompatible
219  * handles. For example, converting from a Handle<String> to a
220  * Handle<Number>.
221  */
222  TYPE_CHECK(T, S);
223  }
TYPE_CHECK
#define TYPE_CHECK(T, S)
Definition: v8.h:167
T
#define T(name, string, precedence)
Definition: token.cc:25
S
#define S(x)
Definition: version.cc:55

References S, T, and TYPE_CHECK.

◆ Handle() [3/3]

template<class T >
v8::Handle< T >::Handle ( T *  val)
inlineexplicitprivate

Creates a new handle for the specified value.

Definition at line 319 of file v8.h.

319 : val_(val) {}

Member Function Documentation

◆ As()

template<class T >
template<class S >
Handle<S> v8::Handle< T >::As ( )
inline

Definition at line 286 of file v8.h.

286  {
287  return Handle<S>::Cast(*this);
288  }
v8::Handle::Cast
static Handle< T > Cast(Handle< S > that)
Definition: v8.h:277

References v8::Handle< T >::Cast().

+ Here is the call graph for this function:

◆ Cast()

template<class T >
template<class S >
static Handle<T> v8::Handle< T >::Cast ( Handle< S >  that)
inlinestatic

Definition at line 277 of file v8.h.

277  {
278 #ifdef V8_ENABLE_CHECKS
279  // If we're going to perform the type check then we have to check
280  // that the handle isn't empty before doing the checked cast.
281  if (that.IsEmpty()) return Handle<T>();
282 #endif
283  return Handle<T>(T::Cast(*that));
284  }

References v8::Handle< T >::IsEmpty().

Referenced by v8::Handle< T >::As(), v8::Shell::DebugCommandToJSONRequest(), v8::Shell::DebugMessageDetails(), v8::internal::DeleteNativeObjectAt(), v8::Shell::ExecuteString(), v8::HandleDebugEvent(), and v8::Shell::System().

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

◆ Clear()

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

Sets the handle to be empty.

IsEmpty() will then return true.

Definition at line 233 of file v8.h.

233 { val_ = 0; }

References v8::Handle< T >::val_.

◆ IsEmpty()

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

Returns true if the handle is empty.

Definition at line 228 of file v8.h.

228 { return val_ == 0; }

References v8::Handle< T >::val_.

Referenced by v8::V8::AddMessageListener(), v8::Debug::Call(), v8::Handle< T >::Cast(), v8::Local< T >::Cast(), v8::CreateEnvironment(), v8::Shell::CreateEvaluationContext(), v8::internal::JSObject::DeleteElementWithInterceptor(), v8::internal::JSObject::DeletePropertyWithInterceptor(), v8::Value::Equals(), v8::SourceGroup::Execute(), v8::Shell::ExecuteString(), v8::FunctionTemplateNew(), v8::internal::JSObject::GetElementAttributeWithInterceptor(), v8::internal::JSObject::GetElementWithCallback(), v8::internal::JSObject::GetElementWithInterceptor(), v8::internal::MessageImpl::GetEventContext(), v8::internal::JSObject::GetKeysForIndexedInterceptor(), v8::internal::JSObject::GetKeysForNamedInterceptor(), v8::Debug::GetMirror(), v8::internal::JSObject::GetPropertyAttributesWithInterceptor(), v8::internal::Object::GetPropertyWithAccessor(), v8::internal::JSObject::GetPropertyWithInterceptor(), v8::internal::HandleApiCallAsFunctionOrConstructor(), v8::internal::HandleApiCallHelper(), v8::Shell::Load(), v8::MakeAccessorInfo(), v8::ObjectTemplate::New(), v8::Signature::New(), v8::Shell::Read(), v8::Shell::RealmEval(), v8::Shell::ReportException(), v8::PersistentBase< T >::Reset(), v8::Shell::RunShell(), v8::internal::RUNTIME_FUNCTION(), v8::Value::SameValue(), v8::ObjectTemplate::SetAccessCheckCallbacks(), v8::SetAccessorInfoProperties(), v8::Template::SetAccessorProperty(), v8::ObjectTemplate::SetCallAsFunctionHandler(), v8::FunctionTemplate::SetCallHandler(), v8::internal::JSObject::SetElementWithInterceptor(), v8::Object::SetHiddenValue(), v8::ObjectTemplate::SetIndexedPropertyHandler(), v8::ObjectTemplate::SetNamedPropertyHandler(), v8::internal::JSObject::SetPropertyWithInterceptor(), v8::Value::StrictEquals(), v8::TemplateSet(), v8::Isolate::ThrowException(), v8::String::Utf8Value::Utf8Value(), and v8::String::Value::Value().

+ Here is the caller graph for this function:

◆ New() [1/3]

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

Definition at line 293 of file v8.h.

294  {
295  return New(isolate, that.val_);
296  }
v8::Handle::New
static Handle< T > New(Isolate *isolate, Handle< T > that)
Definition: v8.h:290

References v8::Handle< T >::New(), and v8::PersistentBase< T >::val_.

+ Here is the call graph for this function:

◆ New() [2/3]

template<class T >
static Handle<T> v8::Handle< T >::New ( Isolate *  isolate,
Handle< T >  that 
)
inlinestatic

Definition at line 290 of file v8.h.

290  {
291  return New(isolate, that.val_);
292  }

References v8::Handle< T >::val_.

Referenced by v8::Handle< T >::New().

+ Here is the caller graph for this function:

◆ New() [3/3]

template<class T >
Handle< T > v8::Handle< T >::New ( Isolate *  isolate,
T *  that 
)
inlinestaticprivate

Definition at line 5997 of file v8.h.

5997  {
5998  if (that == NULL) return Handle<T>();
5999  T* that_ptr = that;
6000  internal::Object** p = reinterpret_cast<internal::Object**>(that_ptr);
6001  return Handle<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
6002  reinterpret_cast<internal::Isolate*>(isolate), *p)));
6003 }
v8::HandleScope::CreateHandle
static internal::Object ** CreateHandle(internal::Isolate *isolate, internal::Object *value)
Definition: api.cc:579
NULL
enable harmony numeric enable harmony object literal extensions Optimize object Array DOM strings and string trace pretenuring decisions of HAllocate instructions Enables optimizations which favor memory size over execution speed maximum source size in bytes considered for a single inlining maximum cumulative number of AST nodes considered for inlining trace the tracking of allocation sites deoptimize every n garbage collections perform array bounds checks elimination analyze liveness of environment slots and zap dead values flushes the cache of optimized code for closures on every GC allow uint32 values on optimize frames if they are used only in safe operations track concurrent recompilation artificial compilation delay in ms do not emit check maps for constant values that have a leaf deoptimize the optimized code if the layout of the maps changes enable context specialization in TurboFan execution budget before interrupt is triggered max percentage of megamorphic generic ICs to allow optimization enable use of SAHF instruction if enable use of VFP3 instructions if available enable use of NEON instructions if enable use of SDIV and UDIV instructions if enable use of MLS instructions if enable loading bit constant by means of movw movt instruction enable unaligned accesses for enable use of d16 d31 registers on ARM this requires VFP3 force all emitted branches to be in long enable alignment of csp to bytes on platforms which prefer the register to always be NULL
Definition: flag-definitions.h:407
v8::internal::Object
kSerializedDataOffset Object
Definition: objects-inl.h:5322

References v8::HandleScope::CreateHandle(), NULL, and T.

+ Here is the call graph for this function:

◆ operator!=() [1/2]

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

268  {
269  return !operator==(that);
270  }
v8::Handle::operator==
bool operator==(const Handle< S > &that) const
Checks whether two handles are the same.
Definition: v8.h:245

References v8::Handle< T >::operator==().

+ Here is the call graph for this function:

◆ operator!=() [2/2]

template<class T >
template<class S >
bool v8::Handle< T >::operator!= ( const Persistent< S > &  that) const
inline

Definition at line 272 of file v8.h.

273  {
274  return !operator==(that);
275  }

References v8::Handle< T >::operator==().

+ Here is the call graph for this function:

◆ operator*()

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

Definition at line 237 of file v8.h.

237 { return val_; }

References v8::Handle< T >::val_.

◆ operator->()

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

Definition at line 235 of file v8.h.

235 { return val_; }

References v8::Handle< T >::val_.

◆ operator==() [1/2]

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

245  {
246  internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);
247  internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);
248  if (a == 0) return b == 0;
249  if (b == 0) return false;
250  return *a == *b;
251  }

References v8::Handle< T >::val_.

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

+ Here is the caller graph for this function:

◆ operator==() [2/2]

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

Definition at line 253 of file v8.h.

254  {
255  internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);
256  internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);
257  if (a == 0) return b == 0;
258  if (b == 0) return false;
259  return *a == *b;
260  }

References v8::Handle< T >::val_, and v8::PersistentBase< T >::val_.

Friends And Related Function Documentation

◆ Context

template<class T >
friend class Context
friend

Definition at line 311 of file v8.h.

◆ False

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

Definition at line 6863 of file v8.h.

6863  {
6864  typedef internal::Object* S;
6865  typedef internal::Internals I;
6866  I::CheckInitialized(isolate);
6867  S* slot = I::GetRoot(isolate, I::kFalseValueRootIndex);
6868  return Handle<Boolean>(reinterpret_cast<Boolean*>(slot));
6869 }
I
#define I(name, number_of_args, result_size)
Definition: runtime.cc:9248

◆ FunctionCallbackInfo

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

Definition at line 304 of file v8.h.

◆ Handle

template<class T >
template<class F >
friend class Handle
friend

Definition at line 302 of file v8.h.

◆ HandleScope

template<class T >
friend class HandleScope
friend

Definition at line 312 of file v8.h.

◆ internal::CustomArguments

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

Definition at line 306 of file v8.h.

◆ Local

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

Definition at line 303 of file v8.h.

◆ Null

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

Definition at line 6845 of file v8.h.

6845  {
6846  typedef internal::Object* S;
6847  typedef internal::Internals I;
6848  I::CheckInitialized(isolate);
6849  S* slot = I::GetRoot(isolate, I::kNullValueRootIndex);
6850  return Handle<Primitive>(reinterpret_cast<Primitive*>(slot));
6851 }

◆ Object

template<class T >
friend class Object
friend

Definition at line 313 of file v8.h.

◆ Persistent

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

Definition at line 300 of file v8.h.

◆ PersistentBase

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

Definition at line 301 of file v8.h.

◆ Private

template<class T >
friend class Private
friend

Definition at line 314 of file v8.h.

◆ PropertyCallbackInfo

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

Definition at line 305 of file v8.h.

◆ True

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

Definition at line 6854 of file v8.h.

6854  {
6855  typedef internal::Object* S;
6856  typedef internal::Internals I;
6857  I::CheckInitialized(isolate);
6858  S* slot = I::GetRoot(isolate, I::kTrueValueRootIndex);
6859  return Handle<Boolean>(reinterpret_cast<Boolean*>(slot));
6860 }

◆ Undefined

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

Definition at line 6836 of file v8.h.

6836  {
6837  typedef internal::Object* S;
6838  typedef internal::Internals I;
6839  I::CheckInitialized(isolate);
6840  S* slot = I::GetRoot(isolate, I::kUndefinedValueRootIndex);
6841  return Handle<Primitive>(reinterpret_cast<Primitive*>(slot));
6842 }

◆ Utils

template<class T >
friend class Utils
friend

Definition at line 299 of file v8.h.

Member Data Documentation

◆ val_

template<class T >
T* v8::Handle< T >::val_
private

Definition at line 323 of file v8.h.

Referenced by v8::Handle< T >::Clear(), v8::Handle< T >::IsEmpty(), v8::Handle< T >::New(), v8::Local< T >::New(), v8::Handle< T >::operator*(), v8::Handle< T >::operator->(), v8::Handle< T >::operator==(), v8::PersistentBase< T >::operator==(), and v8::PersistentBase< T >::Reset().

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