Extended Functions

Extended functionality. More...

Macros
#define	MI_SMALL_SIZE_MAX
	Maximum size allowed for small allocations in mi_malloc_small and mi_zalloc_small (usually 128*sizeof(void*) (= 1KB on 64-bit systems))

Typedefs
typedef void	mi_deferred_free_fun(bool force, unsigned long long heartbeat, void *arg)
	Type of deferred free functions.
typedef void	mi_output_fun(const char *msg, void *arg)
	Type of output functions.
typedef void	mi_error_fun(int err, void *arg)
	Type of error callback functions.
typedef int	mi_arena_id_t
	Mimalloc uses large (virtual) memory areas, called "arena"s, from the OS to manage its memory.
typedef void *	mi_subproc_id_t
	A process can associate threads with sub-processes.

Functions
void *	mi_malloc_small (size_t size)
	Allocate a small object.
void *	mi_zalloc_small (size_t size)
	Allocate a zero initialized small object.
size_t	mi_usable_size (void *p)
	Return the available bytes in a memory block.
size_t	mi_good_size (size_t size)
	Return the used allocation size.
void	mi_collect (bool force)
	Eagerly free memory.
void	mi_stats_print (void *out)
	Deprecated.
void	mi_stats_print_out (mi_output_fun *out, void *arg)
	Print the main statistics.
void	mi_stats_reset (void)
	Reset statistics.
void	mi_stats_merge (void)
	Merge thread local statistics with the main statistics and reset.
void	mi_thread_init (void)
	Initialize mimalloc on a thread.
void	mi_thread_done (void)
	Uninitialize mimalloc on a thread.
void	mi_thread_stats_print_out (mi_output_fun *out, void *arg)
	Print out heap statistics for this thread.
void	mi_register_deferred_free (mi_deferred_free_fun *deferred_free, void *arg)
	Register a deferred free function.
void	mi_register_output (mi_output_fun *out, void *arg)
	Register an output function.
void	mi_register_error (mi_error_fun *errfun, void *arg)
	Register an error callback function.
bool	mi_is_in_heap_region (const void *p)
	Is a pointer part of our heap?
int	mi_reserve_os_memory (size_t size, bool commit, bool allow_large)
	Reserve OS memory for use by mimalloc.
bool	mi_manage_os_memory (void *start, size_t size, bool is_committed, bool is_large, bool is_zero, int numa_node)
	Manage a particular memory area for use by mimalloc.
int	mi_reserve_huge_os_pages_interleave (size_t pages, size_t numa_nodes, size_t timeout_msecs)
	Reserve pages of huge OS pages (1GiB) evenly divided over numa_nodes nodes, but stops after at most timeout_msecs seconds.
int	mi_reserve_huge_os_pages_at (size_t pages, int numa_node, size_t timeout_msecs)
	Reserve pages of huge OS pages (1GiB) at a specific numa_node, but stops after at most timeout_msecs seconds.
bool	mi_is_redirected ()
	Is the C runtime malloc API redirected?
void	mi_process_info (size_t *elapsed_msecs, size_t *user_msecs, size_t *system_msecs, size_t *current_rss, size_t *peak_rss, size_t *current_commit, size_t *peak_commit, size_t *page_faults)
	Return process information (time and memory usage).
void	mi_debug_show_arenas (bool show_inuse, bool show_abandoned, bool show_purge)
	Show all current arena's.
void *	mi_arena_area (mi_arena_id_t arena_id, size_t *size)
	Return the size of an arena.
int	mi_reserve_huge_os_pages_at_ex (size_t pages, int numa_node, size_t timeout_msecs, bool exclusive, mi_arena_id_t *arena_id)
	Reserve huge OS pages (1GiB) into a single arena.
int	mi_reserve_os_memory_ex (size_t size, bool commit, bool allow_large, bool exclusive, mi_arena_id_t *arena_id)
	Reserve OS memory to be managed in an arena.
bool	mi_manage_os_memory_ex (void *start, size_t size, bool is_committed, bool is_large, bool is_zero, int numa_node, bool exclusive, mi_arena_id_t *arena_id)
	Manage externally allocated memory as a mimalloc arena.
