GeezerVison

GeezerVison is showing microsoft.github.io — mi-malloc: Using the Library

mi-malloc 3.6/2.5/1.15

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 1.8 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 the test targets in CMakeLists.txt for examples.

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). Debug builds provide the most detail. Elevated processes ignore these variables; see Environment Options.

> 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 Standard Malloc for more info.

Debug Mode

When mimalloc is built using debug mode (-DCMAKE_BUILD_TYPE=Debug), or with -DMI_DEBUG=ON explicitly, various checks are done at runtime to catch development errors.

All objects have padding at the end to detect byte-precise heap block overflows.
Double frees and freeing invalid heap pointers are detected.
Corrupted free lists and some forms of use-after-free are detected.

Generated by 1.18.0