#include <v8-profiler.h>

Classes
class	ObjectNameResolver

struct	RetainerInfos

Public Types
enum	SamplingFlags { kSamplingNoFlags = 0, kSamplingForceGC = 1 << 0 }

typedef std::unordered_set< const v8::PersistentBase< v8::Value > * >	RetainerChildren

typedef std::vector< std::pair< v8::RetainedObjectInfo *, RetainerChildren > >	RetainerGroups

typedef std::vector< std::pair< const v8::PersistentBase< v8::Value > , const v8::PersistentBase< v8::Value > > >	RetainerEdges

typedef RetainerInfos(*	GetRetainerInfosCallback) (v8::Isolate *isolate)

typedef RetainedObjectInfo (	WrapperInfoCallback) (uint16_t class_id, Local< Value > wrapper)

typedef void(*	BuildEmbedderGraphCallback) (v8::Isolate isolate, v8::EmbedderGraph graph, void *data)

typedef void(*	LegacyBuildEmbedderGraphCallback) (v8::Isolate isolate, v8::EmbedderGraph graph)

Public Member Functions
int	GetSnapshotCount ()

const HeapSnapshot *	GetHeapSnapshot (int index)

SnapshotObjectId	GetObjectId (Local< Value > value)

Local< Value >	FindObjectById (SnapshotObjectId id)

void	ClearObjectIds ()

const HeapSnapshot *	TakeHeapSnapshot (ActivityControl control=nullptr, ObjectNameResolver global_object_name_resolver=nullptr)

void	StartTrackingHeapObjects (bool track_allocations=false)

SnapshotObjectId	GetHeapStats (OutputStream stream, int64_t timestamp_us=nullptr)

void	StopTrackingHeapObjects ()

bool	StartSamplingHeapProfiler (uint64_t sample_interval=512 *1024, int stack_depth=16, SamplingFlags flags=kSamplingNoFlags)

void	StopSamplingHeapProfiler ()

AllocationProfile *	GetAllocationProfile ()

void	DeleteAllHeapSnapshots ()

	V8_DEPRECATED ("Use AddBuildEmbedderGraphCallback to provide info about embedder nodes", void SetWrapperClassInfoProvider(uint16_t class_id, WrapperInfoCallback callback))

	V8_DEPRECATED ("Use AddBuildEmbedderGraphCallback to provide info about embedder nodes", void SetGetRetainerInfosCallback(GetRetainerInfosCallback callback))

	V8_DEPRECATED ("Use AddBuildEmbedderGraphCallback to provide info about embedder nodes", void SetBuildEmbedderGraphCallback(LegacyBuildEmbedderGraphCallback callback))

void	AddBuildEmbedderGraphCallback (BuildEmbedderGraphCallback callback, void *data)

void	RemoveBuildEmbedderGraphCallback (BuildEmbedderGraphCallback callback, void *data)

Static Public Attributes
static const SnapshotObjectId	kUnknownObjectId = 0

static const uint16_t	kPersistentHandleNoClassId = 0

Detailed Description

Interface for controlling heap profiling. Instance of the profiler can be retrieved using v8::Isolate::GetHeapProfiler.

Definition at line 742 of file v8-profiler.h.

Member Typedef Documentation

◆ BuildEmbedderGraphCallback

typedef void(* v8::HeapProfiler::BuildEmbedderGraphCallback) (v8::Isolate *isolate, v8::EmbedderGraph *graph, void *data)

Callback function invoked during heap snapshot generation to retrieve the embedder object graph. The callback should use graph->AddEdge(..) to add references between the objects. The callback must not trigger garbage collection in V8.

Definition at line 782 of file v8-profiler.h.

◆ GetRetainerInfosCallback

typedef RetainerInfos(* v8::HeapProfiler::GetRetainerInfosCallback) (v8::Isolate *isolate)

Callback function invoked to retrieve all RetainerInfos from the embedder.

Definition at line 765 of file v8-profiler.h.

◆ LegacyBuildEmbedderGraphCallback

typedef void(* v8::HeapProfiler::LegacyBuildEmbedderGraphCallback) (v8::Isolate *isolate, v8::EmbedderGraph *graph)

TODO(addaleax): Remove

Definition at line 787 of file v8-profiler.h.

◆ WrapperInfoCallback

typedef RetainedObjectInfo*(* v8::HeapProfiler::WrapperInfoCallback) (uint16_t class_id, Local< Value > wrapper)

Callback function invoked for obtaining RetainedObjectInfo for the given JavaScript wrapper object. It is prohibited to enter V8 while the callback is running: only getters on the handle and GetPointerFromInternalField on the objects are allowed.

Definition at line 773 of file v8-profiler.h.

Member Function Documentation

◆ ClearObjectIds()

void v8::HeapProfiler::ClearObjectIds ( )

Clears internal map from SnapshotObjectId to heap object. The new objects will not be added into it unless a heap snapshot is taken or heap object tracking is kicked off.

Definition at line 10407 of file api.cc.

◆ DeleteAllHeapSnapshots()

void v8::HeapProfiler::DeleteAllHeapSnapshots ( )

Deletes all snapshots taken. All previously returned pointers to snapshots and their contents become invalid after this call.

Definition at line 10454 of file api.cc.

◆ FindObjectById()

