#include <v8.h>

Static Public Member Functions
static void	SetFatalErrorHandler (FatalErrorCallback that)

static void	SetAllowCodeGenerationFromStringsCallback (AllowCodeGenerationFromStringsCallback that)

static void	IgnoreOutOfMemoryException ()

static bool	IsDead ()

static StartupData::CompressionAlgorithm	GetCompressedStartupDataAlgorithm ()

static int	GetCompressedStartupDataCount ()

static void	GetCompressedStartupData (StartupData *compressed_data)

static void	SetDecompressedStartupData (StartupData *decompressed_data)

static bool	AddMessageListener (MessageCallback that, Handle< Value > data=Handle< Value >())

static void	RemoveMessageListeners (MessageCallback that)

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

static void	SetFlagsFromString (const char *str, int length)

static void	SetFlagsFromCommandLine (int argc, char *argv, bool remove_flags)

static const char *	GetVersion ()

static void	SetCounterFunction (CounterLookupCallback)

static void	SetCreateHistogramFunction (CreateHistogramCallback)

static void	SetAddHistogramSampleFunction (AddHistogramSampleCallback)

static void	EnableSlidingStateWindow ()

static void	SetFailedAccessCheckCallbackFunction (FailedAccessCheckCallback)

static void	AddGCPrologueCallback (GCPrologueCallback callback, GCType gc_type_filter=kGCTypeAll)

static void	RemoveGCPrologueCallback (GCPrologueCallback callback)

static void	SetGlobalGCPrologueCallback (GCCallback)

static void	AddGCEpilogueCallback (GCEpilogueCallback callback, GCType gc_type_filter=kGCTypeAll)

static void	RemoveGCEpilogueCallback (GCEpilogueCallback callback)

static void	SetGlobalGCEpilogueCallback (GCCallback)

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

static void	RemoveMemoryAllocationCallback (MemoryAllocationCallback callback)

static void	AddCallCompletedCallback (CallCompletedCallback callback)

static void	RemoveCallCompletedCallback (CallCompletedCallback callback)

static void	AddObjectGroup (Persistent< Value > objects, size_t length, RetainedObjectInfo info=NULL)

static void	AddImplicitReferences (Persistent< Object > parent, Persistent< Value > *children, size_t length)

static bool	Initialize ()

static void	SetEntropySource (EntropySource source)

static void	SetReturnAddressLocationResolver (ReturnAddressLocationResolver return_address_resolver)

static intptr_t	AdjustAmountOfExternalAllocatedMemory (intptr_t change_in_bytes)

static void	PauseProfiler ()

static void	ResumeProfiler ()

static bool	IsProfilerPaused ()

static int	GetCurrentThreadId ()

static void	TerminateExecution (int thread_id)

static void	TerminateExecution (Isolate *isolate=NULL)

static bool	IsExecutionTerminating (Isolate *isolate=NULL)

static bool	Dispose ()

static void	GetHeapStatistics (HeapStatistics *heap_statistics)

static void	VisitExternalResources (ExternalResourceVisitor *visitor)

static bool	IdleNotification (int hint=1000)

static void	LowMemoryNotification ()

static int	ContextDisposedNotification ()

Friends
template<class T >
class	Handle

template<class T >
class	Local

template<class T >
class	Persistent

class	Context

Detailed Description

Container class for static utility functions.

Definition at line 2934 of file v8.h.

Member Function Documentation

void AddCallCompletedCallback ( CallCompletedCallback callback )

static

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.

Definition at line 5305 of file api.cc.

References V8::AddCallCompletedCallback(), Isolate::EnsureDefaultIsolate(), and NULL.

Referenced by TEST().

void AddGCEpilogueCallback	(	GCEpilogueCallback	callback,
		GCType	gc_type_filter = `kGCTypeAll`
	)

static

Enables the host application to receive a notification after a garbage collection. Allocations are not allowed in the callback function, you therefore cannot manipulate objects (set or delete properties for example) since it is possible such operations will result in the allocation of objects. 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.

Definition at line 5273 of file api.cc.

References Heap::AddGCEpilogueCallback(), and Isolate::heap().

Referenced by TEST().

