#include <v8.h>

Static Public Member Functions
static void	SetFatalErrorHandler (FatalErrorCallback that)

static void	SetAllowCodeGenerationFromStringsCallback (AllowCodeGenerationFromStringsCallback that)

static void	SetArrayBufferAllocator (ArrayBuffer::Allocator *allocator)

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	SetFailedAccessCheckCallbackFunction (FailedAccessCheckCallback)

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

static void	RemoveGCPrologueCallback (GCPrologueCallback callback)

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

static void	RemoveGCEpilogueCallback (GCEpilogueCallback callback)

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	RunMicrotasks (Isolate *isolate)

static void	EnqueueMicrotask (Isolate *isolate, Handle< Function > microtask)

static void	SetAutorunMicrotasks (Isolate *source, bool autorun)

static bool	Initialize ()

static void	SetEntropySource (EntropySource source)

static void	SetReturnAddressLocationResolver (ReturnAddressLocationResolver return_address_resolver)

static bool	SetFunctionEntryHook (Isolate *isolate, FunctionEntryHook entry_hook)

static void	SetJitCodeEventHandler (JitCodeEventOptions options, JitCodeEventHandler event_handler)

static void	TerminateExecution (Isolate *isolate=NULL)

static bool	IsExecutionTerminating (Isolate *isolate=NULL)

static void	CancelTerminateExecution (Isolate *isolate)

static bool	Dispose ()

static void	VisitExternalResources (ExternalResourceVisitor *visitor)

static void	VisitHandlesWithClassIds (PersistentHandleVisitor *visitor)

static void	VisitHandlesForPartialDependence (Isolate isolate, PersistentHandleVisitor visitor)

static bool	IdleNotification (int hint=1000)

static void	LowMemoryNotification ()

static int	ContextDisposedNotification ()

static bool	InitializeICU (const char *icu_data_file=NULL)

static void	InitializePlatform (Platform *platform)

static void	ShutdownPlatform ()

Friends
template<class T >
class	Handle

template<class T >
class	Local

template<class T >
class	Eternal

template<class T >
class	PersistentBase

template<class T , class M >
class	Persistent

class	Context

Detailed Description

Container class for static utility functions.

Definition at line 4622 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 6501 of file api.cc.

References V8::AddCallCompletedCallback(), 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 6469 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 6453 of file api.cc.

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

Referenced by TEST().

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

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.

Definition at line 6259 of file api.cc.

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

Referenced by TEST(), and THREADED_TEST().

void CancelTerminateExecution ( Isolate * isolate )

static

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.

Parameters

isolate The isolate in which to resume execution capability.

Definition at line 6548 of file api.cc.

References StackGuard::CancelTerminateExecution(), and Isolate::stack_guard().

Referenced by DoLoopCancelTerminate().

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 5108 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 5028 of file api.cc.

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

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

void EnqueueMicrotask	(	Isolate *	isolate,
		Handle< Function >	microtask
	)

static

Experimental: Enqueues the callback to the Microtask Work Queue

Definition at line 6514 of file api.cc.

References Execution::EnqueueMicrotask(), ENTER_V8, and Utils::OpenHandle().

Referenced by TEST().

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 306 of file api.cc.

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

int GetCompressedStartupDataCount ( )

static

Definition at line 324 of file api.cc.

References v8::kCompressedStartupDataCount.

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

const char * GetVersion ( )

static

Get the version string.

Definition at line 5120 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 5091 of file api.cc.

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

Referenced by Shell::RunMain(), 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 4967 of file api.cc.

References Isolate::IsInitialized(), and NULL.

Referenced by DescriptorTestHelper::DescriptorTestHelper(), TEST(), TestViewFromApi(), and THREADED_TEST().

bool InitializeICU ( const char * icu_data_file = NULL )

static

Initialize the ICU library bundled with V8. The embedder should only invoke this method when using the bundled ICU. Returns true on success.

If V8 was compiled with the ICU data in an external file, the location of the data file has to be provided.

Definition at line 5115 of file api.cc.

References v8::internal::InitializeICU().

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

void InitializePlatform ( Platform * platform )

static

Sets the v8::Platform to use. This should be invoked before V8 is initialized.

Definition at line 4949 of file api.cc.

References FATAL, and V8::InitializePlatform().

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 208 of file api.cc.

References Isolate::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 6541 of file api.cc.

References NULL.

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

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 5101 of file api.cc.

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

void RemoveCallCompletedCallback ( CallCompletedCallback callback )

static

Removes callback that was installed by AddCallCompletedCallback.

Definition at line 6526 of file api.cc.

References V8::RemoveCallCompletedCallback().

Referenced by TEST().

