V8 API Reference Guide for node.js v0.12.15 - v0.12.17
Classes | Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
v8::Isolate Class Reference

#include <v8.h>

Classes

class  AllowJavascriptExecutionScope
 
class  DisallowJavascriptExecutionScope
 
class  Scope
 
class  SuppressMicrotaskExecutionScope
 

Public Types

enum  GarbageCollectionType { kFullGarbageCollection, kMinorGarbageCollection }
 
enum  UseCounterFeature { kUseAsm = 0, kUseCounterFeatureCount }
 
typedef void(* UseCounterCallback) (Isolate *isolate, UseCounterFeature feature)
 
typedef bool(* abort_on_uncaught_exception_t) (Isolate *)
 
typedef void(* GCPrologueCallback) (Isolate *isolate, GCType type, GCCallbackFlags flags)
 
typedef void(* GCEpilogueCallback) (Isolate *isolate, GCType type, GCCallbackFlags flags)
 

Public Member Functions

void SetAbortOnUncaughtException (abort_on_uncaught_exception_t callback)
 
void Enter ()
 
void Exit ()
 
void Dispose ()
 
V8_INLINE void SetData (uint32_t slot, void *data)
 
V8_INLINE void * GetData (uint32_t slot)
 
void GetHeapStatistics (HeapStatistics *heap_statistics)
 
V8_INLINE int64_t AdjustAmountOfExternalAllocatedMemory (int64_t change_in_bytes)
 
HeapProfilerGetHeapProfiler ()
 
CpuProfilerGetCpuProfiler ()
 
bool InContext ()
 
Local< ContextGetCurrentContext ()
 
Local< ContextGetCallingContext ()
 
Local< ContextGetEnteredContext ()
 
Local< ValueThrowException (Local< Value > exception)
 
template<typename T >
void SetObjectGroupId (const Persistent< T > &object, UniqueId id)
 
template<typename T >
void SetReferenceFromGroup (UniqueId id, const Persistent< T > &child)
 
template<typename T , typename S >
void SetReference (const Persistent< T > &parent, const Persistent< S > &child)
 
void AddGCPrologueCallback (GCPrologueCallback callback, GCType gc_type_filter=kGCTypeAll)
 
void RemoveGCPrologueCallback (GCPrologueCallback callback)
 
void AddGCEpilogueCallback (GCEpilogueCallback callback, GCType gc_type_filter=kGCTypeAll)
 
void RemoveGCEpilogueCallback (GCEpilogueCallback callback)
 
void RequestInterrupt (InterruptCallback callback, void *data)
 
void ClearInterrupt ()
 
void RequestGarbageCollectionForTesting (GarbageCollectionType type)
 
void SetEventLogger (LogEventCallback that)
 
void AddCallCompletedCallback (CallCompletedCallback callback)
 
void RemoveCallCompletedCallback (CallCompletedCallback callback)
 
void RunMicrotasks ()
 
void EnqueueMicrotask (Handle< Function > microtask)
 
void EnqueueMicrotask (MicrotaskCallback microtask, void *data=NULL)
 
void SetAutorunMicrotasks (bool autorun)
 
bool WillAutorunMicrotasks () const
 
void SetUseCounterCallback (UseCounterCallback callback)
 
void SetCounterFunction (CounterLookupCallback)
 
void SetCreateHistogramFunction (CreateHistogramCallback)
 
void SetAddHistogramSampleFunction (AddHistogramSampleCallback)
 
bool IdleNotification (int idle_time_in_ms)
 
void LowMemoryNotification ()
 
int ContextDisposedNotification ()
 

Static Public Member Functions

static IsolateNew ()
 
static IsolateGetCurrent ()
 
static V8_INLINE uint32_t GetNumberOfDataSlots ()
 

Friends

template<class K , class V , class Traits >
class PersistentValueMap
 

Detailed Description

Isolate represents an isolated instance of the V8 engine. V8 isolates have completely separate states. Objects from one isolate must not be used in other isolates. When V8 is initialized a default isolate is implicitly created and entered. The embedder can create additional isolates and use them in parallel in multiple threads. An isolate can be entered by at most one thread at any given time. The Locker/Unlocker API must be used to synchronize.

Member Typedef Documentation

typedef bool(* v8::Isolate::abort_on_uncaught_exception_t) (Isolate *)

Custom callback used by embedders to help V8 determine if it should abort when it throws and no internal handler can catch the exception. If FLAG_abort_on_uncaught_exception is true, then V8 will abort if either:

  • no custom callback is set.
  • the custom callback set returns true. Otherwise it won't abort.

Member Enumeration Documentation

Types of garbage collections that can be requested via RequestGarbageCollectionForTesting.

Features reported via the SetUseCounterCallback callback. Do not chang assigned numbers of existing items; add new features to the end of this list.