void AddGCPrologueCallback	(	GCPrologueCallback	callback,
		GCType	gc_type_filter = `kGCTypeAll`
	)

static

Enables the host application to receive a notification before a garbage collection. Allocations are not allowed in the callback function, you therefore cannot manipulate objects (set or delete properties for example) since it is possible such operations will result in the allocation of objects. 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.

Definition at line 5259 of file api.cc.

References Heap::AddGCPrologueCallback(), and Isolate::heap().

Referenced by TEST().

void AddImplicitReferences	(	Persistent< Object >	parent,
		Persistent< Value > *	children,
		size_t	length
	)

static

Allows the host application to declare implicit references between the objects: if |parent| is alive, all |children| are 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 5223 of file api.cc.

References GlobalHandles::AddImplicitReferences(), Isolate::global_handles(), Utils::OpenHandle(), and STATIC_ASSERT.

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

static

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

Definition at line 5287 of file api.cc.

References MemoryAllocator::AddMemoryAllocationCallback(), and Isolate::memory_allocator().

bool AddMessageListener	(	MessageCallback	that,
		Handle< Value >	data = `Handle<Value>()`
	)

static

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.

Definition at line 5130 of file api.cc.

References ENTER_V8, Isolate::factory(), FUNCTION_ADDR, Isolate::heap(), Handle< T >::IsEmpty(), Factory::NewForeign(), ON_BAILOUT, and Utils::OpenHandle().

Referenced by TEST(), and THREADED_TEST().

void AddObjectGroup	(	Persistent< Value > *	objects,
		size_t	length,
		RetainedObjectInfo *	info = `NULL`
	)

static

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. See v8-profiler.h for RetainedObjectInfo interface description.

Definition at line 5212 of file api.cc.

References GlobalHandles::AddObjectGroup(), Isolate::global_handles(), and STATIC_ASSERT.

intptr_t AdjustAmountOfExternalAllocatedMemory ( intptr_t change_in_bytes )

static

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 otherwise in an attempt to garbage collect the JavaScript objects keeping the externally allocated memory alive.

Parameters

change_in_bytes the change in externally allocated memory that is kept alive by JavaScript objects.

Returns: the adjusted value.

Definition at line 5235 of file api.cc.

References Heap::AdjustAmountOfExternalAllocatedMemory(), and Isolate::heap().

Referenced by Shell::ReadBuffer(), and THREADED_TEST().

int ContextDisposedNotification ( )

static

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.

Definition at line 4284 of file api.cc.

References Isolate::heap(), Isolate::IsInitialized(), and Heap::NotifyContextDisposed().

Referenced by Shell::RunMain(), and TEST().

bool Dispose ( )

static

Releases any resources used by v8 and stops any utility threads that may be running. Note that disposing v8 is permanent, it cannot be reinitialized.

It should generally not be necessary to dispose v8 before exiting a process, this should happen automatically. It is only necessary to use if the process needs the resources taken up by v8.

Definition at line 4224 of file api.cc.

References Isolate::IsDefaultIsolate(), NULL, and V8::TearDown().

Referenced by Shell::Main(), and main().

void EnableSlidingStateWindow ( )

static

Enables the computation of a sliding window of states. The sliding window information is recorded in statistics counters.

Definition at line 5196 of file api.cc.

References Logger::EnableSlidingStateWindow(), and Isolate::logger().

void GetCompressedStartupData ( StartupData * compressed_data )

static

StartupData::CompressionAlgorithm GetCompressedStartupDataAlgorithm ( )

static

The following 4 functions are to be used when V8 is built with the 'compress_startup_data' flag enabled. In this case, the embedder must decompress startup data prior to initializing V8.

This is how interaction with V8 should look like: int compressed_data_count = v8::V8::GetCompressedStartupDataCount(); v8::StartupData* compressed_data = new v8::StartupData[compressed_data_count]; v8::V8::GetCompressedStartupData(compressed_data); ... decompress data (compressed_data can be updated in-place) ... v8::V8::SetDecompressedStartupData(compressed_data); ... now V8 can be initialized ... make sure the decompressed data stays valid until V8 shutdown

