mi-malloc: Using the Library

| mi-malloc 1.8/2.1 |

Loading...
Searching...
No Matches
Using the Library

### Build

The preferred usage is including `<mimalloc.h>`, linking with the shared- or static library, and using the `mi_malloc` API exclusively for allocation. For example,

gcc -o myprogram -lmimalloc myfile.c

mimalloc uses only safe OS calls (`mmap` and `VirtualAlloc`) and can co-exist with other allocators linked to the same program. If you use `cmake`, you can simply use:

find_package(mimalloc 2.1 REQUIRED)

in your `CMakeLists.txt` to find a locally installed mimalloc. Then use either:

target_link_libraries(myapp PUBLIC mimalloc)

to link with the shared (dynamic) library, or:

target_link_libraries(myapp PUBLIC mimalloc-static)

to link with the static library. See `test\CMakeLists.txt` for an example.

### C++

For best performance in C++ programs, it is also recommended to override the global `new` and `delete` operators. For convenience, mimalloc provides `mimalloc-new-delete.h` which does this for you – just include it in a single(!) source file in your project.

In C++, mimalloc also provides the `mi_stl_allocator` struct which implements the `std::allocator` interface. For example:

std::vector<some_struct, mi_stl_allocator<some_struct>> vec;
vec.push_back(some_struct());

### Statistics

You can pass environment variables to print verbose messages (`MIMALLOC_VERBOSE=1`) and statistics (`MIMALLOC_SHOW_STATS=1`) (in the debug version):

> env MIMALLOC_SHOW_STATS=1 ./cfrac 175451865205073170563711388363
175451865205073170563711388363 = 374456281610909315237213 * 468551
subproc 0
blocks peak total current block total#
bin S 4: 75.3 KiB 55.2 MiB 0 32 B 1.8 M ok
bin S 6: 31.0 KiB 180.4 KiB 0 48 B 3.8 K ok
bin S 8: 64 B 64 B 0 64 B 1 ok
bin S 9: 160 B 160 B 0 80 B 2 ok
bin S 17: 1.2 KiB 1.2 KiB 0 320 B 4 ok
bin S 21: 640 B 3.1 KiB 0 640 B 5 ok
bin S 33: 5.0 KiB 5.0 KiB 0 5.0 KiB 1 ok
binned : 84.2 Ki 41.5 Mi 0 ok
huge : 0 0 0 ok
total : 84.2 KiB 41.5 MiB 0
malloc req: 29.7 MiB
pages peak total current block total#
touched : 152.8 KiB 152.8 KiB 152.8 KiB
pages : 8 14 0 ok
abandoned : 1 249 0 ok
reclaima : 0
reclaimf : 249
reabandon : 0
waits : 0
extended : 38
retire : 35
searches : 0.7 avg
arenas peak total current block total#
reserved : 1.0 GiB 1.0 GiB 1.0 GiB
committed : 4.8 MiB 4.8 MiB 4.4 MiB
reset : 0
purged : 385.5 Ki
arenas : 1
rollback : 0
mmaps : 3
commits : 0
resets : 1
purges : 2
guarded : 0
heaps : 1 1 1
process peak total current block total#
threads : 1 1 1
numa nodes: 1
elapsed : 0.553 s
process : user: 0.557 s, system: 0.013 s, faults: 29, peak rss: 2.1 MiB, peak commit: 4.8 MiB

The above model of using the `mi_` prefixed API is not always possible though in existing programs that already use the standard malloc interface, and another option is to override the standard malloc interface completely and redirect all calls to the mimalloc library instead.

See Overriding Malloc for more info.