docs/group__arenas.html
Loading...
Searching...
No Matches
Arenas
Arenas are large memory areas (usually 1GiB+) from which mimalloc allocates memory. More...
|
|
| typedef int | mi_arena_id_t |
| | Each arena has an associated identifier.
|
| |
|
|
| 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.
|
| |
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 int mi_arena_id_t |
Each arena has an associated identifier.
| 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. |
Returnsbase address of the arena.
| size_t mi_arena_min_alignment | ( | void | | ) | |
Return the minimal alignment required for managed OS memory.
See alsomi_manage_os_memory(), mi_manage_os_memory_ex()
| void mi_debug_show_arenas | ( | void | | ) | |
Show all current arena's.
| 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. |
ReturnsA 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 alsomi_heap_new_in_arena() for v3
| 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. |
ReturnsThe new heap or NULL.
| 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.
| 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. |
Returnstrue if successful.
| 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. |
Returns0 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.
| 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. |
Returns0 if successful, ENOMEM if running out of memory, or ETIMEDOUT if timed out.
| 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. |
Returns0 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.
| 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).
| 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. |
ReturnsZero on success, an error code otherwise.