A helper class StartupDataDecompressor is provided. It implements the protocol of the interaction described above, and can be used in most cases instead of calling these API functions directly.

Definition at line 368 of file api.cc.

References StartupData::kBZip2, and StartupData::kUncompressed.

int GetCompressedStartupDataCount ( )

static

Definition at line 385 of file api.cc.

References v8::kCompressedStartupDataCount.

Referenced by StartupDataDecompressor::Decompress(), StartupDataDecompressor::StartupDataDecompressor(), and StartupDataDecompressor::~StartupDataDecompressor().

int GetCurrentThreadId ( )

static

Retrieve the V8 thread id of the calling thread.

The thread id for a thread should only be retrieved after the V8 lock has been acquired with a Locker object with that thread.

Definition at line 5340 of file api.cc.

References Isolate::thread_id(), and ThreadId::ToInteger().

Referenced by LoopingThread::Run().

void GetHeapStatistics ( HeapStatistics * heap_statistics )

static

Get statistics about the heap memory usage.

Definition at line 4242 of file api.cc.

References Heap::CommittedMemory(), Heap::CommittedMemoryExecutable(), Heap::MaxReserved(), and Heap::SizeOfObjects().

Referenced by THREADED_TEST().

const char * GetVersion ( )

static

Get the version string.

Definition at line 4291 of file api.cc.

References Version::GetVersion().

Referenced by RunShell(), v8::internal::RUNTIME_FUNCTION(), THREADED_TEST(), Version(), and Shell::Version().

bool IdleNotification ( int hint = 1000 )

static

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 hint argument specifies the amount of work to be done in the function on scale from 1 to 1000. There is no guarantee that the actual work will match the hint.

Definition at line 4268 of file api.cc.

References V8::IdleNotification(), Isolate::IsInitialized(), and NULL.

Referenced by Shell::RunMain(), and TEST().

void IgnoreOutOfMemoryException ( )

static

Ignore out-of-memory exceptions.

V8 running out of memory is treated as a fatal error by default. This means that the fatal error handler is called and that V8 is terminated.

IgnoreOutOfMemoryException can be used to not treat an out-of-memory situation as a fatal error. This way, the contexts that did not cause the out of memory problem might be able to continue execution.

Definition at line 5125 of file api.cc.

References Isolate::set_ignore_out_of_memory().

Referenced by InitDefaultIsolateThread::Run(), and TEST().

bool Initialize ( )

static

Initializes from snapshot if possible. Otherwise, attempts to initialize from scratch. This function is called implicitly if you use the API without calling it first.

Definition at line 4204 of file api.cc.

References Isolate::IsInitialized(), and NULL.

Referenced by Locker::Locker(), TEST(), and THREADED_TEST().

bool IsDead ( )

static

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

Definition at line 227 of file api.cc.

References V8::IsDead().

bool IsExecutionTerminating ( Isolate * isolate = NULL )

static

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.

Parameters

isolate The isolate in which to check.

Definition at line 5373 of file api.cc.

References NULL.

Referenced by DoLoop(), DoLoopNoCall(), Loop(), LoopGetProperty(), ReenterAfterTermination(), TerminatorThread::Run(), LoopingThread::Run(), TerminateCurrentThread(), TerminateOrReturnObject(), and TEST().

bool IsProfilerPaused ( )

static

Return whether profiler is currently paused.

Definition at line 5334 of file api.cc.

References Logger::IsProfilerPaused(), and Isolate::logger().

void LowMemoryNotification ( )

static

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

Definition at line 4277 of file api.cc.

References Heap::CollectAllAvailableGarbage(), Isolate::heap(), Isolate::IsInitialized(), and NULL.

void PauseProfiler ( )

static

Suspends recording of tick samples in the profiler. When the V8 profiling mode is enabled (usually via command line switches) this function suspends recording of tick samples. Profiling ticks are discarded until ResumeProfiler() is called.

See also the –prof and –prof_auto command line switches to enable V8 profiling.

Definition at line 5322 of file api.cc.

References Isolate::logger(), and Logger::PauseProfiler().

Referenced by Shell::DisableProfiler(), v8::internal::RUNTIME_FUNCTION(), and TEST().