mi_heap_t *	mi_heap_new_in_arena (mi_arena_id_t arena_id)
	Create a new heap that only allocates in the specified arena.
mi_heap_t *	mi_heap_new_ex (int heap_tag, bool allow_destroy, mi_arena_id_t arena_id)
	Create a new heap.
mi_subproc_id_t	mi_subproc_main (void)
	Get the main sub-process identifier.
mi_subproc_id_t	mi_subproc_new (void)
	Create a fresh sub-process (with no associated threads yet).
void	mi_subproc_delete (mi_subproc_id_t subproc)
	Delete a previously created sub-process.
void	mi_subproc_add_current_thread (mi_subproc_id_t subproc)
	Add the current thread to the given sub-process.

Detailed Description

Extended functionality.

Macro Definition Documentation

MI_SMALL_SIZE_MAX

#define MI_SMALL_SIZE_MAX

Maximum size allowed for small allocations in mi_malloc_small and mi_zalloc_small (usually 128*sizeof(void*) (= 1KB on 64-bit systems))

Typedef Documentation

mi_arena_id_t

typedef int mi_arena_id_t

Mimalloc uses large (virtual) memory areas, called "arena"s, from the OS to manage its memory.

Each arena has an associated identifier.

mi_deferred_free_fun

typedef void mi_deferred_free_fun(bool force, unsigned long long heartbeat, void *arg)

Type of deferred free functions.

Parameters

force	If true all outstanding items should be freed.
heartbeat	A monotonically increasing count.
arg	Argument that was passed at registration to hold extra state.

See also

mi_register_deferred_free

mi_error_fun

typedef void mi_error_fun(int err, void *arg)

Type of error callback functions.

Parameters

err	Error code (see mi_register_error() for a complete list).
arg	Argument that was passed at registration to hold extra state.

See also

mi_register_error()

mi_output_fun

typedef void mi_output_fun(const char *msg, void *arg)

Type of output functions.

Parameters

msg	Message to output.
arg	Argument that was passed at registration to hold extra state.

See also

mi_register_output()

mi_subproc_id_t

typedef void* mi_subproc_id_t

A process can associate threads with sub-processes.

A sub-process will not reclaim memory from (abandoned heaps/threads) other subprocesses.

Function Documentation

mi_arena_area()

void * mi_arena_area	(	mi_arena_id_t	arena_id,
		size_t *	size )

Return the size of an arena.

Parameters

arena_id	The arena identifier.
size	Returned size in bytes of the (virtual) arena area.

Returns

base address of the arena.

mi_collect()

void mi_collect

(

bool

force

)

Eagerly free memory.

Parameters

force

If true, aggressively return memory to the OS (can be expensive!)

Regular code should not have to call this function. It can be beneficial in very narrow circumstances; in particular, when a long running thread allocates a lot of blocks that are freed by other threads it may improve resource usage by calling this every once in a while.

mi_debug_show_arenas()

void mi_debug_show_arenas	(	bool	show_inuse,
		bool	show_abandoned,
		bool	show_purge )

Show all current arena's.

Parameters

show_inuse	Show the arena blocks that are in use.
show_abandoned	Show the abandoned arena blocks.
show_purge	Show arena blocks scheduled for purging.

mi_good_size()

size_t mi_good_size

(

size_t

size

)

Return the used allocation size.

Parameters

size	The minimal required size in bytes.

Returns

the size n that will be allocated, where n >= size.

Generally, mi_usable_size(mi_malloc(size)) == mi_good_size(size). This can be used to reduce internal wasted space when allocating buffers for example.

See also

mi_usable_size()

mi_heap_new_ex()

mi_heap_t * mi_heap_new_ex	(	int	heap_tag,
		bool	allow_destroy,
		mi_arena_id_t	arena_id )

Create a new heap.

Parameters

heap_tag	The heap tag associated with this heap; heaps only reclaim memory between heaps with the same tag.
allow_destroy	Is mi_heap_destroy allowed? Not allowing this allows the heap to reclaim memory from terminated threads.
arena_id	If not 0, the heap will only allocate from the specified arena.

