Overriding the standard Basic Allocation (and new) can be done either dynamically or statically.
Static override
On Unix-like systems, link the final program with the single object file mimalloc.o to override the standard malloc interface. Link it as the first object so that its definitions take precedence over library archives:
> gcc -o myprogram mimalloc.o myfile1.c ...
Another approach, available on all platforms, is to link statically and include mimalloc-override.h in each source file to redefine Basic Allocation and related functions. This is reliable only when all sources are under your control; otherwise pointers from different heaps may be mixed.
On Windows, static overriding requires the static CRT release runtime (/MT) and the mimalloc(-debug).obj object, linked before the CRT library. The debug CRT (/MTd) is not supported. Static overrides cover the Basic Allocation family, _aligned_*, _expand, _msize, _strdup, and _wcsdup. Other CRT functions returning allocated memory, including _dupenv_s, _getcwd(NULL,...), _fullpath(NULL,...), and _tempnam, still use the CRT heap; their results cannot be freed with the overridden free. Use dynamic overriding or the mi_ equivalents, such as mi_dupenv_s(), where available.
Dynamic override
This is the recommended way to override the standard malloc interface.
Dynamic Override on Linux, BSD
On these ELF-based systems we preload the mimalloc shared library so all calls to the standard Basic Allocation interface are resolved to the mimalloc library.
> env LD_PRELOAD=/usr/lib/libmimalloc.so myprogram
You can set extra environment variables to check that mimalloc is running, like:
> env MIMALLOC_VERBOSE=1 LD_PRELOAD=/usr/lib/libmimalloc.so myprogram
or run with the debug version to get detailed statistics:
> env MIMALLOC_SHOW_STATS=1 LD_PRELOAD=/usr/lib/libmimalloc-debug.so myprogram
Dynamic Override on MacOS
On macOS we can also preload the mimalloc shared library so all calls to the standard Basic Allocation interface are resolved to the mimalloc library.
> env DYLD_INSERT_LIBRARIES=/usr/lib/libmimalloc.dylib myprogram
Note that certain security restrictions may apply when doing this from the shell.
Dynamic Override on Windows
We use a separate redirection DLL to redirect malloc/free calls that go through the dynamic C runtime allocator, including calls from other DLLs and libraries. This low-level interception can be used in large programs containing third-party components. There are four requirements to make the overriding work well:
- Use the C-runtime library as a DLL (using the /MD or /MDd switch).
- Link your program explicitly with the mimalloc.dll.lib export library for the mimalloc.dll. (which must be compiled with -DMI_OVERRIDE=ON, which is the default though). To ensure the mimalloc.dll is actually loaded at run-time it is easiest to insert some call to the mimalloc API in the main function, like mi_version() (or use the /include:mi_version switch on the linker command, or similarly, #pragma comment(linker, "/include:mi_version") in some source file). See the mimalloc-test-override project for an example on how to use this.
- The mimalloc-redirect.dll must be put in the same directory as the main mimalloc.dll at runtime (as it is a dependency of that DLL). The redirection DLL ensures that all calls to the C runtime malloc API get redirected to mimalloc functions (which reside in mimalloc.dll).
- Ensure the mimalloc.dll comes as early as possible in the import list of the final executable (so it can intercept all potential allocations). You can use minject -l <exe> to check this if needed.
For best performance on Windows with C++, it is also recommended to also override the new/delete operations (by including mimalloc-new-delete.h a single(!) source file in your project).
The environment variable MIMALLOC_DISABLE_REDIRECT=1 can be used to disable dynamic overriding at run-time. Use MIMALLOC_VERBOSE=1 to check if mimalloc was successfully redirected.
For different platforms than x64, you may need a specific redirection DLL. Furthermore, we cannot always re-link an executable or ensure mimalloc.dll comes first in the import table. In such cases the minject tool can be used to patch the executable's import tables.
List of Overrides:
The specific functions that get redirected to the mimalloc library are:
void* malloc(size_t size);
void* calloc(size_t size, size_t n);
void* realloc(void* p, size_t newsize);
void free(void* p);
void* aligned_alloc(size_t alignment, size_t size);
char* strdup(const char* s);
char* strndup(const char* s, size_t n);
char* realpath(const char* fname, char* resolved_name);
void free_sized(void* p, size_t size);
void free_aligned_sized(void* p, size_t alignment, size_t size);
void operator delete(void* p);
void operator delete[](void* p);
void* operator new(std::size_t n) noexcept(false);
void* operator new[](std::size_t n) noexcept(false);
void* operator new( std::size_t n, std::align_val_t align) noexcept(false);
void* operator new[]( std::size_t n, std::align_val_t align) noexcept(false);
void* operator new ( std::size_t count, const std::nothrow_t& tag);
void* operator new[]( std::size_t count, const std::nothrow_t& tag);
void* operator new ( std::size_t count, std::align_val_t al, const std::nothrow_t&);
void* operator new[]( std::size_t count, std::align_val_t al, const std::nothrow_t&);
int posix_memalign(void** p, size_t alignment, size_t size);
void* memalign(size_t alignment, size_t size);
void* valloc(size_t size);
void* pvalloc(size_t size);
size_t malloc_usable_size(void *p);
void* reallocf(void* p, size_t newsize);
void vfree(void* p);
size_t malloc_size(const void* p);
size_t malloc_good_size(size_t size);
void* reallocarray( void* p, size_t count, size_t size );
void* reallocf(void* p, size_t newsize);
void cfree(void* p);
int reallocarr(void* p, size_t count, size_t size);
void* _expand(void* p, size_t newsize);
size_t _msize(void* p);
void* _malloc_dbg(size_t size, int block_type, const char* fname, int line);
void* _realloc_dbg(void* p, size_t newsize, int block_type, const char* fname, int line);
void* _calloc_dbg(size_t count, size_t size, int block_type, const char* fname, int line);
void* _expand_dbg(void* p, size_t size, int block_type, const char* fname, int line);
size_t _msize_dbg(void* p, int block_type);
void _free_dbg(void* p, int block_type);