<!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: Getting the Best Performance</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"> 3.6/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('tuning.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">Getting the Best Performance </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Consider the following build options (<b>v3</b>):</p>
<ul>
<li><span class="tt">-DMI_OPT_ARCH=ON</span> (the default on arm64) enables architecture-specific optimizations: <span class="tt">-march=haswell -mavx2</span> on x64, <span class="tt">-march=armv8.1-a</span> on arm64, and <span class="tt">-march=rv64gcb_zacas</span> on RISC-V. These improve bit operations and atomic operations, but unsupported hardware or emulators may fail with an illegal instruction. Apple arm64 defaults to <span class="tt">-march=armv8.3-a</span>, supported on M1 and later, for efficient load-acquire instructions. RISC-V hardware supporting <span class="tt">zalasr</span> can use <span class="tt">-DMI_OPT_ARCH=rv64gcb_zacas_zalasr</span>.</li>
<li><span class="tt">-DMI_ALLOW_THP=OFF</span> can significantly reduce resident memory usage for some programs.</li>
<li><span class="tt">-DMI_ALLOW_THP=FULL</span> can significantly improve performance for some programs, but still respects an OS THP setting of <span class="tt">[never]</span>.</li>
<li><span class="tt">-DMI_FREE_IS_CHECKED=ON</span> checks pointers passed to <a class="el" href="group__malloc.html#gaf2c7b89c327d1f60f59e68b9ea644d95" title="Free previously allocated memory.">mi_free()</a>, at a small performance cost. This can be useful when overriding malloc/free process-wide. Alternatively, <a class="el" href="group__malloc.html#ga705dc7a64bffacfeeb0141501a5c35d7" title="Checked free: just as mi_free() but always checks if the pointer p belongs to our heap.">mi_cfree()</a> always checks pointer validity. Pointer checking is always enabled at secure level <span class="tt">CHECKED</span> and higher.</li>
</ul>
<p>In source code:</p>
<ul>
<li>Use <a class="el" href="group__malloc.html#gae6e38c4403247a7b40d80419e093bfb8" title="Allocate zero-initialized size bytes.">mi_zalloc()</a> for zero-initialized allocations.</li>
<li>Use typed macros such as <a class="el" href="group__typed.html#ga0619a62c5fd886f1016030abe91f0557" title="Allocate a block of type tp.">mi_malloc_tp()</a>: they are safer and use <a class="el" href="group__constantsize.html#ga9cd44d925d34f7180922e12bbf594571" title="v3: Allocate a constant size object.">mi_malloc_csize()</a> internally.</li>
<li>Use <a class="el" href="group__constantsize.html#ga9cd44d925d34f7180922e12bbf594571" title="v3: Allocate a constant size object.">mi_malloc_csize()</a> and <a class="el" href="group__constantsize.html#ga7a421e302074e598527c3eb052a6a3c5" title="v3: Free a pointer with a known constant size.">mi_free_csize()</a> when the size is a compile-time constant. These inline and select <a class="el" href="group__extended.html#ga7f050bc6b897da82692174f5fce59cde" title="Allocate a small object.">mi_malloc_small()</a> or <a class="el" href="group__extended.html#ga2a8469764c38dcaf878f36e5f50e3610" title="v3: Can be used to free an object that was allocated with mi_malloc_small() or any allocation with a ...">mi_free_small()</a> where possible. The C++ <span class="tt">mimalloc-new-delete.h</span> sized overrides use these too. Use <a class="el" href="group__constantsize.html#ga38a93d373a9dc8edc8bca83edb6af5c5" title="v3: Free a non-null pointer with a known constant size.">mi_free_csize_nonnull()</a> when the pointer is known to be non-NULL.</li>
<li>Use <a class="el" href="group__extended.html#ga7f050bc6b897da82692174f5fce59cde" title="Allocate a small object.">mi_malloc_small()</a> when the requested size is at most <span class="tt"><a class="el" href="group__extended.html#ga1ea64283508718d9d645c38efc2f4305" title="Maximum size in bytes allowed for small allocations in mi_malloc_small, mi_zalloc_small,...">MI_SMALL_SIZE_MAX</a></span> (128 machine words, or 1 KiB on a 64-bit system). Use <a class="el" href="group__extended.html#ga2a8469764c38dcaf878f36e5f50e3610" title="v3: Can be used to free an object that was allocated with mi_malloc_small() or any allocation with a ...">mi_free_small()</a> for pointers returned by <a class="el" href="group__extended.html#ga7f050bc6b897da82692174f5fce59cde" title="Allocate a small object.">mi_malloc_small()</a>, and <a class="el" href="group__extended.html#ga22890f54e5be433837069c8e97fdf379" title="v3: Can be used to free an object that was allocated with mi_malloc_small() or any allocation with a ...">mi_free_small_nonnull()</a> when the pointer is known to be non-NULL.</li>
</ul>
<p>For runtimes and compilers, such as Koka, Lean, or Rust, prefer the constant-size or small-allocation APIs when sizes are known. If a runtime already carries thread-local state, it can cache <a class="el" href="group__theap.html#ga78afbb07c1e0cd333c7539cf7403dfd5" title="Get the default theap that is used for mi_malloc() et al.">mi_theap_get_default()</a> for each thread and pass that thread's theap directly to <a class="el" href="group__theap.html#gac7308e029c59e6675dd5ab5ec54f304a" title="Allocate in a specific theap.">mi_theap_malloc()</a> or <a class="el" href="group__theap.html#ga1fc65302a212daaecb21abda96ff247c" title="Allocate a small object in a specific theap.">mi_theap_malloc_small()</a>. This avoids repeatedly looking up the thread-local pointer and skips a NULL theap check. The benefit depends on the OS implementation of thread-local storage. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</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>