Heap Introspection

Walk areas and blocks of the heap at runtime. More...

Data Structures
struct	mi_heap_area_t
	An area of heap space contains blocks of a single size. More...

Typedefs
typedef bool	mi_block_visit_fun(const mi_heap_t *heap, const mi_heap_area_t *area, void *block, size_t block_size, void *arg)
	Visitor function passed to mi_heap_visit_blocks().

Functions
bool	mi_heap_visit_blocks (const mi_heap_t *heap, bool visit_blocks, mi_block_visit_fun *visitor, void *arg)
	Visit all areas and blocks in a heap.
bool	mi_heap_visit_abandoned_blocks (mi_heap_t *heap, bool visit_blocks, mi_block_visit_fun *visitor, void *arg)
	v3: Visit only abandoned pages of heap, optionally visiting their allocated blocks.
bool	mi_unsafe_heap_page_is_under_utilized (mi_heap_t *heap, void *p, size_t perc_threshold)
	v3, experimental: Test whether an eligible page containing p is at most perc_threshold percent utilized.
bool	mi_abandoned_visit_blocks (mi_subproc_id_t subproc_id, int heap_tag, bool visit_blocks, mi_block_visit_fun *visitor, void *arg)
	v1,v2: Visit all areas and blocks in abandoned heaps.

Detailed Description

Walk areas and blocks of the heap at runtime.

---

Data Structure Documentation

mi_heap_area_t

struct mi_heap_area_t

An area of heap space contains blocks of a single size.

The bytes in freed blocks are committed - used.

Data Fields
size_t	block_size	size in bytes of one block
void *	blocks	start of the area containing heap blocks
size_t	committed	current committed bytes of this area
size_t	full_block_size	size in bytes of a full block including padding and metadata.
int	heap_tag	heap tag associated with this area (see mi_heap_new_ex)
size_t	reserved	bytes reserved for this area
size_t	used	bytes in use by allocated blocks

Typedef Documentation

mi_block_visit_fun

typedef bool mi_block_visit_fun(const mi_heap_t *heap, const mi_heap_area_t *area, void *block, size_t block_size, void *arg)

Visitor function passed to mi_heap_visit_blocks().

Returns

true if ok, false to stop visiting (i.e. break)

This function is always first called for every area with block as a NULL pointer. If visit_all_blocks was true, the function is then called for every allocated block in that area.

Function Documentation

mi_abandoned_visit_blocks()

bool mi_abandoned_visit_blocks	(	mi_subproc_id_t	subproc_id,
		int	heap_tag,
		bool	visit_blocks,
		mi_block_visit_fun *	visitor,
		void *	arg )

v1,v2: Visit all areas and blocks in abandoned heaps.

Parameters

subproc_id	The sub-process id associated with the abandoned heaps.
heap_tag	Visit only abandoned memory with the specified heap tag, use -1 to visit all abandoned memory.
visit_blocks	If true visits all allocated blocks, otherwise visitor is only called for every heap area.
visitor	This function is called for every area in the heap (with block as NULL). If visit_all_blocks is true, visitor is also called for every allocated block in every area (with block!=NULL). return false from this function to stop visiting early.
arg	extra argument passed to the visitor.

Returns

true if all areas and blocks were visited.

Note: requires the option mi_option_visit_abandoned() to be set at the start of the program.

mi_heap_visit_abandoned_blocks()

bool mi_heap_visit_abandoned_blocks	(	mi_heap_t *	heap,
		bool	visit_blocks,
		mi_block_visit_fun *	visitor,
		void *	arg )

v3: Visit only abandoned pages of heap, optionally visiting their allocated blocks.

The callback rules and synchronization requirements are the same as mi_heap_visit_blocks().

Returns

true if the visit completed, or false if the visitor stopped it or the arguments were invalid.

mi_heap_visit_blocks()

bool mi_heap_visit_blocks	(	const mi_heap_t *	heap,
		bool	visit_blocks,
		mi_block_visit_fun *	visitor,
		void *	arg )

Visit all areas and blocks in a heap.

Parameters

heap	The heap to visit.
visit_blocks	If true visits all allocated blocks, otherwise visitor is only called for every heap area.
visitor	This function is called for every area in the heap (with block as NULL). If visit_all_blocks is true, visitor is also called for every allocated block in every area (with block!=NULL). return false from this function to stop visiting early.
arg	Extra argument passed to visitor.

Returns

true if all areas and blocks were visited.

Visits all areas and blocks in the heap. Other threads must not access this heap during the visit: they may not allocate in it, nor free blocks that belong to it (but thread termination is synchronized internally). The visitor runs under the heap's lock and must not re-enter the heap (through allocating or free-ing).

mi_unsafe_heap_page_is_under_utilized()

bool mi_unsafe_heap_page_is_under_utilized	(	mi_heap_t *	heap,
		void *	p,
		size_t	perc_threshold )

v3, experimental: Test whether an eligible page containing p is at most perc_threshold percent utilized.

heap may be NULL to match any heap. Full, partially extended, and active allocation pages are excluded. Only the calling thread may access the page during this call.