void RemoveCallCompletedCallback ( CallCompletedCallback callback )

static

Removes callback that was installed by AddCallCompletedCallback.

Definition at line 5314 of file api.cc.

References Isolate::EnsureDefaultIsolate(), and V8::RemoveCallCompletedCallback().

Referenced by TEST().

void RemoveGCEpilogueCallback ( GCEpilogueCallback callback )

static

This function removes callback which was installed by AddGCEpilogueCallback function.

Definition at line 5280 of file api.cc.

References Isolate::heap(), and Heap::RemoveGCEpilogueCallback().

Referenced by TEST().

void RemoveGCPrologueCallback ( GCPrologueCallback callback )

static

This function removes callback which was installed by AddGCPrologueCallback function.

Definition at line 5266 of file api.cc.

References Isolate::heap(), and Heap::RemoveGCPrologueCallback().

Referenced by TEST().

void RemoveMemoryAllocationCallback ( MemoryAllocationCallback callback )

static

Removes callback that was installed by AddMemoryAllocationCallback.

Definition at line 5297 of file api.cc.

References Isolate::memory_allocator(), and MemoryAllocator::RemoveMemoryAllocationCallback().

void RemoveMessageListeners ( MessageCallback that )

static

Remove all message listeners from the specified callback function.

Definition at line 5147 of file api.cc.

References JSObject::cast(), Foreign::cast(), ENTER_V8, Isolate::factory(), FUNCTION_ADDR, NeanderObject::get(), Isolate::heap(), and ON_BAILOUT.

Referenced by TEST(), and THREADED_TEST().

void ResumeProfiler ( )

static

Resumes recording of tick samples in the profiler. See also PauseProfiler().

Definition at line 5328 of file api.cc.

References Isolate::logger(), and Logger::ResumeProfiler().

Referenced by Shell::EnableProfiler(), v8::internal::RUNTIME_FUNCTION(), and TEST().

void SetAddHistogramSampleFunction ( AddHistogramSampleCallback callback )

static

Definition at line 5189 of file api.cc.

References Isolate::stats_table().

Referenced by Shell::MapCounters(), and InitDefaultIsolateThread::Run().

void SetAllowCodeGenerationFromStringsCallback ( AllowCodeGenerationFromStringsCallback that )

static

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

Definition at line 460 of file api.cc.

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

static

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

Definition at line 5166 of file api.cc.

Referenced by TEST().

void SetCounterFunction ( CounterLookupCallback callback )

static

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

Definition at line 5177 of file api.cc.

References StatsTable::SetCounterFunction(), and Isolate::stats_table().

Referenced by Shell::MapCounters(), and InitDefaultIsolateThread::Run().

void SetCreateHistogramFunction ( CreateHistogramCallback callback )

static

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.

Definition at line 5183 of file api.cc.

References StatsTable::SetCreateHistogramFunction(), and Isolate::stats_table().

Referenced by Shell::MapCounters(), and InitDefaultIsolateThread::Run().

void SetDecompressedStartupData ( StartupData * decompressed_data )

static

Definition at line 425 of file api.cc.

References ASSERT_EQ, Snapshot::context_raw_size(), NativesCollection< type >::GetRawScriptsSize(), v8::kExperimentalLibraries, v8::kLibraries, v8::kSnapshot, v8::kSnapshotContext, Snapshot::raw_size(), Snapshot::set_context_raw_data(), Snapshot::set_raw_data(), and NativesCollection< type >::SetRawScriptsSource().

Referenced by StartupDataDecompressor::Decompress().

void SetEntropySource ( EntropySource source )

static

Allows the host application to provide a callback which can be used as a source of entropy for random number generators.

Definition at line 4213 of file api.cc.

References V8::SetEntropySource().

void SetFailedAccessCheckCallbackFunction ( FailedAccessCheckCallback callback )

static

Callback function for reporting failed access checks.

Definition at line 5203 of file api.cc.

References Isolate::SetFailedAccessCheckCallback().

Referenced by TEST().

void SetFatalErrorHandler ( FatalErrorCallback that )

static

Set the callback to invoke in case of fatal errors.

Definition at line 454 of file api.cc.

