<divclass="textblock"><p>The preferred usage is including <code><mimalloc.h></code>, linking with the shared- or static library, and using the <code>mi_malloc</code> API exclusively for allocation. For example, </p><divclass="fragment"><divclass="line">gcc -o myprogram -lmimalloc myfile.c</div></div><!-- fragment --><p>mimalloc uses only safe OS calls (<code>mmap</code> and <code>VirtualAlloc</code>) and can co-exist with other allocators linked to the same program. If you use <code>cmake</code>, you can simply use: </p><divclass="fragment"><divclass="line">find_package(mimalloc 1.0 REQUIRED)</div></div><!-- fragment --><p> in your <code>CMakeLists.txt</code> to find a locally installed mimalloc. Then use either: </p><divclass="fragment"><divclass="line">target_link_libraries(myapp PUBLIC mimalloc)</div></div><!-- fragment --><p> to link with the shared (dynamic) library, or: </p><divclass="fragment"><divclass="line">target_link_libraries(myapp PUBLIC mimalloc-<spanclass="keyword">static</span>)</div></div><!-- fragment --><p> to link with the static library. See <code>test\CMakeLists.txt</code> for an example.</p>
<p>You can pass environment variables to print verbose messages (<code>MIMALLOC_VERBOSE=1</code>) and statistics (<code>MIMALLOC_SHOW_STATS=1</code>) (in the debug version): </p><divclass="fragment"><divclass="line">> env MIMALLOC_SHOW_STATS=1 ./cfrac 175451865205073170563711388363</div><divclass="line"></div><divclass="line">175451865205073170563711388363 = 374456281610909315237213 * 468551</div><divclass="line"></div><divclass="line">heap stats: peak total freed unit</div><divclass="line">normal 2: 16.4 kb 17.5 mb 17.5 mb 16 b ok</div><divclass="line">normal 3: 16.3 kb 15.2 mb 15.2 mb 24 b ok</div><divclass="line">normal 4: 64 b 4.6 kb 4.6 kb 32 b ok</div><divclass="line">normal 5: 80 b 118.4 kb 118.4 kb 40 b ok</div><divclass="line">normal 6: 48 b 48 b 48 b 48 b ok</div><divclass="line">normal 17: 960 b 960 b 960 b 320 b ok</div><divclass="line"></div><divclass="line">heap stats: peak total freed unit</div><divclass="line"> normal: 33.9 kb 32.8 mb 32.8 mb 1 b ok</div><divclass="line"> huge: 0 b 0 b 0 b 1 b ok</div><divclass="line"> total: 33.9 kb 32.8 mb 32.8 mb 1 b ok</div><divclass="line">malloc requested: 32.8 mb</div><divclass="line"></div><divclass="line"> committed: 58.2 kb 58.2 kb 58.2 kb 1 b ok</div><divclass="line"> reserved: 2.0 mb 2.0 mb 2.0 mb 1 b ok</div><divclass="line"> reset: 0 b 0 b 0 b 1 b ok</div><divclass="line"> segments: 1 1 1</div><divclass="line">-abandoned: 0</div><divclass="line"> pages: 6 6 6</div><divclass="line">-abandoned: 0</div><divclass="line"> mmaps: 3</div><divclass="line"> mmap fast: 0</div><divclass="line"> mmap slow: 1</div><divclass="line"> threads: 0</div><divclass="line"> elapsed: 2.022s</div><divclass="line"> process: user: 1.781s, system: 0.016s, faults: 756, reclaims: 0, rss: 2.7 mb</div></div><!-- fragment --><p>The above model of using the <code>mi_</code> 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 <em>mimalloc</em> library instead.</p>
<p>See <aclass="el"href="overrides.html">Overriding Malloc</a> for more info.</p>
<h2>Environment Options</h2>
<p>You can set further options either programmatically (using <ahref="https://microsoft.github.io/mimalloc/group__options.html"><code>mi_option_set</code></a>), or via environment variables.</p>
<ul>
<li><code>MIMALLOC_SHOW_STATS=1</code>: show statistics when the program terminates.</li>
<li><code>MIMALLOC_VERBOSE=1</code>: show verbose messages.</li>
<li><code>MIMALLOC_SHOW_ERRORS=1</code>: show error and warning messages.</li>
<li><code>MIMALLOC_LARGE_OS_PAGES=1</code>: use large OS pages when available; for some workloads this can significantly improve performance. Use <code>MIMALLOC_VERBOSE</code> to check if the large OS pages are enabled – usually one needs to explicitly allow large OS pages (as on <ahref="https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-the-lock-pages-in-memory-option-windows?view=sql-server-2017">Windows</a> and <ahref="https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/5/html/tuning_and_optimizing_red_hat_enterprise_linux_for_oracle_9i_and_10g_databases/sect-oracle_9i_and_10g_tuning_guide-large_memory_optimization_big_pages_and_huge_pages-configuring_huge_pages_in_red_hat_enterprise_linux_4_or_5">Linux</a>).</li>
<li><code>MIMALLOC_EAGER_REGION_COMMIT=1</code>: on Windows, commit large (256MiB) regions eagerly. On Windows, these regions show in the working set even though usually just a small part is committed to physical memory. This is why it turned off by default on Windows as it looks not good in the task manager. However, in reality it is always better to turn it on as it improves performance and has no other drawbacks. </li>
