mi-malloc: Arenas

| mi-malloc 1.8/2.1 |

Loading...
Searching...
No Matches
Typedefs | Functions
Arenas

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.