Returns

A new heap or NULL on failure.

The arena_id can be used by runtimes to allocate only in a specified pre-reserved arena. This is used for example for a compressed pointer heap in Koka. The heap_tag enables heaps to keep objects of a certain type isolated to heaps with that tag. This is used for example in the CPython integration.

mi_heap_new_in_arena()

mi_heap_t * mi_heap_new_in_arena

(

mi_arena_id_t

arena_id

)

Create a new heap that only allocates in the specified arena.

Parameters

arena_id

The arena identifier.

Returns

The new heap or NULL.

mi_is_in_heap_region()

bool mi_is_in_heap_region

(

const void *

p

)

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.

mi_is_redirected()

bool mi_is_redirected

(

)

Is the C runtime malloc API redirected?

Returns

true if all malloc API calls are redirected to mimalloc.

Currently only used on Windows.

mi_malloc_small()

void * mi_malloc_small

(

size_t

size

)

Allocate a small object.

Parameters

size	The size in bytes, can be at most MI_SMALL_SIZE_MAX.

Returns

a pointer to newly allocated memory of at least size bytes, or NULL if out of memory. This function is meant for use in run-time systems for best performance and does not check if size was indeed small – use with care!

mi_manage_os_memory()

bool mi_manage_os_memory	(	void *	start,
		size_t	size,
		bool	is_committed,
		bool	is_large,
		bool	is_zero,
		int	numa_node )

Manage a particular memory area for use by mimalloc.

This is just like mi_reserve_os_memory except that the area should already be allocated in some manner and available for use my mimalloc.

Parameters

start	Start of the memory area
size	The size of the memory area.
is_committed	Is the area already committed?
is_large	Does it consist of large OS pages? Set this to true as well for memory that should not be decommitted or protected (like rdma etc.)
is_zero	Does the area consists of zero's?
numa_node	Possible associated numa node or -1.

Returns

true if successful, and false on error.

mi_manage_os_memory_ex()

bool mi_manage_os_memory_ex	(	void *	start,
		size_t	size,
		bool	is_committed,
		bool	is_large,
		bool	is_zero,
		int	numa_node,
		bool	exclusive,
		mi_arena_id_t *	arena_id )

Manage externally allocated memory as a mimalloc arena.

This memory will not be freed by mimalloc.

Parameters

start	Start address of the area.
size	Size in bytes of the area.
is_committed	Is the memory already committed?
is_large	Does it consist of (pinned) large OS pages?
is_zero	Is the memory zero-initialized?
numa_node	Associated NUMA node, or -1 to have no NUMA preference.
exclusive	Is the arena exclusive (where only heaps associated with the arena can allocate in it)
arena_id	The new arena identifier.

Returns

true if successful.

mi_process_info()

void mi_process_info	(	size_t *	elapsed_msecs,
		size_t *	user_msecs,
		size_t *	system_msecs,
		size_t *	current_rss,
		size_t *	peak_rss,
		size_t *	current_commit,
		size_t *	peak_commit,
		size_t *	page_faults )

Return process information (time and memory usage).

Parameters

elapsed_msecs	Optional. Elapsed wall-clock time of the process in milli-seconds.
user_msecs	Optional. User time in milli-seconds (as the sum over all threads).
system_msecs	Optional. System time in milli-seconds.
current_rss	Optional. Current working set size (touched pages).
peak_rss	Optional. Peak working set size (touched pages).
current_commit	Optional. Current committed memory (backed by the page file).
peak_commit	Optional. Peak committed memory (backed by the page file).
page_faults	Optional. Count of hard page faults.

The current_rss is precise on Windows and MacOSX; other systems estimate this using current_commit. The commit is precise on Windows but estimated on other systems as the amount of read/write accessible memory reserved by mimalloc.

mi_register_deferred_free()

void mi_register_deferred_free	(	mi_deferred_free_fun *	deferred_free,
		void *	arg )

Register a deferred free function.

Parameters

deferred_free	Address of a deferred free-ing function or NULL to unregister.
arg	Argument that will be passed on to the deferred free function.