void RemoveGCEpilogueCallback ( GCEpilogueCallback callback )

static

This function removes callback which was installed by AddGCEpilogueCallback function.

Definition at line 6478 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 6462 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 6494 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 6275 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 RunMicrotasks ( Isolate * isolate )

static

Experimental: Runs the Microtask Work Queue until empty

Definition at line 6507 of file api.cc.

References V8::RunMicrotasks().

Referenced by TEST().

void SetAddHistogramSampleFunction ( AddHistogramSampleCallback callback )

static

Definition at line 6319 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 399 of file api.cc.

void SetArrayBufferAllocator ( ArrayBuffer::Allocator * allocator )

static

Set allocator to use for ArrayBuffer memory. The allocator should be set only once. The allocator should be set before any code tha uses ArrayBuffers is executed. This allocator is used in all isolates.

Definition at line 5018 of file api.cc.

References Utils::ApiCheck(), V8::ArrayBufferAllocator(), NULL, and V8::SetArrayBufferAllocator().

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

void SetAutorunMicrotasks	(	Isolate *	source,
		bool	autorun
	)

static

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

Definition at line 6521 of file api.cc.

Referenced by TEST().

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 6294 of file api.cc.

Referenced by main(), and TEST().

void SetCounterFunction ( CounterLookupCallback callback )

static

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

Definition at line 6305 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 6311 of file api.cc.

References Isolate::counters(), Isolate::InitializeLoggingAndCounters(), Counters::ResetHistograms(), StatsTable::SetCreateHistogramFunction(), and Isolate::stats_table().

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

void SetDecompressedStartupData ( StartupData * decompressed_data )

static

Definition at line 364 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 4976 of file api.cc.

void SetFailedAccessCheckCallbackFunction ( FailedAccessCheckCallback callback )

static

Callback function for reporting failed access checks.

Definition at line 6325 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 393 of file api.cc.

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

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

static

Sets V8 flags from the command line.

Definition at line 411 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 406 of file api.cc.

bool SetFunctionEntryHook	(	Isolate *	isolate,
		FunctionEntryHook	entry_hook
	)

static

Allows the host application to provide the address of a function that's invoked on entry to every V8-generated function. Note that entry_hook is invoked at the very start of each generated function.

Parameters

isolate	the isolate to operate on.
entry_hook	a function that will be invoked on entry to every V8-generated function.

Returns: true on success on supported platforms, false on failure.

Note: Setting an entry hook can only be done very early in an isolates lifetime, and once set, the entry hook cannot be revoked.

Definition at line 4987 of file api.cc.

References ASSERT, Isolate::function_entry_hook(), Isolate::IsInitialized(), NULL, and Isolate::set_function_entry_hook().

Referenced by SetFunctionEntryHookTest::RunTest().

void SetJitCodeEventHandler	(	JitCodeEventOptions	options,
		JitCodeEventHandler	event_handler
	)

static

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

Parameters

options	options for the JIT code event handler.
event_handler	the 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.

Definition at line 5010 of file api.cc.

References Isolate::InitializeLoggingAndCounters(), Isolate::logger(), and Logger::SetCodeEventHandler().

Referenced by SetFunctionEntryHookTest::RunTest().

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 4981 of file api.cc.

References V8::SetReturnAddressLocationResolver().

void ShutdownPlatform ( )

static

Clears all references to the v8::Platform. This should be invoked after V8 was disposed.

Definition at line 4958 of file api.cc.

References FATAL, and V8::ShutdownPlatform().

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 6531 of file api.cc.

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

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

void VisitExternalResources ( ExternalResourceVisitor * visitor )

static

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.

Definition at line 5047 of file api.cc.

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

Referenced by TEST().

void VisitHandlesForPartialDependence	(	Isolate *	isolate,
		PersistentHandleVisitor *	visitor
	)

static

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.

Definition at line 5079 of file api.cc.

References ASSERT, Isolate::global_handles(), and GlobalHandles::IterateAllRootsInNewSpaceWithClassIds().

Referenced by TEST().

void VisitHandlesWithClassIds ( PersistentHandleVisitor * visitor )

static

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

Definition at line 5070 of file api.cc.

References Isolate::global_handles(), and GlobalHandles::IterateAllRootsWithClassIds().

Referenced by TEST().

Friends And Related Function Documentation

friend class Context

friend

Definition at line 5018 of file v8.h.

friend class Eternal

friend

Definition at line 5015 of file v8.h.

friend class Handle

friend

Definition at line 5013 of file v8.h.

friend class Local

friend

Definition at line 5014 of file v8.h.

friend class Persistent

friend

Definition at line 5017 of file v8.h.

friend class PersistentBase

friend

Definition at line 5016 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