Heaps

First-class heaps. More...

Typedefs
typedef struct mi_heap_s	mi_heap_t
	Type of first-class heaps.

Functions
mi_heap_t *	mi_heap_new ()
	Create a new heap that can be used for allocation.
void	mi_heap_delete (mi_heap_t *heap)
	Delete a heap, releasing its internal resources but keeping live blocks intact.
void	mi_thread_heap_release (mi_heap_t *heap)
	Release a heap in the calling thread – promises to not allocate in that heap anymore.
void	mi_heap_destroy (mi_heap_t *heap)
	Destroy a heap, freeing all its still allocated blocks.
mi_heap_t *	mi_heap_set_default (mi_heap_t *heap)
	v1,v2: Set the default heap to use in the current thread for mi_malloc() et al.
mi_heap_t *	mi_heap_get_default ()
	v1,v2: Get the default heap that is used for mi_malloc() et al.
mi_heap_t *	mi_heap_get_backing ()
	v1,v2: Get the backing heap.
void	mi_heap_set_numa_affinity (mi_heap_t *heap, int numa_node)
	v3: set NUMA affinity for a heap.
void	mi_heap_set_debug_fill_preserve (mi_heap_t *heap, size_t preserve)
	v3: Exclude the first preserve bytes of each block from debug filling on allocation and free.
mi_heap_t *	mi_heap_main (void)
	v3: the main heap (of the current sub-process)
mi_heap_t *	mi_heap_of (const void *p)
	v3: return the heap that contains the given pointer.
bool	mi_heap_contains (const mi_heap_t *heap, const void *p)
	v3: does a heap contain a specific pointer?
bool	mi_any_heap_contains (const void *p)
	v3: is a pointer pointing into mimalloc managed memory?
bool	mi_is_in_heap_region (const void *p)
	v1,v2: Is a pointer part of our heap?
bool	mi_check_owned (const void *p)
	v1,v2: Check if any pointer is part of the default heap of this thread.
bool	mi_heap_contains_block (mi_heap_t *heap, const void *p)
	v1,v2: Does a heap contain a pointer to a previously allocated block?
bool	mi_heap_check_owned (mi_heap_t *heap, const void *p)
	v1,v2: Check safely if any pointer is part of a heap.
void	mi_heap_collect (mi_heap_t *heap, bool force)
	Release outstanding resources in a specific heap.
void *	mi_heap_malloc (mi_heap_t *heap, size_t size)
	Allocate in a specific heap.
void *	mi_heap_malloc_small (mi_heap_t *heap, size_t size)
	Allocate a small object in a specific heap.
void *	mi_heap_zalloc (mi_heap_t *heap, size_t size)
	Allocate zero-initialized in a specific heap.
void *	mi_heap_zalloc_small (mi_heap_t *heap, size_t size)
	Allocate a small object in a specific heap.
void *	mi_heap_calloc (mi_heap_t *heap, size_t count, size_t size)
	Allocate count zero-initialized elements in a specific heap.
void *	mi_heap_mallocn (mi_heap_t *heap, size_t count, size_t size)
	Allocate count elements in a specific heap.
char *	mi_heap_strdup (mi_heap_t *heap, const char *s)
	Duplicate a string in a specific heap.
char *	mi_heap_strndup (mi_heap_t *heap, const char *s, size_t n)
	Duplicate a string of at most length n in a specific heap.
char *	mi_heap_realpath (mi_heap_t *heap, const char *fname, char *resolved_name)
	Resolve a file path name using a specific heap to allocate the result.