Some runtime systems use deferred free-ing, for example when using reference counting to limit the worst case free time. Such systems can register (re-entrant) deferred free function to free more memory on demand. When the force parameter is true all possible memory should be freed. The per-thread heartbeat parameter is monotonically increasing and guaranteed to be deterministic if the program allocates deterministically. The deferred_free function is guaranteed to be called deterministically after some number of allocations (regardless of freeing or available free memory). At most one deferred_free function can be active.

mi_register_error()

void mi_register_error	(	mi_error_fun *	errfun,
		void *	arg )

Register an error callback function.

Parameters

errfun	The error function that is called on an error (use NULL for default)
arg	Extra argument that will be passed on to the error function.

The errfun function is called on an error in mimalloc after emitting an error message (through the output function). It as always legal to just return from the errfun function in which case allocation functions generally return NULL or ignore the condition. The default function only calls abort() when compiled in secure mode with an EFAULT error. The possible error codes are:

• EAGAIN: Double free was detected (only in debug and secure mode).
• EFAULT: Corrupted free list or meta-data was detected (only in debug and secure mode).
• ENOMEM: Not enough memory available to satisfy the request.
• EOVERFLOW: Too large a request, for example in mi_calloc(), the count and size parameters are too large.
• EINVAL: Trying to free or re-allocate an invalid pointer.

mi_register_output()

void mi_register_output	(	mi_output_fun *	out,
		void *	arg )

Register an output function.

Parameters

out	The output function, use NULL to output to stderr.
arg	Argument that will be passed on to the output function.

The out function is called to output any information from mimalloc, like verbose or warning messages.

mi_reserve_huge_os_pages_at()

int mi_reserve_huge_os_pages_at	(	size_t	pages,
		int	numa_node,
		size_t	timeout_msecs )

Reserve pages of huge OS pages (1GiB) at a specific numa_node, but stops after at most timeout_msecs seconds.

Parameters

pages	The number of 1GiB pages to reserve.
numa_node	The NUMA node where the memory is reserved (start at 0). Use -1 for no affinity.
timeout_msecs	Maximum number of milli-seconds to try reserving, or 0 for no timeout.

Returns

0 if successful, ENOMEM if running out of memory, or ETIMEDOUT if timed out.

The reserved memory is used by mimalloc to satisfy allocations. May quit before timeout_msecs are expired if it estimates it will take more than 1.5 times timeout_msecs. The time limit is needed because on some operating systems it can take a long time to reserve contiguous memory if the physical memory is fragmented.

mi_reserve_huge_os_pages_at_ex()

int mi_reserve_huge_os_pages_at_ex	(	size_t	pages,
		int	numa_node,
		size_t	timeout_msecs,
		bool	exclusive,
		mi_arena_id_t *	arena_id )

Reserve huge OS pages (1GiB) into a single arena.

Parameters

pages	Number of 1GiB pages to reserve.
numa_node	The associated NUMA node, or -1 for no NUMA preference.
timeout_msecs	Max amount of milli-seconds this operation is allowed to take. (0 is infinite)
exclusive	If exclusive, only a heap associated with this arena can allocate in it.
arena_id	The arena identifier.

Returns

0 if successful, ENOMEM if running out of memory, or ETIMEDOUT if timed out.

mi_reserve_huge_os_pages_interleave()

int mi_reserve_huge_os_pages_interleave	(	size_t	pages,
		size_t	numa_nodes,
		size_t	timeout_msecs )

Reserve pages of huge OS pages (1GiB) evenly divided over numa_nodes nodes, but stops after at most timeout_msecs seconds.

Parameters

pages	The number of 1GiB pages to reserve.
numa_nodes	The number of nodes do evenly divide the pages over, or 0 for using the actual number of NUMA nodes.
timeout_msecs	Maximum number of milli-seconds to try reserving, or 0 for no timeout.

Returns

0 if successful, ENOMEM if running out of memory, or ETIMEDOUT if timed out.

The reserved memory is used by mimalloc to satisfy allocations. May quit before timeout_msecs are expired if it estimates it will take more than 1.5 times timeout_msecs. The time limit is needed because on some operating systems it can take a long time to reserve contiguous memory if the physical memory is fragmented.

