<divclass="textblock"><p>Overriding the standard <code>malloc</code> (and <code>new</code>) can be done either <em>dynamically</em> or <em>statically</em>.</p>
<p>On these ELF-based systems we preload the mimalloc shared library so all calls to the standard <code>malloc</code> interface are resolved to the <em>mimalloc</em> library. </p><divclass="fragment"><divclass="line">> env LD_PRELOAD=/usr/lib/libmimalloc.so myprogram</div>
</div><!-- fragment --><p>You can set extra environment variables to check that mimalloc is running, like: </p><divclass="fragment"><divclass="line">> env MIMALLOC_VERBOSE=1 LD_PRELOAD=/usr/lib/libmimalloc.so myprogram</div>
</div><!-- fragment --><p> or run with the debug version to get detailed statistics: </p><divclass="fragment"><divclass="line">> env MIMALLOC_SHOW_STATS=1 LD_PRELOAD=/usr/lib/libmimalloc-debug.so myprogram</div>
</div><!-- fragment --><h3>Dynamic Override on MacOS</h3>
<p>On macOS we can also preload the mimalloc shared library so all calls to the standard <code>malloc</code> interface are resolved to the <em>mimalloc</em> library. </p><divclass="fragment"><divclass="line">> env DYLD_INSERT_LIBRARIES=/usr/lib/libmimalloc.dylib myprogram</div>
</div><!-- fragment --><p>Note that certain security restrictions may apply when doing this from the <ahref="https://stackoverflow.com/questions/43941322/dyld-insert-libraries-ignored-when-calling-application-through-bash">shell</a>.</p>
<p><spanid="override_on_windows">Dynamically overriding on mimalloc on Windows</span> is robust and has the particular advantage to be able to redirect all malloc/free calls that go through the (dynamic) C runtime allocator, including those from other DLL's or libraries. As it intercepts all allocation calls on a low level, it can be used reliably on large programs that include other 3rd party components. There are four requirements to make the overriding work well:</p>
<li>Link your program explicitly with the <code>mimalloc.lib</code> export library for the <code>mimalloc.dll</code>. (which must be compiled with <code>-DMI_OVERRIDE=ON</code>, which is the default though). To ensure the <code>mimalloc.dll</code> is actually loaded at run-time it is easiest to insert some call to the mimalloc API in the <code>main</code> function, like <code>mi_version()</code> (or use the <code>/include:mi_version</code> switch on the linker command, or similarly, <code>#pragma comment(linker, "/include:mi_version")</code> in some source file). See the <code>mimalloc-test-override</code> project for an example on how to use this.</li>
<li>The <code>mimalloc-redirect.dll</code> must be put in the same directory as the main <code>mimalloc.dll</code> 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 <code>mimalloc.dll</code>).</li>
<li>Ensure the <code>mimalloc.dll</code> comes as early as possible in the import list of the final executable (so it can intercept all potential allocations). You can use <code>minject -l <exe></code> to check this if needed.</li>
<p>For best performance on Windows with C++, it is also recommended to also override the <code>new</code>/<code>delete</code> operations (by including <ahref="include/mimalloc-new-delete.h"><code>mimalloc-new-delete.h</code></a> a single(!) source file in your project).</p>
<p>The environment variable <code>MIMALLOC_DISABLE_REDIRECT=1</code> can be used to disable dynamic overriding at run-time. Use <code>MIMALLOC_VERBOSE=1</code> to check if mimalloc was successfully redirected.</p>
<p>For different platforms than x64, you may need a specific [redirection dll](bin). Furthermore, we cannot always re-link an executable or ensure <code>mimalloc.dll</code> comes first in the import table. In such cases the [<code>minject</code>](bin) tool can be used to patch the executable's import tables.</p>
<p>On Unix-like systems, you can also statically link with <em>mimalloc</em> to override the standard malloc interface. The recommended way is to link the final program with the <em>mimalloc</em> single object file (<code>mimalloc.o</code>). We use an object file instead of a library file as linkers give preference to that over archives to resolve symbols. To ensure that the standard malloc interface resolves to the <em>mimalloc</em> library, link it as the first object file. For example: </p><divclass="fragment"><divclass="line">> gcc -o myprogram mimalloc.o myfile1.c ...</div>
</div><!-- fragment --><p>Another way to override statically that works on all platforms, is to link statically to mimalloc (as shown in the introduction) and include a header file in each source file that re-defines <code>malloc</code> etc. to <code>mi_malloc</code>. This is provided by <ahref="https://github.com/microsoft/mimalloc/blob/master/include/mimalloc-override.h"><code>mimalloc-override.h</code></a>. This only works reliably though if all sources are under your control or otherwise mixing of pointers from different heaps may occur!</p>
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.13.1 </li>