Local< Value > v8::HeapProfiler::FindObjectById ( SnapshotObjectId id )

Returns heap object with given SnapshotObjectId if the object is alive, otherwise empty handle is returned.

Definition at line 10399 of file api.cc.

◆ GetAllocationProfile()

AllocationProfile * v8::HeapProfiler::GetAllocationProfile ( )

Returns the sampled profile of allocations allocated (and still live) since StartSamplingHeapProfiler was called. The ownership of the pointer is transferred to the caller. Returns nullptr if sampling heap profiler is not active.

Definition at line 10450 of file api.cc.

◆ GetHeapSnapshot()

const HeapSnapshot * v8::HeapProfiler::GetHeapSnapshot ( int index )

Returns a snapshot by index.

Definition at line 10387 of file api.cc.

◆ GetHeapStats()

SnapshotObjectId v8::HeapProfiler::GetHeapStats	(	OutputStream *	stream,
		int64_t *	timestamp_us = `nullptr`
	)

Adds a new time interval entry to the aggregated statistics array. The time interval entry contains information on the current heap objects population size. The method also updates aggregated statistics and reports updates for all previous time intervals via the OutputStream object. Updates on each time interval are provided as a stream of the HeapStatsUpdate structure instances. If |timestamp_us| is supplied, timestamp of the new entry will be written into it. The return value of the function is the last seen heap object Id.

StartTrackingHeapObjects must be called before the first call to this method.

Definition at line 10431 of file api.cc.

◆ GetObjectId()

SnapshotObjectId v8::HeapProfiler::GetObjectId ( Local< Value > value )

Returns SnapshotObjectId for a heap object referenced by |value| if it has been seen by the heap profiler, kUnknownObjectId otherwise.

Definition at line 10393 of file api.cc.

◆ GetSnapshotCount()

int v8::HeapProfiler::GetSnapshotCount ( )

Returns the number of snapshots taken.

Definition at line 10382 of file api.cc.

◆ StartSamplingHeapProfiler()

bool v8::HeapProfiler::StartSamplingHeapProfiler	(	uint64_t	sample_interval = `512 * 1024`,
		int	stack_depth = `16`,
		SamplingFlags	flags = `kSamplingNoFlags`
	)

Starts gathering a sampling heap profile. A sampling heap profile is similar to tcmalloc's heap profiler and Go's mprof. It samples object allocations and builds an online 'sampling' heap profile. At any point in time, this profile is expected to be a representative sample of objects currently live in the system. Each sampled allocation includes the stack trace at the time of allocation, which makes this really useful for memory leak detection.

This mechanism is intended to be cheap enough that it can be used in production with minimal performance overhead.

Allocations are sampled using a randomized Poisson process. On average, one allocation will be sampled every |sample_interval| bytes allocated. The |stack_depth| parameter controls the maximum number of stack frames to be captured on each allocation.

NOTE: This is a proof-of-concept at this point. Right now we only sample newspace allocations. Support for paged space allocation (e.g. pre-tenured objects, large objects, code objects, etc.) and native allocations doesn't exist yet, but is anticipated in the future.

Objects allocated before the sampling is started will not be included in the profile.

Returns false if a sampling heap profiler is already running.

Definition at line 10437 of file api.cc.

◆ StartTrackingHeapObjects()

void v8::HeapProfiler::StartTrackingHeapObjects ( bool track_allocations = false )

Starts tracking of heap objects population statistics. After calling this method, all heap objects relocations done by the garbage collector are being registered.

|track_allocations| parameter controls whether stack trace of each allocation in the heap will be recorded and reported as part of HeapSnapshot.

Definition at line 10420 of file api.cc.

◆ StopSamplingHeapProfiler()

void v8::HeapProfiler::StopSamplingHeapProfiler ( )

Stops the sampling heap profile and discards the current profile.

Definition at line 10445 of file api.cc.

◆ StopTrackingHeapObjects()

void v8::HeapProfiler::StopTrackingHeapObjects ( )

Stops tracking of heap objects population statistics, cleans up all collected data. StartHeapObjectsTracking must be called again prior to calling GetHeapStats next time.

Definition at line 10426 of file api.cc.

◆ TakeHeapSnapshot()

const HeapSnapshot * v8::HeapProfiler::TakeHeapSnapshot	(	ActivityControl *	control = `nullptr`,
		ObjectNameResolver *	global_object_name_resolver = `nullptr`
	)

Takes a heap snapshot and returns it.

Definition at line 10412 of file api.cc.

◆ V8_DEPRECATED()

v8::HeapProfiler::V8_DEPRECATED	(	"Use AddBuildEmbedderGraphCallback to provide info about embedder nodes"	,
		void	SetWrapperClassInfoProvideruint16_t class_id, WrapperInfoCallback callback
	)

Binds a callback to embedder's class ID.

Member Data Documentation

◆ kPersistentHandleNoClassId

const uint16_t v8::HeapProfiler::kPersistentHandleNoClassId = 0

static

Default value of persistent handle class ID. Must not be used to define a class. Can be used to reset a class of a persistent handle.

Definition at line 952 of file v8-profiler.h.

◆ kUnknownObjectId

STATIC_CONST_MEMBER_DEFINITION const SnapshotObjectId v8::HeapProfiler::kUnknownObjectId = 0