libmimalloc-sys2 0.1.53

Sys crate wrapping the mimalloc allocator
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

<!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: Tools</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;1.8/2.1</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('tools.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">Tools</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Generally, we recommend using the standard allocator with memory tracking tools, but mimalloc can also be build to support the <a href="https://github.com/google/sanitizers/wiki/AddressSanitizer">address sanitizer</a> or the excellent <a href="https://valgrind.org/">Valgrind</a> tool. Moreover, it can be build to support Windows event tracing (<a href="https://learn.microsoft.com/en-us/windows-hardware/test/wpt/event-tracing-for-windows">ETW</a>). This has a small performance overhead but does allow detecting memory leaks and byte-precise buffer overflows directly on final executables. See also the <code>test/test-wrong.c</code> file to test with various tools.</p>
<h2>Valgrind</h2>
<p>To build with <a href="https://valgrind.org/">valgrind</a> support, use the <code>MI_TRACK_VALGRIND=ON</code> cmake option:</p>
<div class="fragment"><div class="line">&gt; cmake ../.. -DMI_TRACK_VALGRIND=ON</div>
</div><!-- fragment --><p>This can also be combined with secure mode or debug mode. You can then run your programs directly under valgrind:</p>
<div class="fragment"><div class="line">&gt; valgrind &lt;myprogram&gt;</div>
</div><!-- fragment --><p>If you rely on overriding <code>malloc</code>/<code>free</code> by mimalloc (instead of using the <code>mi_malloc</code>/<code>mi_free</code> API directly), you also need to tell <code>valgrind</code> to not intercept those calls itself, and use:</p>
<div class="fragment"><div class="line">&gt; MIMALLOC_SHOW_STATS=1 valgrind  --soname-synonyms=somalloc=*mimalloc* -- &lt;myprogram&gt;</div>
</div><!-- fragment --><p>By setting the <code>MIMALLOC_SHOW_STATS</code> environment variable you can check that mimalloc is indeed used and not the standard allocator. Even though the <a href="https://valgrind.org/docs/manual/manual-core.html#opt.soname-synonyms">Valgrind option</a> is called <code>--soname-synonyms</code>, this also works when overriding with a static library or object file. To dynamically override mimalloc using <code>LD_PRELOAD</code> together with <code>valgrind</code>, use:</p>
<div class="fragment"><div class="line">&gt; valgrind --trace-children=yes --soname-synonyms=somalloc=*mimalloc* /usr/bin/env LD_PRELOAD=/usr/lib/libmimalloc.so -- &lt;myprogram&gt;</div>
</div><!-- fragment --><p>See also the <code>test/test-wrong.c</code> file to test with <code>valgrind</code>.</p>
<p>Valgrind support is in its initial development &ndash; please report any issues.</p>
<h2>ASAN</h2>
<p>To build with the address sanitizer, use the <code>-DMI_TRACK_ASAN=ON</code> cmake option:</p>
<div class="fragment"><div class="line">&gt; cmake ../.. -DMI_TRACK_ASAN=ON</div>
</div><!-- fragment --><p>This can also be combined with secure mode or debug mode. You can then run your programs as:'</p>
<div class="fragment"><div class="line">&gt; ASAN_OPTIONS=verbosity=1 &lt;myprogram&gt;</div>
</div><!-- fragment --><p>When you link a program with an address sanitizer build of mimalloc, you should generally compile that program too with the address sanitizer enabled. For example, assuming you build mimalloc in <code>out/debug</code>:</p>
<div class="fragment"><div class="line">clang -g -o test-wrong -Iinclude test/test-wrong.c out/debug/libmimalloc-asan-debug.a -lpthread -fsanitize=address -fsanitize-recover=address</div>
</div><!-- fragment --><p>Since the address sanitizer redirects the standard allocation functions, on some platforms (macOSX for example) it is required to compile mimalloc with <code>-DMI_OVERRIDE=OFF</code>. Address sanitizer support is in its initial development &ndash; please report any issues.</p>
<h2>ETW</h2>
<p>Event tracing for Windows (<a href="https://learn.microsoft.com/en-us/windows-hardware/test/wpt/event-tracing-for-windows">ETW</a>) provides a high performance way to capture all allocations though mimalloc and analyze them later. To build with ETW support, use the <code>-DMI_TRACK_ETW=ON</code> cmake option.</p>
<p>You can then capture an allocation trace using the Windows performance recorder (WPR), using the <code>src/prim/windows/etw-mimalloc.wprp</code> profile. In an admin prompt, you can use: </p><div class="fragment"><div class="line">&gt; wpr -start src\prim\windows\etw-mimalloc.wprp -filemode</div>
<div class="line">&gt; &lt;my_mimalloc_program&gt;</div>
<div class="line">&gt; wpr -stop &lt;my_mimalloc_program&gt;.etl</div>
</div><!-- fragment --><p> and then open <code>&lt;my_mimalloc_program&gt;.etl</code> in the Windows Performance Analyzer (WPA), or use a tool like <a href="https://github.com/xinglonghe/TraceControl">TraceControl</a> that is specialized for analyzing mimalloc traces. </p>
</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>