docs/environment.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: Environment Options</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('environment.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">Environment Options </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>You can set further options either programmatically (using <a class="el" href="group__options.html#gaf84921c32375e25754dc2ee6a911fa60">mi_option_set()</a>, see <a class="el" href="group__options.html" title="Runtime Options">Runtime Options</a>), or via environment variables:</p>
<ul>
<li><span class="tt">MIMALLOC_SHOW_STATS=1</span>: show statistics when the program terminates.</li>
<li><span class="tt">MIMALLOC_VERBOSE=1</span>: show verbose messages (including statistics).</li>
<li><span class="tt">MIMALLOC_SHOW_ERRORS=1</span>: show error and warning messages.</li>
</ul>
<p>Advanced options:</p>
<ul>
<li><span class="tt">MIMALLOC_ARENA_EAGER_COMMIT=2</span>: turns on eager commit for the large arenas (usually 1GiB) from which mimalloc allocates segments and pages. Set this to 2 (default) to only enable this on overcommit systems (e.g. Linux). Set this to 1 to enable explicitly on other systems as well (like Windows or macOS) which may improve performance (as the whole arena is committed at once). Note that eager commit only increases the commit but not the actual the peak resident set (rss) so it is generally ok to enable this.</li>
<li><span class="tt">MIMALLOC_PURGE_DELAY=N</span>: the delay in <span class="tt">N</span> milli-seconds (by default <span class="tt">1000</span> in v3) after which mimalloc will purge OS pages that are not in use. This signals to the OS that the underlying physical memory can be reused which can reduce memory fragmentation especially in long running (server) programs. Setting <span class="tt">N</span> to <span class="tt">0</span> purges immediately when a page becomes unused which can improve memory usage but also decreases performance. Setting it to <span class="tt">-1</span> disables purging completely.</li>
<li><span class="tt">MIMALLOC_PURGE_DECOMMITS=1</span>: By default "purging" memory means unused memory is decommitted (<span class="tt">MEM_DECOMMIT</span> on Windows, <span class="tt">MADV_DONTNEED</span> (which decresease rss immediately) on <span class="tt">mmap</span> systems). Set this to 0 to instead "reset" unused memory on a purge (<span class="tt">MEM_RESET</span> on Windows, generally <span class="tt">MADV_FREE</span> (which does not decrease rss immediately) on <span class="tt">mmap</span> systems). Mimalloc generally does not "free" OS memory but only "purges" OS memory, in other words, it tries to keep virtual address ranges and decommits within those ranges (to make the underlying physical memory available to other processes).</li>
</ul>
<p>Further options for large workloads and services:</p>
<ul>
<li><span class="tt">MIMALLOC_ALLOW_THP=1</span>: By default always allow transparent huge pages (THP) on Linux systems. On Android only this is by default off. When set to <span class="tt">0</span>, THP is disabled for the process that mimalloc runs in. In mimalloc v3.2+, If enabled, mimalloc also sets the <span class="tt">MIMALLOC_MINIMAL_PURGE_SIZE</span> to 2MiB to avoid potentially breaking up transparent huge pages.</li>
<li><span class="tt">MIMALLOC_USE_NUMA_NODES=N</span>: pretend there are at most <span class="tt">N</span> NUMA nodes. If not set, the actual NUMA nodes are detected at runtime. Setting <span class="tt">N</span> to 1 may avoid problems in some virtual environments. Also, setting it to a lower number than the actual NUMA nodes is fine and will only cause threads to potentially allocate more memory across actual NUMA nodes (but this can happen in any case as NUMA local allocation is always a best effort but not guaranteed).</li>
<li><span class="tt">MIMALLOC_ALLOW_LARGE_OS_PAGES=0</span>: Set to 1 to use large OS pages (usually 2MiB) when available; for some workloads this can significantly improve performance. However, large OS pages cannot be purged or shared with other processes so may lead to increased memory usage in some cases. Use <span class="tt">MIMALLOC_VERBOSE</span> to check if the large OS pages are enabled &ndash; usually one needs to explicitly give permissions for large OS pages (as on <a href="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 <a href="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>). However, sometimes the OS is very slow to reserve contiguous physical memory for large OS pages so use with care on systems that can have fragmented memory (for that reason, we generally recommend to use <span class="tt">MIMALLOC_RESERVE_HUGE_OS_PAGES</span> instead whenever possible).</li>
<li><span class="tt">MIMALLOC_RESERVE_HUGE_OS_PAGES=N</span>: where <span class="tt">N</span> is the number of 1GiB <em>huge</em> OS pages. This reserves the huge pages at startup and sometimes this can give a large (latency) performance improvement on big workloads. Usually it is better to not use <span class="tt">MIMALLOC_ALLOW_LARGE_OS_PAGES=1</span> in combination with this setting. Just like large OS pages, use with care as reserving contiguous physical memory can take a long time when memory is fragmented (but reserving the huge pages is done at startup only once). Note that we usually need to explicitly give permission for huge OS pages (as on <a href="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 <a href="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>)). The huge pages are usually allocated evenly among NUMA nodes. We can use <span class="tt">MIMALLOC_RESERVE_HUGE_OS_PAGES_AT=N</span> where <span class="tt">N</span> is the numa node (starting at 0) to allocate all the huge pages at a specific numa node instead.</li>
</ul>
<p>Use caution when using <span class="tt">fork</span> in combination with either large or huge OS pages: on a fork, the OS uses copy-on-write for all pages in the original process including the huge OS pages. When any memory is now written in that area, the OS will copy the entire 1GiB huge page (or 2MiB large page) which can cause the memory usage to grow in large increments. </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>