Referenced by InitDefaultIsolateThread::Run(), and TEST().

void SetFlagsFromCommandLine	(	int *	argc,
		char **	argv,
		bool	remove_flags
	)

static

Sets V8 flags from the command line.

Definition at line 480 of file api.cc.

Referenced by main(), and RunMain().

void SetFlagsFromString	(	const char *	str,
		int	length
	)

static

Sets V8 flags from a string.

Definition at line 475 of file api.cc.

void SetGlobalGCEpilogueCallback ( GCCallback callback )

static

The function is deprecated. Please use AddGCEpilogueCallback instead. Enables the host application to receive a notification after a major garbage collection. Allocations are not allowed in the callback function, you therefore cannot manipulate objects (set or delete properties for example) since it is possible such operations will result in the allocation of objects.

Definition at line 5252 of file api.cc.

References Isolate::heap(), and Heap::SetGlobalGCEpilogueCallback().

void SetGlobalGCPrologueCallback ( GCCallback callback )

static

The function is deprecated. Please use AddGCPrologueCallback instead. Enables the host application to receive a notification before a garbage collection. Allocations are not allowed in the callback function, you therefore cannot manipulate objects (set or delete properties for example) since it is possible such operations will result in the allocation of objects.

Definition at line 5245 of file api.cc.

References Isolate::heap(), and Heap::SetGlobalGCPrologueCallback().

Referenced by TEST().

void SetReturnAddressLocationResolver ( ReturnAddressLocationResolver return_address_resolver )

static

Allows the host application to provide a callback that allows v8 to cooperate with a profiler that rewrites return addresses on stack.

Definition at line 4218 of file api.cc.

References V8::SetReturnAddressLocationResolver().

void TerminateExecution ( int thread_id )

static

Forcefully terminate execution of a JavaScript thread. This can be used to terminate long-running scripts.

TerminateExecution should only be called when then V8 lock has been acquired with a Locker object. Therefore, in order to be able to terminate long-running threads, preemption must be enabled to allow the user of TerminateExecution to acquire the lock.

The termination is achieved by throwing an exception that is uncatchable by JavaScript exception handlers. Termination exceptions act as if they were caught by a C++ TryCatch exception handler. If forceful termination is used, any C++ TryCatch exception handler that catches an exception should check if that exception is a termination exception and immediately return if that is the case. Returning immediately in that case will continue the propagation of the termination exception if needed.

The thread id passed to TerminateExecution must have been obtained by calling GetCurrentThreadId on the thread in question.

Parameters

thread_id The thread id of the thread to terminate.

Definition at line 5347 of file api.cc.

References API_ENTRY_CHECK, ThreadId::FromInteger(), Isolate::IsInitialized(), Isolate::stack_guard(), ThreadManager::TerminateExecution(), StackGuard::TerminateExecution(), Isolate::thread_id(), and Isolate::thread_manager().

Referenced by TerminatorThread::Run(), TerminateCurrentThread(), TerminateOrReturnObject(), and TEST().

void TerminateExecution ( Isolate * isolate = NULL )

static

Forcefully terminate the current thread of JavaScript execution in the given isolate. If no isolate is provided, the default isolate is used.

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

Parameters

isolate The isolate in which to terminate the current JS execution.

Definition at line 5363 of file api.cc.

References Isolate::GetDefaultIsolateStackGuard(), NULL, StackGuard::TerminateExecution(), and Isolate::TerminateExecution().

void VisitExternalResources ( ExternalResourceVisitor * visitor )

static

Iterates through all external resources referenced from current isolate heap. This method is not expected to be used except for debugging purposes and may be quite slow.

Definition at line 4261 of file api.cc.

References Isolate::heap(), and Heap::VisitExternalResources().

Referenced by TEST().

Friends And Related Function Documentation

friend class Context

friend

Definition at line 3347 of file v8.h.

friend class Handle

friend

Definition at line 3344 of file v8.h.

friend class Local

friend

Definition at line 3345 of file v8.h.

friend class Persistent

friend

Definition at line 3346 of file v8.h.

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

include/v8.h
src/api.cc

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

Friends And Related Function Documentation