mi-malloc: Extended Functions

| mi-malloc 1.7/2.0 |

Macros | Typedefs | Functions
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)) More...

## Typedefs
typedef void() | mi_deferred_free_fun(bool force, unsigned long long heartbeat, void *arg)
| Type of deferred free functions. More...
typedef void() | mi_output_fun(const char *msg, void *arg)
| Type of output functions. More...
typedef void() | mi_error_fun(int err, void *arg)
| Type of error callback functions. More...

## Functions
void * | mi_malloc_small (size_t size)
| Allocate a small object. More...
void * | mi_zalloc_small (size_t size)
| Allocate a zero initialized small object. More...
size_t | mi_usable_size (void *p)
| Return the available bytes in a memory block. More...
size_t | mi_good_size (size_t size)
| Return the used allocation size. More...
void | mi_collect (bool force)
| Eagerly free memory. More...
void | mi_stats_print (void *out)
| Deprecated. More...
void | mi_stats_print_out (mi_output_fun *out, void *arg)
| Print the main statistics. More...
void | mi_stats_reset (void)
| Reset statistics. More...
void | mi_stats_merge (void)
| Merge thread local statistics with the main statistics and reset. More...
void | mi_thread_init (void)
| Initialize mimalloc on a thread. More...
void | mi_thread_done (void)
| Uninitialize mimalloc on a thread. More...
void | mi_thread_stats_print_out (mi_output_fun *out, void *arg)
| Print out heap statistics for this thread. More...
void | mi_register_deferred_free (mi_deferred_free_fun *deferred_free, void *arg)
| Register a deferred free function. More...
void | mi_register_output (mi_output_fun *out, void *arg)
| Register an output function. More...
void | mi_register_error (mi_error_fun *errfun, void *arg)
| Register an error callback function. More...
bool | mi_is_in_heap_region (const void *p)
| Is a pointer part of our heap? More...
int | mi_reserve_os_memory (size_t size, bool commit, bool allow_large)
| Reserve OS memory for use by mimalloc. More...
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. More...
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. More...
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. More...
bool | mi_is_redirected ()
| Is the C runtime malloc API redirected? More...
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). More...

## 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_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()

## Function Documentation

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

Currenty 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.
  commit | 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_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).
  timeout_msecs | Maximum number of milli-seconds to try reserving, or 0 for no timeout.

Returns
  0 if successfull, 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_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 successfull, 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_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_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, and, in the current design, should be less than 16.7% more.

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!