void *	mi_heap_realloc (mi_heap_t *heap, void *p, size_t newsize)
void *	mi_heap_reallocn (mi_heap_t *heap, void *p, size_t count, size_t size)
void *	mi_heap_reallocf (mi_heap_t *heap, void *p, size_t newsize)
void *	mi_heap_malloc_aligned (mi_heap_t *heap, size_t size, size_t alignment)
void *	mi_heap_malloc_aligned_at (mi_heap_t *heap, size_t size, size_t alignment, size_t offset)
void *	mi_heap_zalloc_aligned (mi_heap_t *heap, size_t size, size_t alignment)
void *	mi_heap_zalloc_aligned_at (mi_heap_t *heap, size_t size, size_t alignment, size_t offset)
void *	mi_heap_calloc_aligned (mi_heap_t *heap, size_t count, size_t size, size_t alignment)
void *	mi_heap_calloc_aligned_at (mi_heap_t *heap, size_t count, size_t size, size_t alignment, size_t offset)
void *	mi_heap_realloc_aligned (mi_heap_t *heap, void *p, size_t newsize, size_t alignment)
void *	mi_heap_realloc_aligned_at (mi_heap_t *heap, void *p, size_t newsize, size_t alignment, size_t offset)

Detailed Description

First-class heaps.

Heaps allow allocations to be grouped, and for example be destroyed in one go. Heaps can also be associated with a specific allocation arena (mi_heap_new_in_arena()).

v1,v2: heaps are only semi-first-class and one can only use heap allocation functions from the thread that created the heap. (of course, mi_free() can always be used from any thread to free objects from any heap).

v3: heaps are fully first-class and can be used to allocate efficiently from from any thread. In v3, the old v1/v2 heaps still exist but are now called theaps (mi_theap_t()) for thread-local heaps. A v3 heap creates internally such theaps on demand to efficiently allocate without needing taking locks for example.

The heap argument of the heap functions must be a valid heap: NULL is not accepted (use mi_heap_main() for the main heap). (except for mi_unsafe_heap_page_is_under_utilized() where NULL matches any heap).

Typedef Documentation

mi_heap_t

typedef struct mi_heap_s mi_heap_t

Type of first-class heaps.

v1,v2: in mimalloc v1 and v2, a heap can only be used for allocation in the thread that created this heap!

Function Documentation

mi_any_heap_contains()

bool mi_any_heap_contains

(

const void *

p

)

v3: is a pointer pointing into mimalloc managed memory?

Parameters

p	Any pointer – not required to be previously allocated by mimalloc. This is a constant time efficient function.

mi_check_owned()

bool mi_check_owned

(

const void *

p

)

v1,v2: Check if any pointer is part of the default heap of this thread.

Parameters

p	Any pointer – not required to be previously allocated by us.

Returns

true if p points to a block in default heap of this thread. Note: expensive function, linear in the pages in the heap.

Deprecated

In v3, use mi_any_heap_contains(); the legacy name checks all heaps, not just the default heap.

mi_heap_calloc()

void * mi_heap_calloc	(	mi_heap_t *	heap,
		size_t	count,
		size_t	size )

Allocate count zero-initialized elements in a specific heap.

See also

mi_calloc()

mi_heap_calloc_aligned()

void * mi_heap_calloc_aligned	(	mi_heap_t *	heap,
		size_t	count,
		size_t	size,
		size_t	alignment )

mi_heap_calloc_aligned_at()

void * mi_heap_calloc_aligned_at	(	mi_heap_t *	heap,
		size_t	count,
		size_t	size,
		size_t	alignment,
		size_t	offset )

mi_heap_check_owned()

bool mi_heap_check_owned	(	mi_heap_t *	heap,
		const void *	p )

v1,v2: Check safely if any pointer is part of a heap.

Parameters

heap	The heap.
p	Any pointer – not required to be previously allocated by us.

Returns

true if p points to a block in heap. Note: expensive function, linear in the pages in the heap.

See also

mi_heap_contains_block(), mi_heap_contains() for v3

mi_heap_collect()

void mi_heap_collect	(	mi_heap_t *	heap,
		bool	force )

Release outstanding resources in a specific heap.

mi_heap_contains()

bool mi_heap_contains	(	const mi_heap_t *	heap,
		const void *	p )

v3: does a heap contain a specific pointer?

Parameters

heap	The heap to query.
p	Any pointer – not required to be previously allocated by mimalloc. This is a constant time efficient function.

mi_heap_contains_block()

bool mi_heap_contains_block	(	mi_heap_t *	heap,
		const void *	p )

v1,v2: Does a heap contain a pointer to a previously allocated block?

Parameters

