docs/index.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.18.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>mi-malloc: mi-malloc</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="codefolding.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="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>
<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;3.5/2.5/1.15</span>
   </div>
  </td>
    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <span id="MSearchSelect" class="search-icon"><span class="search-icon-dropdown"></span></span>
          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><div id="MSearchCloseImg" class="close-icon"></div></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.18.0 -->
<script type="text/javascript">
let searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', codefold.init);
</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" class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded',() => { initNavTree('index.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow">
</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">mi-malloc </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This is the API documentation of the <a href="https://github.com/microsoft/mimalloc">mimalloc</a> allocator (pronounced "me-malloc") &ndash; a general purpose allocator with excellent <a href="bench.html">performance</a> characteristics. Initially developed by Daan Leijen for the run-time systems of the <a href="https://github.com/koka-lang/koka">Koka</a> and <a href="https://github.com/leanprover/lean">Lean</a> languages.</p>
<p>It is a drop-in replacement for <span class="tt"><a class="el" href="group__malloc.html" title="The basic allocation interface.">Basic Allocation</a></span> and can be used in other programs without code changes, for example, on Unix you can use it as: </p><div class="fragment"><div class="line">&gt; LD_PRELOAD=/usr/bin/libmimalloc.so  myprogram</div>
</div><!-- fragment --><p>Notable aspects of the design include:</p><ul>
<li><b>small and consistent</b>: the core library is about 10k LOC using simple and consistent data structures. This makes it very suitable to integrate and adapt in other projects. For runtime systems it provides hooks for a monotonic <em>heartbeat</em> and deferred freeing (for bounded worst-case times with reference counting). Partly due to its simplicity, mimalloc has been ported to many systems (Windows, macOS, Linux, WASM, various BSD's, Haiku, MUSL, etc) and has excellent support for dynamic overriding. At the same time, it is an industrial strength allocator that runs (very) large scale distributed services on thousands of machines with excellent worst case latencies.</li>
<li><b>free list sharding</b>: instead of one big free list (per size class) we have many smaller lists per "mimalloc page" which reduces fragmentation and increases locality &ndash; things that are allocated close in time get allocated close in memory. (A mimalloc page contains blocks of one size class and is usually 64KiB on a 64-bit system).</li>
<li><b>free list multi-sharding</b>: the big idea! Not only do we shard the free list per mimalloc page, but for each page we have multiple free lists. In particular, there is one list for thread-local <span class="tt">free</span> operations, and another one for concurrent <span class="tt">free</span> operations. Free-ing from another thread can now be a single CAS without needing sophisticated coordination between threads. Since there will be thousands of separate free lists, contention is naturally distributed over the heap, and the chance of contending on a single location will be low &ndash; this is quite similar to randomized algorithms like skip lists where adding a random oracle removes the need for a more complex algorithm.</li>
<li><b>eager page purging</b>: when a "page" becomes empty (with increased chance due to free list sharding) the memory is marked to the OS as unused (reset or decommitted) reducing (real) memory pressure and fragmentation, especially in long running programs.</li>
<li><b>secure</b>: <em>mimalloc</em> can be built in secure mode, adding guard pages, randomized allocation, encrypted free lists, etc. to protect against various heap vulnerabilities. The performance penalty is usually around 10% on average over our benchmarks.</li>
<li><b>first-class heaps</b>: efficiently create and use multiple heaps to allocate across different regions. A heap can be destroyed at once instead of deallocating each object separately. v3.2+ has true first-class heaps where one can allocate in a heap from any thread. <br  />
</li>
<li><b>bounded</b>: it does not suffer from <em>blowup</em> [1], has bounded worst-case allocation times (<em>wcat</em>) (upto OS primitives), bounded space overhead (~0.2% meta-data, with low internal fragmentation), and has no internal points of contention using only atomic operations.</li>
<li><b>fast</b>: In our benchmarks (see <a class="el" href="bench.html" title="Performance">below</a>), <em>mimalloc</em> outperforms other leading allocators (<em>jemalloc</em>, <em>tcmalloc</em>, <em>Hoard</em>, etc), and often uses less memory. A nice property is that it does consistently well over a wide range of benchmarks. There is also good huge OS page support for larger server programs.</li>
</ul>
<p>There are three maintained versions of mimalloc. All versions are mostly equal except for how the OS memory is handled. New development is mostly on v3, while v1 and v2 are maintained with security and bug fixes.</p>
<ul>
<li><b>v3</b> <b>recommended</b>: simplifies the lock-free design of previous versions, and improves sharing of memory between threads. On certain large workloads this version may use (much) less memory. Also supports true first-class heaps (that can allocate from any thread) and has more efficient heap-walking (for the CPython GC for example). (release tags: <span class="tt">v3.4.x</span>, development branch <span class="tt">dev3</span>).</li>
<li><b>v2</b> <b>stable</b>: Uses thread-local segments to reduce fragmentation. (release tags: <span class="tt">v2.4.x</span>, development branch <span class="tt">dev2</span>)</li>
<li><b>v1</b> <b>legacy</b>: initial design of mimalloc (release tags: <span class="tt">v1.9.x</span>, development branch <span class="tt">dev</span>). Send PR's against this version if possible.</li>
</ul>
<p>You can read more on the design of mimalloc in the <a href="https://www.microsoft.com/en-us/research/publication/mimalloc-free-list-sharding-in-action">technical report</a> which also has detailed benchmark results. To learn more about the internal implementation of mimalloc, see <a href="https://github.com/microsoft/mimalloc/blob/master/include/mimalloc/types.h">include/mimalloc/types.h</a>.</p>
<p>Further information:</p>
<ul>
<li><a class="el" href="build.html" title="Building">Building</a></li>
<li><a class="el" href="using.html" title="Using the Library">Using the Library</a></li>
<li><a class="el" href="environment.html" title="Environment Options">Environment Options</a></li>
<li><a class="el" href="overrides.html" title="Overriding Malloc">Overriding Malloc</a></li>
<li><a class="el" href="modes.html" title="Build Modes">Build Modes</a></li>
<li><a class="el" href="tools.html" title="Tools">Tools</a></li>
<li><a class="el" href="bench.html" title="Performance">Performance</a></li>
</ul>
<p>&#160;</p>
<ul>
<li><a class="el" href="group__malloc.html" title="Basic Allocation">Basic Allocation</a></li>
<li><a class="el" href="group__aligned.html" title="Aligned Allocation">Aligned Allocation</a></li>
<li><a class="el" href="group__typed.html" title="Typed Macros">Typed Macros</a></li>
<li><a class="el" href="group__constantsize.html" title="Constant size allocation">Constant size allocation</a></li>
<li><a class="el" href="group__zeroinit.html" title="Zero initialized re-allocation">Zero initialized re-allocation</a></li>
<li><a class="el" href="group__heap.html" title="Heaps">Heaps</a></li>
<li><a class="el" href="group__analysis.html" title="Heap Introspection">Heap Introspection</a></li>
<li><a class="el" href="group__arenas.html" title="Arenas">Arenas</a></li>
<li><a class="el" href="group__subproc.html" title="Subprocesses">Subprocesses</a></li>
<li><a class="el" href="group__extended.html" title="Extended Functions">Extended Functions</a></li>
<li><a class="el" href="group__stats.html" title="Statistics">Statistics</a></li>
<li><a class="el" href="group__options.html" title="Runtime Options">Runtime Options</a></li>
<li><a class="el" href="group__theap.html" title="Thread-local heaps">Thread-local heaps</a></li>
<li><a class="el" href="group__posix.html" title="Posix">Posix</a></li>
<li><a class="el" href="group__cpp.html" title="C++ wrappers">C++ wrappers</a> </li>
</ul>
</div></div><!-- PageDoc -->
<a href="doxygen_crawl.html"></a>
</div><!-- contents -->
</div><!-- doc-content -->
</div><!-- container -->
<!-- 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.18.0 </li>
  </ul>
</div>
</body>
</html>