v8  4.6.85(node5.12.0)
V8 is Google's open source JavaScript engine
Isolate Class Reference

#include <v8.h>

Data Structures

class  AllowJavascriptExecutionScope
 
struct  CreateParams
 
class  DisallowJavascriptExecutionScope
 
class  Scope
 
class  SuppressMicrotaskExecutionScope
 

Public Types

enum  GarbageCollectionType { kFullGarbageCollection, kMinorGarbageCollection }
 
enum  UseCounterFeature {
  kUseAsm = 0, kBreakIterator = 1, kLegacyConst = 2, kMarkDequeOverflow = 3,
  kStoreBufferOverflow = 4, kSlotsBufferOverflow = 5, kObjectObserve = 6, kForcedGC = 7,
  kUseCounterFeatureCount
}
 
typedef void(* UseCounterCallback) (Isolate *isolate, UseCounterFeature feature)
 
typedef void(* GCCallback) (Isolate *isolate, GCType type, GCCallbackFlags flags)
 

Public Member Functions

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)
 
size_t NumberOfHeapSpaces ()
 
bool GetHeapSpaceStatistics (HeapSpaceStatistics *space_statistics, size_t index)
 
size_t NumberOfTrackedHeapObjectTypes ()
 
bool GetHeapObjectStatisticsAtLastGC (HeapObjectStatistics *object_statistics, size_t type_index)
 
void GetStackSample (const RegisterState &state, void **frames, size_t frames_limit, SampleInfo *sample_info)
 
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)
 
 V8_DEPRECATE_SOON ("Use GCCallBack instead", typedef void(*GCPrologueCallback)(Isolate *isolate, GCType type, GCCallbackFlags flags))
 
 V8_DEPRECATE_SOON ("Use GCCallBack instead", typedef void(*GCEpilogueCallback)(Isolate *isolate, GCType type, GCCallbackFlags flags))
 
void AddGCPrologueCallback (GCCallback callback, GCType gc_type_filter=kGCTypeAll)
 
void RemoveGCPrologueCallback (GCCallback callback)
 
void AddGCEpilogueCallback (GCCallback callback, GCType gc_type_filter=kGCTypeAll)
 
void RemoveGCEpilogueCallback (GCCallback callback)
 
void TerminateExecution ()
 
bool IsExecutionTerminating ()
 
void CancelTerminateExecution ()
 
void RequestInterrupt (InterruptCallback callback, void *data)
 
void RequestGarbageCollectionForTesting (GarbageCollectionType type)
 
void SetEventLogger (LogEventCallback that)
 
void AddCallCompletedCallback (CallCompletedCallback callback)
 
void RemoveCallCompletedCallback (CallCompletedCallback callback)
 
void SetPromiseRejectCallback (PromiseRejectCallback callback)
 
void RunMicrotasks ()
 