Member Function Documentation

void v8::Isolate::AddCallCompletedCallback ( CallCompletedCallback  callback)

Adds a callback to notify the host application when a script finished running. If a script re-enters the runtime during executing, the CallCompletedCallback is only invoked when the outer-most script execution ends. Executing scripts inside the callback do not trigger further callbacks.

void v8::Isolate::AddGCEpilogueCallback ( GCEpilogueCallback  callback,
GCType  gc_type_filter = kGCTypeAll 
)

Enables the host application to receive a notification after a garbage collection. Allocations are allowed in the callback function, but the callback is not re-entrant: if the allocation inside it will trigger the garbage collection, the callback won't be called again. It is possible to specify the GCType filter for your callback. But it is not possible to register the same callback function two times with different GCType filters.

void v8::Isolate::AddGCPrologueCallback ( GCPrologueCallback  callback,
GCType  gc_type_filter = kGCTypeAll 
)

Enables the host application to receive a notification before a garbage collection. Allocations are allowed in the callback function, but the callback is not re-entrant: if the allocation inside it will trigger the garbage collection, the callback won't be called again. It is possible to specify the GCType filter for your callback. But it is not possible to register the same callback function two times with different GCType filters.

int64_t v8::Isolate::AdjustAmountOfExternalAllocatedMemory ( int64_t  change_in_bytes)

Adjusts the amount of registered external memory. Used to give V8 an indication of the amount of externally allocated memory that is kept alive by JavaScript objects. V8 uses this to decide when to perform global garbage collections. Registering externally allocated memory will trigger global garbage collections more often than it would otherwise in an attempt to garbage collect the JavaScript objects that keep the externally allocated memory alive.

Parameters
change_in_bytesthe change in externally allocated memory that is kept alive by JavaScript objects.
Returns
the adjusted value.
void v8::Isolate::ClearInterrupt ( )

Clear interrupt request created by |RequestInterrupt|. Can be called from another thread without acquiring a |Locker|.

int v8::Isolate::ContextDisposedNotification ( )

Optional notification that a context has been disposed. V8 uses these notifications to guide the GC heuristic. Returns the number of context disposals - including this one - since the last time V8 had a chance to clean up.

void v8::Isolate::Dispose ( )

Disposes the isolate. The isolate must not be entered by any thread to be disposable.

void v8::Isolate::EnqueueMicrotask ( Handle< Function microtask)

Experimental: Enqueues the callback to the Microtask Work Queue

void v8::Isolate::EnqueueMicrotask ( MicrotaskCallback  microtask,
void *  data = NULL 
)

Experimental: Enqueues the callback to the Microtask Work Queue

void v8::Isolate::Enter ( )

Methods below this point require holding a lock (using Locker) in a multi-threaded environment. Sets this isolate as the entered one for the current thread. Saves the previously entered one (if any), so that it can be restored when exiting. Re-entering an isolate is allowed.

void v8::Isolate::Exit ( )

Exits this isolate by restoring the previously entered one in the current thread. The isolate may still stay the same, if it was entered more than once.

Requires: this == Isolate::GetCurrent().

Local<Context> v8::Isolate::GetCallingContext ( )

Returns the context of the calling JavaScript code. That is the context of the top-most JavaScript frame. If there are no JavaScript frames an empty handle is returned.

CpuProfiler* v8::Isolate::GetCpuProfiler ( )

Returns CPU profiler for this isolate. Will return NULL unless the isolate is initialized. It is the embedder's responsibility to stop all CPU profiling activities if it has started any.

static Isolate* v8::Isolate::GetCurrent ( )
static

Returns the entered isolate for the current thread or NULL in case there is no current isolate.

Local<Context> v8::Isolate::GetCurrentContext ( )

Returns the context that is on the top of the stack.

void * v8::Isolate::GetData ( uint32_t  slot)

Retrieve embedder-specific data from the isolate. Returns NULL if SetData has never been called for the given |slot|.

Local<Context> v8::Isolate::GetEnteredContext ( )

Returns the last entered context.

HeapProfiler* v8::Isolate::GetHeapProfiler ( )

Returns heap profiler for this isolate. Will return NULL until the isolate is initialized.

void v8::Isolate::GetHeapStatistics ( HeapStatistics heap_statistics)

Get statistics about the heap memory usage.

uint32_t v8::Isolate::GetNumberOfDataSlots ( )
static

Returns the maximum number of available embedder data slots. Valid slots are in the range of 0 - GetNumberOfDataSlots() - 1.

bool v8::Isolate::IdleNotification ( int  idle_time_in_ms)

Optional notification that the embedder is idle. V8 uses the notification to reduce memory footprint. This call can be used repeatedly if the embedder remains idle. Returns true if the embedder should stop calling IdleNotification until real work has been done. This indicates that V8 has done as much cleanup as it will be able to do.