mi_reserve_os_memory()

int mi_reserve_os_memory	(	size_t	size,
		bool	commit,
		bool	allow_large )

Reserve OS memory for use by mimalloc.

Reserved areas are used before allocating from the OS again. By reserving a large area upfront, allocation can be more efficient, and can be better managed on systems without mmap/VirtualAlloc (like WASM for example).

Parameters

size	The size to reserve.
commit	Commit the memory upfront.
allow_large	Allow large OS pages (2MiB) to be used?

Returns

0 if successful, and an error code otherwise (e.g. ENOMEM).

mi_reserve_os_memory_ex()

int mi_reserve_os_memory_ex	(	size_t	size,
		bool	commit,
		bool	allow_large,
		bool	exclusive,
		mi_arena_id_t *	arena_id )

Reserve OS memory to be managed in an arena.

Parameters

size	Size the reserve.
commit	Should the memory be initially committed?
allow_large	Allow the use of large OS pages?
exclusive	Is the returned arena exclusive?
arena_id	The new arena identifier.

Returns

Zero on success, an error code otherwise.

mi_stats_merge()

void mi_stats_merge

(

void

)

Merge thread local statistics with the main statistics and reset.

mi_stats_print()

void mi_stats_print

(

void *

out

)

Deprecated.

Parameters

out	Ignored, outputs to the registered output function or stderr by default.

Most detailed when using a debug build.

mi_stats_print_out()

void mi_stats_print_out	(	mi_output_fun *	out,
		void *	arg )

Print the main statistics.

Parameters

out	An output function or NULL for the default.
arg	Optional argument passed to out (if not NULL)

Most detailed when using a debug build.

mi_stats_reset()

void mi_stats_reset

(

void

)

Reset statistics.

mi_subproc_add_current_thread()

void mi_subproc_add_current_thread

(

mi_subproc_id_t

subproc

)

Add the current thread to the given sub-process.

This should be called right after a thread is created (and no allocation has taken place yet)

mi_subproc_delete()

void mi_subproc_delete

(

mi_subproc_id_t

subproc

)

Delete a previously created sub-process.

Parameters

subproc

The sub-process identifier. Only delete sub-processes if all associated threads have terminated.

mi_subproc_main()

mi_subproc_id_t mi_subproc_main

(

void

)

Get the main sub-process identifier.

mi_subproc_new()

mi_subproc_id_t mi_subproc_new

(

void

)

Create a fresh sub-process (with no associated threads yet).

Returns

The new sub-process identifier.

mi_thread_done()

void mi_thread_done

(

void

)

Uninitialize mimalloc on a thread.

Should not be used as on most systems (pthreads, windows) this is done automatically. Ensures that any memory that is not freed yet (but will be freed by other threads in the future) is properly handled.

mi_thread_init()

void mi_thread_init

(

void

)

Initialize mimalloc on a thread.

Should not be used as on most systems (pthreads, windows) this is done automatically.

mi_thread_stats_print_out()

void mi_thread_stats_print_out	(	mi_output_fun *	out,
		void *	arg )

Print out heap statistics for this thread.

Parameters

out	An output function or NULL for the default.
arg	Optional argument passed to out (if not NULL)

Most detailed when using a debug build.

mi_usable_size()

size_t mi_usable_size

(

void *

p

)

Return the available bytes in a memory block.

Parameters

p	Pointer to previously allocated memory (or NULL)

Returns

Returns the available bytes in the memory block, or 0 if p was NULL.

The returned size can be used to call mi_expand successfully. The returned size is always at least equal to the allocated size of p.

See also

_msize (Windows)

malloc_usable_size (Linux)

mi_good_size()

mi_zalloc_small()

void * mi_zalloc_small

(

size_t

size

)

Allocate a zero initialized small object.

Parameters

size	The size in bytes, can be at most MI_SMALL_SIZE_MAX.

Returns

a pointer to newly allocated zero-initialized memory of at least size bytes, or NULL if out of memory. This function is meant for use in run-time systems for best performance and does not check if size was indeed small – use with care!