mi-malloc: Internals

| mi-malloc v1.9, v2.2, v3.2 |

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

Internals More...

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

## Functions
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_set_in_threadpool (void)
| V3: Communicate that a thread is in a threadpool.
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.

## Detailed Description

Internals

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

void mi_thread_set_in_threadpool | ( | void |  | ) |

V3: Communicate that a thread is in a threadpool.

This is done automatically for threads in the Windows threadpool, but if using a custom threadpool it is good to call this on worker threads. Internally, mimalloc uses different locality heuristics for worker threads to try to reduce non-local accesss.