void EnqueueMicrotask (Local< 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 IdleNotificationDeadline (double deadline_in_seconds)
 
 V8_DEPRECATE_SOON ("use IdleNotificationDeadline()", bool IdleNotification(int idle_time_in_ms))
 
void LowMemoryNotification ()
 
int ContextDisposedNotification (bool dependant_context=true)
 
void SetJitCodeEventHandler (JitCodeEventOptions options, JitCodeEventHandler event_handler)
 
void SetStackLimit (uintptr_t stack_limit)
 
void GetCodeRange (void **start, size_t *length_in_bytes)
 
void SetFatalErrorHandler (FatalErrorCallback that)
 
void SetAllowCodeGenerationFromStringsCallback (AllowCodeGenerationFromStringsCallback callback)
 
bool IsDead ()
 
bool AddMessageListener (MessageCallback that, Local< Value > data=Local< Value >())
 
void RemoveMessageListeners (MessageCallback that)
 
void SetFailedAccessCheckCallbackFunction (FailedAccessCheckCallback)
 
void SetCaptureStackTraceForUncaughtExceptions (bool capture, int frame_limit=10, StackTrace::StackTraceOptions options=StackTrace::kOverview)
 
void AddMemoryAllocationCallback (MemoryAllocationCallback callback, ObjectSpace space, AllocationAction action)
 
void RemoveMemoryAllocationCallback (MemoryAllocationCallback callback)
 
void VisitExternalResources (ExternalResourceVisitor *visitor)
 
void VisitHandlesWithClassIds (PersistentHandleVisitor *visitor)
 
void VisitHandlesForPartialDependence (PersistentHandleVisitor *visitor)
 

Static Public Member Functions

static IsolateNew (const CreateParams &params)
 
static IsolateGetCurrent ()
 
static V8_INLINE uint32_t GetNumberOfDataSlots ()
 

Friends

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

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. The embedder can create multiple 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.

Definition at line 5182 of file v8.h.

Member Typedef Documentation

typedef void(* GCCallback) (Isolate *isolate, GCType type, GCCallbackFlags flags)

Definition at line 5566 of file v8.h.

typedef void(* UseCounterCallback) (Isolate *isolate, UseCounterFeature feature)

Definition at line 5350 of file v8.h.

Member Enumeration Documentation

Types of garbage collections that can be requested via RequestGarbageCollectionForTesting.

Enumerator
kFullGarbageCollection 
kMinorGarbageCollection 

Definition at line 5328 of file v8.h.

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

Enumerator
kUseAsm 
kBreakIterator 
kLegacyConst 
kMarkDequeOverflow 
kStoreBufferOverflow 
kSlotsBufferOverflow 
kObjectObserve 
kForcedGC 
kUseCounterFeatureCount 

Definition at line 5338 of file v8.h.

Member Function Documentation

void 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 AddGCEpilogueCallback ( GCCallback  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 AddGCPrologueCallback ( GCCallback  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.

void AddMemoryAllocationCallback ( MemoryAllocationCallback  callback,
ObjectSpace  space,
AllocationAction  action 
)

Enables the host application to provide a mechanism to be notified and perform custom logging when V8 Allocates Executable Memory.

bool AddMessageListener ( MessageCallback  that,
Local< Value data = LocalValue >() 
)

Adds a message listener.

The same message listener can be added more than once and in that case it will be called more than once for each message.

If data is specified, it will be passed to the callback when it is called. Otherwise, the exception object will be passed to the callback instead.

int64_t 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.

Definition at line 8152 of file v8.h.

References Internals::kAmountOfExternalAllocatedMemoryAtLastGlobalGCOffset, Internals::kAmountOfExternalAllocatedMemoryOffset, and Internals::kExternalAllocationLimit.

void CancelTerminateExecution ( )

Resume execution capability in the given isolate, whose execution was previously forcefully terminated using TerminateExecution().

When execution is forcefully terminated using TerminateExecution(), the isolate can not resume execution until all JavaScript frames have propagated the uncatchable exception which is generated. This method allows the program embedding the engine to handle the termination event and resume execution capability, even if JavaScript frames remain on the stack.

This method can be used by any thread even if that thread has not acquired the V8 lock with a Locker object.

int ContextDisposedNotification ( bool  dependant_context = true)

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.

The optional parameter |dependant_context| specifies whether the disposed context was depending on state from other contexts or not.

void Dispose ( )

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

void EnqueueMicrotask ( Local< Function microtask)

Experimental: Enqueues the callback to the Microtask Work Queue

void EnqueueMicrotask ( MicrotaskCallback  microtask,
void *  data = NULL 
)

Experimental: Enqueues the callback to the Microtask Work Queue

void 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.

Referenced by Isolate::Scope::Scope().

void 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().

Referenced by Isolate::Scope::~Scope().

Local<Context> 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.

void GetCodeRange ( void **  start,
size_t *  length_in_bytes 
)

Returns a memory range that can potentially contain jitted code.

On Win64, embedders are advised to install function table callbacks for these ranges, as default SEH won't be able to unwind through jitted code.

The first page of the code range is reserved for the embedder and is committed, writable, and executable.

Might be empty on other platforms.

https://code.google.com/p/v8/issues/detail?id=3598

CpuProfiler* 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* GetCurrent ( )
static

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

This method must not be invoked before V8::Initialize() was invoked.

Referenced by Value::ToDetailString(), and Value::ToObject().

Local<Context> GetCurrentContext ( )

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

Referenced by Value::ToDetailString(), and Value::ToObject().

void * GetData ( uint32_t  slot)

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

Definition at line 8140 of file v8.h.

References Internals::GetEmbedderData().

Local<Context> GetEnteredContext ( )

Returns the last entered context.

bool GetHeapObjectStatisticsAtLastGC ( HeapObjectStatistics object_statistics,
size_t  type_index 
)

Get statistics about objects in the heap.

Parameters
object_statisticsThe HeapObjectStatistics object to fill in statistics of objects of given type, which were live in the previous GC.
type_indexThe index of the type of object to fill details about, which ranges from 0 to NumberOfTrackedHeapObjectTypes() - 1.
Returns
true on success.
HeapProfiler* GetHeapProfiler ( )

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

bool GetHeapSpaceStatistics ( HeapSpaceStatistics space_statistics,
size_t  index 
)

Get the memory usage of a space in the heap.

Parameters
space_statisticsThe HeapSpaceStatistics object to fill in statistics.
indexThe index of the space to get statistics from, which ranges from 0 to NumberOfHeapSpaces() - 1.
Returns
true on success.
void GetHeapStatistics ( HeapStatistics heap_statistics)

Get statistics about the heap memory usage.

uint32_t GetNumberOfDataSlots ( )
static

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

Definition at line 8146 of file v8.h.

References Internals::kNumIsolateDataSlots.

void GetStackSample ( const RegisterState state,
void **  frames,
size_t  frames_limit,
SampleInfo sample_info 
)

Get a call stack sample from the isolate.

Parameters
stateExecution state.
framesCaller allocated buffer to store stack frames.
frames_limitMaximum number of frames to capture. The buffer must be large enough to hold the number of frames.
sample_infoThe sample info is filled up by the function provides number of actual captured stack frames and the current VM state.
Note
GetStackSample should only be called when the JS thread is paused or interrupted. Otherwise the behavior is undefined.
bool IdleNotificationDeadline ( double  deadline_in_seconds)

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

The deadline_in_seconds argument specifies the deadline V8 has to finish garbage collection work. deadline_in_seconds is compared with MonotonicallyIncreasingTime() and should be based on the same timebase as that function. There is no guarantee that the actual work will be done within the time limit.

bool InContext ( )

Returns true if this isolate has a current context.

bool IsDead ( )

Check if V8 is dead and therefore unusable. This is the case after fatal errors such as out-of-memory situations.

bool IsExecutionTerminating ( )

Is V8 terminating JavaScript execution.

Returns true if JavaScript execution is currently terminating because of a call to TerminateExecution. In that case there are still JavaScript frames on the stack and the termination exception is still active.

void LowMemoryNotification ( )

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

static Isolate* New ( const CreateParams params)
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.

V8::Initialize() must have run prior to this.

size_t NumberOfHeapSpaces ( )

Returns the number of spaces in the heap.

size_t NumberOfTrackedHeapObjectTypes ( )

Returns the number of types of objects tracked in the heap at GC.

void RemoveCallCompletedCallback ( CallCompletedCallback  callback)

Removes callback that was installed by AddCallCompletedCallback.

void RemoveGCEpilogueCallback ( GCCallback  callback)

This function removes callback which was installed by AddGCEpilogueCallback function.

void RemoveGCPrologueCallback ( GCCallback  callback)

This function removes callback which was installed by AddGCPrologueCallback function.

void RemoveMemoryAllocationCallback ( MemoryAllocationCallback  callback)

Removes callback that was installed by AddMemoryAllocationCallback.

void RemoveMessageListeners ( MessageCallback  that)

Remove all message listeners from the specified callback function.

void 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 IdleNotificationDeadline() or LowMemoryNotification() instead to influence the garbage collection schedule.

void 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. There may be a number of interrupt requests in flight. Can be called from another thread without acquiring a |Locker|. Registered |callback| must not reenter interrupted Isolate.

void RunMicrotasks ( )

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

void SetAddHistogramSampleFunction ( AddHistogramSampleCallback  )
void SetAllowCodeGenerationFromStringsCallback ( AllowCodeGenerationFromStringsCallback  callback)

Set the callback to invoke to check if code generation from strings should be allowed.

void SetAutorunMicrotasks ( bool  autorun)

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

void SetCaptureStackTraceForUncaughtExceptions ( bool  capture,
int  frame_limit = 10,
StackTrace::StackTraceOptions  options = StackTrace::kOverview 
)

Tells V8 to capture current stack trace when uncaught exception occurs and report it to the message listeners. The option is off by default.

void SetCounterFunction ( CounterLookupCallback  )

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

void 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 SetData ( uint32_t  slot,
void *  data 
)

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

Definition at line 8134 of file v8.h.

References Internals::SetEmbedderData().

void SetEventLogger ( LogEventCallback  that)

Set the callback to invoke for logging event.

void SetFailedAccessCheckCallbackFunction ( FailedAccessCheckCallback  )

Callback function for reporting failed access checks.

void SetFatalErrorHandler ( FatalErrorCallback  that)

Set the callback to invoke in case of fatal errors.

void SetJitCodeEventHandler ( JitCodeEventOptions  options,
JitCodeEventHandler  event_handler 
)

Allows the host application to provide the address of a function that is notified each time code is added, moved or removed.

Parameters
optionsoptions for the JIT code event handler.
event_handlerthe JIT code event handler, which will be invoked each time code is added, moved or removed.
Note
event_handler won't get notified of existent code.
since code removal notifications are not currently issued, the event_handler may get notifications of code that overlaps earlier code notifications. This happens when code areas are reused, and the earlier overlapping code areas should therefore be discarded.
the events passed to event_handler and the strings they point to are not guaranteed to live past each call. The event_handler must copy strings and other parameters it needs to keep around.
the set of events declared in JitCodeEvent::EventType is expected to grow over time, and the JitCodeEvent structure is expected to accrue new members. The event_handler function must ignore event codes it does not recognize to maintain future compatibility.
Use Isolate::CreateParams to get events for code executed during Isolate setup.
void 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.

Definition at line 8174 of file v8.h.

void SetPromiseRejectCallback ( PromiseRejectCallback  callback)

Set callback to notify about promise reject with no handler, or revocation of such a previous notification once the handler is added.

void 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.

Definition at line 8191 of file v8.h.

void 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.

Definition at line 8182 of file v8.h.

void SetStackLimit ( uintptr_t  stack_limit)

Modifies the stack limit for this Isolate.

Parameters
stack_limitAn address beyond which the Vm's stack may not grow.
Note
If you are using threads then you should hold the V8::Locker lock while setting the stack limit and you must set a non-default stack limit separately for each thread.
void SetUseCounterCallback ( UseCounterCallback  callback)

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

void TerminateExecution ( )

Forcefully terminate the current thread of JavaScript execution in the given isolate.

This method can be used by any thread even if that thread has not acquired the V8 lock with a Locker object.

Local<Value> 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.

V8_DEPRECATE_SOON ( "Use GCCallBack instead"  ,
typedef void(*)(Isolate *isolate, GCType type, GCCallbackFlags flags)  GCPrologueCallback 
)
V8_DEPRECATE_SOON ( "Use GCCallBack instead"  ,
typedef void(*)(Isolate *isolate, GCType type, GCCallbackFlags flags)  GCEpilogueCallback 
)
V8_DEPRECATE_SOON ( "use IdleNotificationDeadline()"  ,
bool   IdleNotificationint idle_time_in_ms 
)
void VisitExternalResources ( ExternalResourceVisitor visitor)

Iterates through all external resources referenced from current isolate heap. GC is not invoked prior to iterating, therefore there is no guarantee that visited objects are still alive.

void VisitHandlesForPartialDependence ( PersistentHandleVisitor visitor)

Iterates through all the persistent handles in the current isolate's heap that have class_ids and are candidates to be marked as partially dependent handles. This will visit handles to young objects created since the last garbage collection but is free to visit an arbitrary superset of these objects.

void VisitHandlesWithClassIds ( PersistentHandleVisitor visitor)

Iterates through all the persistent handles in the current isolate's heap that have class_ids.

bool WillAutorunMicrotasks ( ) const

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

Friends And Related Function Documentation

friend class PersistentValueMapBase
friend

Definition at line 5903 of file v8.h.


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