Arenas are large memory areas (usually 1GiB+) from which mimalloc allocates memory. More...

Typedefs
typedef int	mi_arena_id_t
	Each arena has an associated identifier.

Functions
int	mi_reserve_os_memory (size_t size, bool commit, bool allow_large)
	Reserve OS memory for use by mimalloc.

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.

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.

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.

size_t	mi_arena_min_alignment (void)
	Return the minimal alignment required for managed 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.

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.

void	mi_debug_show_arenas (void)
	Show all current arena's.

void *	mi_arena_area (mi_arena_id_t arena_id, size_t *size)
	Return the start and size of an 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)
	v1,v2: Create a new heap.

Detailed Description

Arenas are large memory areas (usually 1GiB+) from which mimalloc allocates memory.

The arenas are usually allocated on-demand from the OS but can be reserved explicitly. It is also possible to give previously allocated memory to mimalloc to manage. Heaps can be associated with a specific arena to only allocate memory from that arena.

Typedef Documentation

◆ mi_arena_id_t

typedef int mi_arena_id_t

Each arena has an associated identifier.

Function Documentation

◆ mi_arena_area()

void * mi_arena_area	(	mi_arena_id_t	arena_id,
		size_t *	size )

Return the start and 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_arena_min_alignment()

size_t mi_arena_min_alignment ( void )

Return the minimal alignment required for managed OS memory.

See also: mi_manage_os_memory(), mi_manage_os_memory_ex()

◆ mi_debug_show_arenas()

void mi_debug_show_arenas ( void )

Show all current arena's.

◆ mi_heap_new_ex()

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

v1,v2: 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.

See also: mi_heap_new_in_arena() for v3

◆ 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_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_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.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ mi_arena_id_t

Function Documentation

◆ mi_arena_area()

◆ mi_arena_min_alignment()

◆ mi_debug_show_arenas()

◆ mi_heap_new_ex()

◆ mi_heap_new_in_arena()

◆ mi_manage_os_memory()

◆ mi_manage_os_memory_ex()

◆ mi_reserve_huge_os_pages_at()

◆ mi_reserve_huge_os_pages_at_ex()

◆ mi_reserve_huge_os_pages_interleave()

◆ mi_reserve_os_memory()

◆ mi_reserve_os_memory_ex()