heap	The heap.
p	Pointer to a previously allocated block (in any heap)– cannot be some random pointer!

Returns

true if the block pointed to by p is in the heap.

See also

mi_heap_owned(), mi_heap_contains() for v3

mi_heap_delete()

void mi_heap_delete

(

mi_heap_t *

heap

)

Delete a heap, releasing its internal resources but keeping live blocks intact.

Parameters

heap	The heap to delete.

Other threads that allocated in the heap should first call mi_thread_heap_release() (or no longer allocate or free in the heap at all). In debug mode, a warning is given for threads that did not release the heap.

This will release internal resources but not free still allocated blocks in this heap (and these should be mi_free'd later on as usual).

Note: trying to delete the main heap of a subprocess is ignored.

See also

mi_heap_destroy() for destroying a Heaps.

mi_thread_heap_release() for releasing a Heaps in the current thread.

mi_heap_destroy()

void mi_heap_destroy

(

mi_heap_t *

heap

)

Destroy a heap, freeing all its still allocated blocks.

Parameters

heap	The heap to destroy.

It is not safe to destroy a heap if other threads are still concurrently allocating or freeing in it!

Use with care as this will free all blocks still allocated in the heap. However, this can be an efficient way to free all heap memory in one go.

Note: trying to destroy the main heap of a subprocess is ignored.

See also

mi_heap_delete() for deleting a Heaps.

mi_thread_heap_release() for releasing a Heaps in the current thread.

mi_heap_get_backing()

mi_heap_t * mi_heap_get_backing

(

)

v1,v2: Get the backing heap.

The backing heap is the initial default heap for a thread and always available for allocations. It cannot be destroyed or deleted except by exiting the thread.

See also

mi_heap_main() for v3

mi_heap_get_default()

mi_heap_t * mi_heap_get_default

(

)

v1,v2: Get the default heap that is used for mi_malloc() et al.

(for the current thread).

Returns

The current default heap.

See also

mi_theap_get_default() for v3

mi_heap_main()

mi_heap_t * mi_heap_main

(

void

)

v3: the main heap (of the current sub-process)

Returns

a pointer to the main heap Every (sub)process has a main heap that cannot be deleted or destroyed until (sub)process exit. If other heaps are deleted their live objects are migrated to the main heap.

mi_heap_malloc()

void * mi_heap_malloc	(	mi_heap_t *	heap,
		size_t	size )

Allocate in a specific heap.

See also

mi_malloc()

mi_heap_malloc_aligned()

void * mi_heap_malloc_aligned	(	mi_heap_t *	heap,
		size_t	size,
		size_t	alignment )

mi_heap_malloc_aligned_at()

void * mi_heap_malloc_aligned_at	(	mi_heap_t *	heap,
		size_t	size,
		size_t	alignment,
		size_t	offset )

mi_heap_malloc_small()

void * mi_heap_malloc_small	(	mi_heap_t *	heap,
		size_t	size )

Allocate a small object in a specific heap.

size must be smaller or equal to MI_SMALL_SIZE_MAX().

See also

mi_malloc_small()

mi_heap_mallocn()

void * mi_heap_mallocn	(	mi_heap_t *	heap,
		size_t	count,
		size_t	size )

Allocate count elements in a specific heap.

See also

mi_mallocn()

mi_heap_new()

mi_heap_t * mi_heap_new

(

)

Create a new heap that can be used for allocation.

mi_heap_of()

mi_heap_t * mi_heap_of

(

const void *

p

)

v3: return the heap that contains the given pointer.

Parameters

p	Any pointer – not required to be previously allocated by mimalloc.

Returns

the heap that contains the given pointer, or NULL if the pointer does not point into mimalloc allocated memory. This is a constant time efficient function.

mi_heap_realloc()

void * mi_heap_realloc	(	mi_heap_t *	heap,
		void *	p,
		size_t	newsize )

mi_heap_realloc_aligned()

void * mi_heap_realloc_aligned	(	mi_heap_t *	heap,
		void *	p,
		size_t	newsize,
		size_t	alignment )

mi_heap_realloc_aligned_at()

void * mi_heap_realloc_aligned_at	(	mi_heap_t *	heap,
		void *	p,
		size_t	newsize,
		size_t	alignment,
		size_t	offset )

mi_heap_reallocf()

void * mi_heap_reallocf	(	mi_heap_t *	heap,
		void *	p,
		size_t	newsize )

mi_heap_reallocn()

void * mi_heap_reallocn	(	mi_heap_t *	heap,
		void *	p,
		size_t	count,
		size_t	size )

mi_heap_realpath()

char * mi_heap_realpath	(	mi_heap_t *	heap,
		const char *	fname,
		char *	resolved_name )

Resolve a file path name using a specific heap to allocate the result.

See also

mi_realpath()

mi_heap_set_debug_fill_preserve()

void mi_heap_set_debug_fill_preserve	(	mi_heap_t *	heap,
		size_t	preserve )

v3: Exclude the first preserve bytes of each block from debug filling on allocation and free.

This does not prevent allocator metadata, zero-initialization, or security mitigations from changing those bytes.

mi_heap_set_default()

mi_heap_t * mi_heap_set_default

(

mi_heap_t *

heap

)

v1,v2: Set the default heap to use in the current thread for mi_malloc() et al.

Parameters

heap	The new default heap.

Returns

The previous default heap.

See also

mi_theap_set_default() for v3

mi_heap_set_numa_affinity()

void mi_heap_set_numa_affinity	(	mi_heap_t *	heap,
		int	numa_node )

v3: set NUMA affinity for a heap.

Parameters

heap	the heap which should be associated with a specific numa node.
numa_node	the numa node to associate to (>=0)

mi_heap_strdup()

char * mi_heap_strdup	(	mi_heap_t *	heap,
		const char *	s )

Duplicate a string in a specific heap.

See also

mi_strdup()

mi_heap_strndup()

char * mi_heap_strndup	(	mi_heap_t *	heap,
		const char *	s,
		size_t	n )

Duplicate a string of at most length n in a specific heap.

See also

mi_strndup()

mi_heap_zalloc()

void * mi_heap_zalloc	(	mi_heap_t *	heap,
		size_t	size )

Allocate zero-initialized in a specific heap.

See also

mi_zalloc()

mi_heap_zalloc_aligned()

void * mi_heap_zalloc_aligned	(	mi_heap_t *	heap,
		size_t	size,
		size_t	alignment )

mi_heap_zalloc_aligned_at()

void * mi_heap_zalloc_aligned_at	(	mi_heap_t *	heap,
		size_t	size,
		size_t	alignment,
		size_t	offset )

mi_heap_zalloc_small()

void * mi_heap_zalloc_small	(	mi_heap_t *	heap,
		size_t	size )

Allocate a small object in a specific heap.

size must be smaller or equal to MI_SMALL_SIZE_MAX().

See also

mi_zalloc_small()

mi_is_in_heap_region()

bool mi_is_in_heap_region

(

const void *

p

)

v1,v2: Is a pointer part of our heap?

Parameters

p	The pointer to check.

Returns

true if this is a pointer into our heap. This function is relatively fast.

Deprecated

In v3, use mi_any_heap_contains().

mi_thread_heap_release()

void mi_thread_heap_release

(

mi_heap_t *

heap

)

Release a heap in the calling thread – promises to not allocate in that heap anymore.

Parameters

heap	The heap to release in the calling thread.

After this call, allocation in the heap from this thread returns NULL. If using mi_heap_delete() it is recommended to first release the heap in all threads that allocated in it. In particular, for mi_heap_delete() it is not safe if any thread is concurrently freeing (or allocating) in that heap while it is being deleted. However, if each other thread that allocated in the heap first calls mi_thread_heap_release(), it is safe to delete the heap even with concurrent freeing. Using mi_thread_heap_release() is not needed for mi_heap_destroy() (where all blocks are freed) but it is still good practice. Calling this multiple times is allowed.

Note: trying to release the main heap of a subprocess is ignored.

See also

mi_heap_delete() for deleting a Heaps.

mi_heap_destroy() for destroying a Heaps.