docs/overrides.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.11.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>mi-malloc: Overriding Malloc</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  $(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="mimalloc-doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectlogo"><img alt="Logo" src="mimalloc-logo.svg"/></td>
  <td id="projectalign">
   <div id="projectname">mi-malloc<span id="projectnumber">&#160;v1.9,  v2.2,  v3.2</span>
   </div>
  </td>
    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.11.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){initNavTree('overrides.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Overriding Malloc</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Overriding the standard <code>malloc</code> (and <code>new</code>) can be done either <em>dynamically</em> or <em>statically</em>.</p>
<h2>Dynamic override</h2>
<p>This is the recommended way to override the standard malloc interface.</p>
<h3>Dynamic Override on Linux, BSD</h3>
<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><div class="fragment"><div class="line">&gt; 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><div class="fragment"><div class="line">&gt; 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><div class="fragment"><div class="line">&gt; 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><div class="fragment"><div class="line">&gt; 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 <a href="https://stackoverflow.com/questions/43941322/dyld-insert-libraries-ignored-when-calling-application-through-bash">shell</a>.</p>
<h3>Dynamic Override on Windows</h3>
<p><span id="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>
<ol type="1">
<li>Use the C-runtime library as a DLL (using the <code>/MD</code> or <code>/MDd</code> switch).</li>
<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><a class="el" href="group__extended.html#gae9ddddcf14a58d0224ef3c8778e5b057" title="Return the mimalloc version.">mi_version()</a></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 &lt;exe&gt;</code> to check this if needed.</li>
</ol>
<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 <a href="https://github.com/microsoft/mimalloc/blob/main/include/mimalloc-new-delet.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>
<h2>Static override</h2>
<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><div class="fragment"><div class="line">&gt; 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 <a href="https://github.com/microsoft/mimalloc/blob/main/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>
<h2>List of Overrides:</h2>
<p>The specific functions that get redirected to the <em>mimalloc</em> library are:</p>
<div class="fragment"><div class="line"><span class="comment">// C</span></div>
<div class="line"><span class="keywordtype">void</span>*  malloc(<span class="keywordtype">size_t</span> size);</div>
<div class="line"><span class="keywordtype">void</span>*  calloc(<span class="keywordtype">size_t</span> size, <span class="keywordtype">size_t</span> n);</div>
<div class="line"><span class="keywordtype">void</span>*  realloc(<span class="keywordtype">void</span>* p, <span class="keywordtype">size_t</span> newsize);</div>
<div class="line"><span class="keywordtype">void</span>   free(<span class="keywordtype">void</span>* p);</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">void</span>*  aligned_alloc(<span class="keywordtype">size_t</span> alignment, <span class="keywordtype">size_t</span> size);</div>
<div class="line"><span class="keywordtype">char</span>*  strdup(<span class="keyword">const</span> <span class="keywordtype">char</span>* s);</div>
<div class="line"><span class="keywordtype">char</span>*  strndup(<span class="keyword">const</span> <span class="keywordtype">char</span>* s, <span class="keywordtype">size_t</span> n);</div>
<div class="line"><span class="keywordtype">char</span>*  realpath(<span class="keyword">const</span> <span class="keywordtype">char</span>* fname, <span class="keywordtype">char</span>* resolved_name);</div>
<div class="line"> </div>
<div class="line"> </div>
<div class="line"><span class="comment">// C++</span></div>
<div class="line"><span class="keywordtype">void</span>   <span class="keyword">operator</span> <span class="keyword">delete</span>(<span class="keywordtype">void</span>* p);</div>
<div class="line"><span class="keywordtype">void</span>   <span class="keyword">operator</span> <span class="keyword">delete</span>[](<span class="keywordtype">void</span>* p);</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">void</span>*  <span class="keyword">operator</span> <span class="keyword">new</span>(std::size_t n) <span class="keyword">noexcept</span>(<span class="keyword">false</span>);</div>
<div class="line"><span class="keywordtype">void</span>*  <span class="keyword">operator</span> <span class="keyword">new</span>[](std::size_t n) <span class="keyword">noexcept</span>(<span class="keyword">false</span>);</div>
<div class="line"><span class="keywordtype">void</span>*  <span class="keyword">operator</span> <span class="keyword">new</span>( std::size_t n, std::align_val_t align) <span class="keyword">noexcept</span>(<span class="keyword">false</span>);</div>
<div class="line"><span class="keywordtype">void</span>*  <span class="keyword">operator</span> <span class="keyword">new</span>[]( std::size_t n, std::align_val_t align) <span class="keyword">noexcept</span>(<span class="keyword">false</span>);</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">void</span>*  <span class="keyword">operator</span> <span class="keyword">new</span>  ( std::size_t count, <span class="keyword">const</span> std::nothrow_t&amp; tag);</div>
<div class="line"><span class="keywordtype">void</span>*  <span class="keyword">operator</span> <span class="keyword">new</span>[]( std::size_t count, <span class="keyword">const</span> std::nothrow_t&amp; tag);</div>
<div class="line"><span class="keywordtype">void</span>*  <span class="keyword">operator</span> <span class="keyword">new</span>  ( std::size_t count, std::align_val_t al, <span class="keyword">const</span> std::nothrow_t&amp;);</div>
<div class="line"><span class="keywordtype">void</span>*  <span class="keyword">operator</span> <span class="keyword">new</span>[]( std::size_t count, std::align_val_t al, <span class="keyword">const</span> std::nothrow_t&amp;);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Posix</span></div>
<div class="line"><span class="keywordtype">int</span>    posix_memalign(<span class="keywordtype">void</span>** p, <span class="keywordtype">size_t</span> alignment, <span class="keywordtype">size_t</span> size);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Linux</span></div>
<div class="line"><span class="keywordtype">void</span>*  memalign(<span class="keywordtype">size_t</span> alignment, <span class="keywordtype">size_t</span> size);</div>
<div class="line"><span class="keywordtype">void</span>*  valloc(<span class="keywordtype">size_t</span> size);</div>
<div class="line"><span class="keywordtype">void</span>*  pvalloc(<span class="keywordtype">size_t</span> size);</div>
<div class="line"><span class="keywordtype">size_t</span> malloc_usable_size(<span class="keywordtype">void</span> *p);</div>
<div class="line"><span class="keywordtype">void</span>*  reallocf(<span class="keywordtype">void</span>* p, <span class="keywordtype">size_t</span> newsize);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// macOS</span></div>
<div class="line"><span class="keywordtype">void</span>   vfree(<span class="keywordtype">void</span>* p);</div>
<div class="line"><span class="keywordtype">size_t</span> malloc_size(<span class="keyword">const</span> <span class="keywordtype">void</span>* p);</div>
<div class="line"><span class="keywordtype">size_t</span> malloc_good_size(<span class="keywordtype">size_t</span> size);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// BSD</span></div>
<div class="line"><span class="keywordtype">void</span>*  reallocarray( <span class="keywordtype">void</span>* p, <span class="keywordtype">size_t</span> count, <span class="keywordtype">size_t</span> size );</div>
<div class="line"><span class="keywordtype">void</span>*  reallocf(<span class="keywordtype">void</span>* p, <span class="keywordtype">size_t</span> newsize);</div>
<div class="line"><span class="keywordtype">void</span>   cfree(<span class="keywordtype">void</span>* p);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// NetBSD</span></div>
<div class="line"><span class="keywordtype">int</span>    reallocarr(<span class="keywordtype">void</span>* p, <span class="keywordtype">size_t</span> count, <span class="keywordtype">size_t</span> size);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Windows</span></div>
<div class="line"><span class="keywordtype">void</span>*  _expand(<span class="keywordtype">void</span>* p, <span class="keywordtype">size_t</span> newsize);</div>
<div class="line"><span class="keywordtype">size_t</span> _msize(<span class="keywordtype">void</span>* p);</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">void</span>*  _malloc_dbg(<span class="keywordtype">size_t</span> size, <span class="keywordtype">int</span> block_type, <span class="keyword">const</span> <span class="keywordtype">char</span>* fname, <span class="keywordtype">int</span> line);</div>
<div class="line"><span class="keywordtype">void</span>*  _realloc_dbg(<span class="keywordtype">void</span>* p, <span class="keywordtype">size_t</span> newsize, <span class="keywordtype">int</span> block_type, <span class="keyword">const</span> <span class="keywordtype">char</span>* fname, <span class="keywordtype">int</span> line);</div>
<div class="line"><span class="keywordtype">void</span>*  _calloc_dbg(<span class="keywordtype">size_t</span> count, <span class="keywordtype">size_t</span> size, <span class="keywordtype">int</span> block_type, <span class="keyword">const</span> <span class="keywordtype">char</span>* fname, <span class="keywordtype">int</span> line);</div>
<div class="line"><span class="keywordtype">void</span>*  _expand_dbg(<span class="keywordtype">void</span>* p, <span class="keywordtype">size_t</span> size, <span class="keywordtype">int</span> block_type, <span class="keyword">const</span> <span class="keywordtype">char</span>* fname, <span class="keywordtype">int</span> line);</div>
<div class="line"><span class="keywordtype">size_t</span> _msize_dbg(<span class="keywordtype">void</span>* p, <span class="keywordtype">int</span> block_type);</div>
<div class="line"><span class="keywordtype">void</span>   _free_dbg(<span class="keywordtype">void</span>* p, <span class="keywordtype">int</span> block_type);</div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.11.0 </li>
  </ul>
</div>
</body>
</html>