The idle_time_in_ms argument specifies the time V8 has to do reduce the memory footprint. There is no guarantee that the actual work will be done within the time limit.

bool v8::Isolate::InContext ( )

Returns true if this isolate has a current context.

void v8::Isolate::LowMemoryNotification ( )

Optional notification that the system is running low on memory. V8 uses these notifications to attempt to free memory.

static Isolate* v8::Isolate::New ( )
static

Creates a new isolate. Does not change the currently entered isolate.

When an isolate is no longer used its resources should be freed by calling Dispose(). Using the delete operator is not allowed.

void v8::Isolate::RemoveCallCompletedCallback ( CallCompletedCallback  callback)

Removes callback that was installed by AddCallCompletedCallback.

void v8::Isolate::RemoveGCEpilogueCallback ( GCEpilogueCallback  callback)

This function removes callback which was installed by AddGCEpilogueCallback function.

void v8::Isolate::RemoveGCPrologueCallback ( GCPrologueCallback  callback)

This function removes callback which was installed by AddGCPrologueCallback function.

void v8::Isolate::RequestGarbageCollectionForTesting ( GarbageCollectionType  type)

Request garbage collection in this Isolate. It is only valid to call this function if –expose_gc was specified.

This should only be used for testing purposes and not to enforce a garbage collection schedule. It has strong negative impact on the garbage collection performance. Use IdleNotification() or LowMemoryNotification() instead to influence the garbage collection schedule.

void v8::Isolate::RequestInterrupt ( InterruptCallback  callback,
void *  data 
)

Request V8 to interrupt long running JavaScript code and invoke the given |callback| passing the given |data| to it. After |callback| returns control will be returned to the JavaScript code. At any given moment V8 can remember only a single callback for the very last interrupt request. Can be called from another thread without acquiring a |Locker|. Registered |callback| must not reenter interrupted Isolate.

void v8::Isolate::RunMicrotasks ( )

Experimental: Runs the Microtask Work Queue until empty Any exceptions thrown by microtask callbacks are swallowed.

void v8::Isolate::SetAutorunMicrotasks ( bool  autorun)

Experimental: Controls whether the Microtask Work Queue is automatically run when the script call depth decrements to zero.

void v8::Isolate::SetCounterFunction ( CounterLookupCallback  )

Enables the host application to provide a mechanism for recording statistics counters.

void v8::Isolate::SetCreateHistogramFunction ( CreateHistogramCallback  )

Enables the host application to provide a mechanism for recording histograms. The CreateHistogram function returns a histogram which will later be passed to the AddHistogramSample function.

void v8::Isolate::SetData ( uint32_t  slot,
void *  data 
)

Associate embedder-specific data with the isolate. |slot| has to be between 0 and GetNumberOfDataSlots() - 1.

void v8::Isolate::SetEventLogger ( LogEventCallback  that)

Set the callback to invoke for logging event.

template<typename T >
void v8::Isolate::SetObjectGroupId ( const Persistent< T > &  object,
UniqueId  id 
)

Allows the host application to group objects together. If one object in the group is alive, all objects in the group are alive. After each garbage collection, object groups are removed. It is intended to be used in the before-garbage-collection callback function, for instance to simulate DOM tree connections among JS wrapper objects. Object groups for all dependent handles need to be provided for kGCTypeMarkSweepCompact collections, for all other garbage collection types it is sufficient to provide object groups for partially dependent handles only.

template<typename T , typename S >
void v8::Isolate::SetReference ( const Persistent< T > &  parent,
const Persistent< S > &  child 
)

Allows the host application to declare implicit references from an object to another object. If the parent object is alive, the child object is alive too. After each garbage collection, all implicit references are removed. It is intended to be used in the before-garbage-collection callback function.

template<typename T >
void v8::Isolate::SetReferenceFromGroup ( UniqueId  id,
const Persistent< T > &  child 
)

Allows the host application to declare implicit references from an object group to an object. If the objects of the object group are alive, the child object is alive too. After each garbage collection, all implicit references are removed. It is intended to be used in the before-garbage-collection callback function.

void v8::Isolate::SetUseCounterCallback ( UseCounterCallback  callback)

Sets a callback for counting the number of times a feature of V8 is used.

Local<Value> v8::Isolate::ThrowException ( Local< Value exception)

Schedules an exception to be thrown when returning to JavaScript. When an exception has been scheduled it is illegal to invoke any JavaScript operation; the caller must return immediately and only after the exception has been handled does it become legal to invoke JavaScript operations.

bool v8::Isolate::WillAutorunMicrotasks ( ) const

Experimental: Returns whether the Microtask Work Queue is automatically run when the script call depth decrements to zero.


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