Internal functionality. More...
Macros | |
| #define | MI_SMALL_WSIZE_MAX |
| Maximum number of machine words allowed for mi_wmalloc_small(). | |
| #define | MI_SMALL_SIZE_MAX |
| Maximum size in bytes allowed for small allocations in mi_malloc_small, mi_zalloc_small, mi_heap_malloc_small, mi_heap_zalloc_small, mi_theap_malloc_small, and mi_theap_zalloc_small (128*sizeof(size_t), or 1 KiB on 64-bit systems). | |
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 | |
| int | mi_version (void) |
| Return the mimalloc version. | |
| void | mi_collect (bool force) |
| Eagerly free memory. | |
| void | mi_collect_reduce (size_t target_thread_owned) |
| void | mi_process_init (void) |
| Initialize mimalloc for the process. Normally called automatically; repeated calls have no effect. | |
| void | mi_process_done (void) |
| Perform process-exit cleanup. | |
| void | mi_thread_set_in_threadpool (void) |
| v3: Communicate that a thread is in a threadpool. | |
| bool | mi_is_redirected () |
| Is the C runtime malloc API redirected? | |
| void | mi_thread_init (void) |
| Initialize mimalloc on a thread. | |
| void | mi_thread_done (void) |
| Uninitialize mimalloc on a thread. | |
| 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. | |
| void * | mi_malloc_small (size_t size) |
| Allocate a small object. | |
| void * | mi_wmalloc_small (size_t wsize) |
| v3: Allocate a small object with its size expressed in machine words. | |
| void * | mi_wzalloc_small (size_t wsize) |
| v3: As mi_wmalloc_small(), but zero-initialize the allocation. | |
| size_t | mi_wsize_from_size (size_t size) |
| v3: Convert a byte size to a number of sizeof(size_t) words, rounding up. | |
| void * | mi_zalloc_small (size_t size) |
| Allocate a zero initialized small object. | |
| void | mi_free_small (void *p) |
| v3: Can be used to free an object that was allocated with mi_malloc_small() or any allocation with a size < MI_SMALL_SIZE_MAX() | |
| void | mi_free_small_nonnull (void *p) |
| v3: Can be used to free an object that was allocated with mi_malloc_small() or any allocation with a size < MI_SMALL_SIZE_MAX() | |
| void | mi_free_small_local (void *p) |
| v3: As mi_free_small(), but the block's page must be owned by the calling thread. | |
| void | mi_free_small_local_nonnull (void *p) |
| As mi_free_small_local(), but p must not be NULL. | |
Internal functionality.
| #define MI_SMALL_SIZE_MAX |
Maximum size in bytes allowed for small allocations in mi_malloc_small, mi_zalloc_small, mi_heap_malloc_small, mi_heap_zalloc_small, mi_theap_malloc_small, and mi_theap_zalloc_small (128*sizeof(size_t), or 1 KiB on 64-bit systems).
| #define MI_SMALL_WSIZE_MAX |
Maximum number of machine words allowed for mi_wmalloc_small().
A machine word is sizeof(size_t) bytes.
| typedef void mi_deferred_free_fun(bool force, unsigned long long heartbeat, void *arg) |
Type of deferred free functions.
| 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. |
| typedef void mi_error_fun(int err, void *arg) |
Type of error callback functions.
| err | Error code (see mi_register_error() for a complete list). |
| arg | Argument that was passed at registration to hold extra state. |
| typedef void mi_output_fun(const char *msg, void *arg) |
Type of output functions.
| msg | Message to output. |
| arg | Argument that was passed at registration to hold extra state. |
| void mi_collect | ( | bool | force | ) |
Eagerly free memory.
| 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.
| void mi_collect_reduce | ( | size_t | target_thread_owned | ) |
| void mi_free_small | ( | void * | p | ) |
v3: Can be used to free an object that was allocated with mi_malloc_small() or any allocation with a size < MI_SMALL_SIZE_MAX()
| p | Pointer that was returned from mi_malloc_small et al. (or NULL ) |
This function is meant for use in run-time systems for best performance and does not check if the pointer was indeed allocated as a small object – use with care!
| void mi_free_small_local | ( | void * | p | ) |
v3: As mi_free_small(), but the block's page must be owned by the calling thread.
p may be NULL. The caller must guarantee both the small size and page ownership.
| void mi_free_small_local_nonnull | ( | void * | p | ) |
As mi_free_small_local(), but p must not be NULL.
| void mi_free_small_nonnull | ( | void * | p | ) |
v3: Can be used to free an object that was allocated with mi_malloc_small() or any allocation with a size < MI_SMALL_SIZE_MAX()
| p | Pointer that was returned from mi_malloc_small et al. Cannot be NULL ! |
This function is meant for use in run-time systems for best performance and does not check if the pointer was indeed allocated as a small object or not NULL – use with care!
| bool mi_is_redirected | ( | ) |
Is the C runtime malloc API redirected?
Currently only used on Windows.
| void * mi_malloc_small | ( | size_t | size | ) |
Allocate a small object.
| size | The size in bytes, can be at most MI_SMALL_SIZE_MAX. |
| void mi_process_done | ( | void | ) |
Perform process-exit cleanup.
Normally called automatically on process exit or library unload. Not intended for use while the program continues allocating.
| void mi_process_init | ( | void | ) |
Initialize mimalloc for the process. Normally called automatically; repeated calls have no effect.
| void mi_register_deferred_free | ( | mi_deferred_free_fun * | deferred_free, |
| void * | arg ) |
Register a deferred free function.
| 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.
| void mi_register_error | ( | mi_error_fun * | errfun, |
| void * | arg ) |
Register an error callback function.
| 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. An EFAULT error message is always shown, and when compiled in secure mode, mimalloc always calls abort() after an EFAULT error (even if the error function returns). The possible error codes are:
Independent of the error code passed to errfun, allocation functions that return NULL set errno as required by POSIX: ENOMEM, or EINVAL for an invalid alignment. Other errors (like freeing an invalid pointer) do not modify errno.
| void mi_register_output | ( | mi_output_fun * | out, |
| void * | arg ) |
Register an output function.
| 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.
| 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. Afterwards, the thread is not implicitly re-initialized: allocations (for example in thread-local destructors) use a shared fallback heap until mi_thread_init() is called explicitly.
| void mi_thread_init | ( | void | ) |
Initialize mimalloc on a thread.
Should not be used as on most systems (pthreads, windows) this is done automatically.
| 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.
| int mi_version | ( | void | ) |
Return the mimalloc version.
| void * mi_wmalloc_small | ( | size_t | wsize | ) |
v3: Allocate a small object with its size expressed in machine words.
| wsize | The number of words, at most MI_SMALL_WSIZE_MAX. Each word is sizeof(size_t) bytes, not necessarily the size of a pointer. |
| size_t mi_wsize_from_size | ( | size_t | size | ) |
v3: Convert a byte size to a number of sizeof(size_t) words, rounding up.
size must not exceed SIZE_MAX - (sizeof(size_t) - 1) to avoid overflow.
| void * mi_wzalloc_small | ( | size_t | wsize | ) |
v3: As mi_wmalloc_small(), but zero-initialize the allocation.
wsize must not exceed MI_SMALL_WSIZE_MAX.
| void * mi_zalloc_small | ( | size_t | size | ) |
Allocate a zero initialized small object.
| size | The size in bytes, can be at most MI_SMALL_SIZE_MAX. |