xref: /redis-3.2.3/deps/jemalloc/doc/jemalloc.html (revision 5268379e)
1*5268379eSantirez<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>JEMALLOC</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry"><a name="idp45223136"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>jemalloc &#8212; general purpose memory allocation functions</p></div><div class="refsect1"><a name="library"></a><h2>LIBRARY</h2><p>This manual describes jemalloc 4.0.3-0-ge9192eacf8935e29fc62fddc2701f7942b1cc02c.  More information
2*5268379eSantirez    can be found at the <a class="ulink" href="http://www.canonware.com/jemalloc/" target="_top">jemalloc website</a>.</p></div><div class="refsynopsisdiv"><h2>SYNOPSIS</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;<code class="filename">jemalloc/jemalloc.h</code>&gt;</pre><div class="refsect2"><a name="idp44244480"></a><h3>Standard API</h3><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">malloc</b>(</code></td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">calloc</b>(</code></td><td>size_t <var class="pdparam">number</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">posix_memalign</b>(</code></td><td>void **<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">alignment</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">aligned_alloc</b>(</code></td><td>size_t <var class="pdparam">alignment</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">realloc</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">free</b>(</code></td><td>void *<var class="pdparam">ptr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="refsect2"><a name="idp46062768"></a><h3>Non-standard API</h3><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">mallocx</b>(</code></td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">rallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">xallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">extra</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">sallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">dallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">sdallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">nallocx</b>(</code></td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctl</b>(</code></td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">oldp</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">oldlenp</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">newp</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">newlen</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctlnametomib</b>(</code></td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">mibp</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">miblenp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctlbymib</b>(</code></td><td>const size_t *<var class="pdparam">mib</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">miblen</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">oldp</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">oldlenp</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">newp</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">newlen</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">malloc_stats_print</b>(</code></td><td>void <var class="pdparam">(*write_cb)</var>
3a78e148bSantirez            <code>(</code>void *, const char *<code>)</code>
4*5268379eSantirez          , </td></tr><tr><td>�</td><td>void *<var class="pdparam">cbopaque</var>, </td></tr><tr><td>�</td><td>const char *<var class="pdparam">opts</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">malloc_usable_size</b>(</code></td><td>const void *<var class="pdparam">ptr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">(*malloc_message)</b>(</code></td><td>void *<var class="pdparam">cbopaque</var>, </td></tr><tr><td>�</td><td>const char *<var class="pdparam">s</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><p><span class="type">const char *</span><code class="varname">malloc_conf</code>;</p></div></div></div><div class="refsect1"><a name="description"></a><h2>DESCRIPTION</h2><div class="refsect2"><a name="idp46115952"></a><h3>Standard API</h3><p>The <code class="function">malloc</code>(<em class="parameter"><code></code></em>) function allocates
5a78e148bSantirez      <em class="parameter"><code>size</code></em> bytes of uninitialized memory.  The allocated
6a78e148bSantirez      space is suitably aligned (after possible pointer coercion) for storage
7a78e148bSantirez      of any type of object.</p><p>The <code class="function">calloc</code>(<em class="parameter"><code></code></em>) function allocates
8a78e148bSantirez      space for <em class="parameter"><code>number</code></em> objects, each
9a78e148bSantirez      <em class="parameter"><code>size</code></em> bytes in length.  The result is identical to
10a78e148bSantirez      calling <code class="function">malloc</code>(<em class="parameter"><code></code></em>) with an argument of
11a78e148bSantirez      <em class="parameter"><code>number</code></em> * <em class="parameter"><code>size</code></em>, with the
12a78e148bSantirez      exception that the allocated memory is explicitly initialized to zero
13a78e148bSantirez      bytes.</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function
14a78e148bSantirez      allocates <em class="parameter"><code>size</code></em> bytes of memory such that the
15*5268379eSantirez      allocation's base address is a multiple of
16a78e148bSantirez      <em class="parameter"><code>alignment</code></em>, and returns the allocation in the value
17a78e148bSantirez      pointed to by <em class="parameter"><code>ptr</code></em>.  The requested
18*5268379eSantirez      <em class="parameter"><code>alignment</code></em> must be a power of 2 at least as large as
19*5268379eSantirez      <code class="code">sizeof(<span class="type">void *</span>)</code>.</p><p>The <code class="function">aligned_alloc</code>(<em class="parameter"><code></code></em>) function
20ad4c0b41Santirez      allocates <em class="parameter"><code>size</code></em> bytes of memory such that the
21*5268379eSantirez      allocation's base address is a multiple of
22ad4c0b41Santirez      <em class="parameter"><code>alignment</code></em>.  The requested
23ad4c0b41Santirez      <em class="parameter"><code>alignment</code></em> must be a power of 2.  Behavior is
24ad4c0b41Santirez      undefined if <em class="parameter"><code>size</code></em> is not an integral multiple of
25ad4c0b41Santirez      <em class="parameter"><code>alignment</code></em>.</p><p>The <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function changes the
26a78e148bSantirez      size of the previously allocated memory referenced by
27a78e148bSantirez      <em class="parameter"><code>ptr</code></em> to <em class="parameter"><code>size</code></em> bytes.  The
28a78e148bSantirez      contents of the memory are unchanged up to the lesser of the new and old
29a78e148bSantirez      sizes.  If the new size is larger, the contents of the newly allocated
30a78e148bSantirez      portion of the memory are undefined.  Upon success, the memory referenced
31a78e148bSantirez      by <em class="parameter"><code>ptr</code></em> is freed and a pointer to the newly
32a78e148bSantirez      allocated memory is returned.  Note that
33a78e148bSantirez      <code class="function">realloc</code>(<em class="parameter"><code></code></em>) may move the memory allocation,
34a78e148bSantirez      resulting in a different return value than <em class="parameter"><code>ptr</code></em>.
35a78e148bSantirez      If <em class="parameter"><code>ptr</code></em> is <code class="constant">NULL</code>, the
36a78e148bSantirez      <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function behaves identically to
37a78e148bSantirez      <code class="function">malloc</code>(<em class="parameter"><code></code></em>) for the specified size.</p><p>The <code class="function">free</code>(<em class="parameter"><code></code></em>) function causes the
38a78e148bSantirez      allocated memory referenced by <em class="parameter"><code>ptr</code></em> to be made
39a78e148bSantirez      available for future allocations.  If <em class="parameter"><code>ptr</code></em> is
40*5268379eSantirez      <code class="constant">NULL</code>, no action occurs.</p></div><div class="refsect2"><a name="idp46144704"></a><h3>Non-standard API</h3><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>),
41fceef8e0Santirez      <code class="function">rallocx</code>(<em class="parameter"><code></code></em>),
42fceef8e0Santirez      <code class="function">xallocx</code>(<em class="parameter"><code></code></em>),
43fceef8e0Santirez      <code class="function">sallocx</code>(<em class="parameter"><code></code></em>),
44*5268379eSantirez      <code class="function">dallocx</code>(<em class="parameter"><code></code></em>),
45*5268379eSantirez      <code class="function">sdallocx</code>(<em class="parameter"><code></code></em>), and
46fceef8e0Santirez      <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) functions all have a
47fceef8e0Santirez      <em class="parameter"><code>flags</code></em> argument that can be used to specify
48fceef8e0Santirez      options.  The functions only check the options that are contextually
49fceef8e0Santirez      relevant.  Use bitwise or (<code class="code">|</code>) operations to
50fceef8e0Santirez      specify one or more of the following:
51*5268379eSantirez        </p><div class="variablelist"><dl class="variablelist"><dt><a name="MALLOCX_LG_ALIGN"></a><span class="term"><code class="constant">MALLOCX_LG_ALIGN(<em class="parameter"><code>la</code></em>)
52fceef8e0Santirez            </code></span></dt><dd><p>Align the memory allocation to start at an address
53fceef8e0Santirez            that is a multiple of <code class="code">(1 &lt;&lt;
54fceef8e0Santirez            <em class="parameter"><code>la</code></em>)</code>.  This macro does not validate
55fceef8e0Santirez            that <em class="parameter"><code>la</code></em> is within the valid
56*5268379eSantirez            range.</p></dd><dt><a name="MALLOCX_ALIGN"></a><span class="term"><code class="constant">MALLOCX_ALIGN(<em class="parameter"><code>a</code></em>)
57fceef8e0Santirez            </code></span></dt><dd><p>Align the memory allocation to start at an address
58fceef8e0Santirez            that is a multiple of <em class="parameter"><code>a</code></em>, where
59fceef8e0Santirez            <em class="parameter"><code>a</code></em> is a power of two.  This macro does not
60fceef8e0Santirez            validate that <em class="parameter"><code>a</code></em> is a power of 2.
61*5268379eSantirez            </p></dd><dt><a name="MALLOCX_ZERO"></a><span class="term"><code class="constant">MALLOCX_ZERO</code></span></dt><dd><p>Initialize newly allocated memory to contain zero
62fceef8e0Santirez            bytes.  In the growing reallocation case, the real size prior to
63fceef8e0Santirez            reallocation defines the boundary between untouched bytes and those
64fceef8e0Santirez            that are initialized to contain zero bytes.  If this macro is
65*5268379eSantirez            absent, newly allocated memory is uninitialized.</p></dd><dt><a name="MALLOCX_TCACHE"></a><span class="term"><code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)
66*5268379eSantirez            </code></span></dt><dd><p>Use the thread-specific cache (tcache) specified by
67*5268379eSantirez            the identifier <em class="parameter"><code>tc</code></em>, which must have been
68*5268379eSantirez            acquired via the <a class="link" href="#tcache.create">
69*5268379eSantirez    "<code class="mallctl">tcache.create</code>"
70*5268379eSantirez  </a>
71*5268379eSantirez            mallctl.  This macro does not validate that
72*5268379eSantirez            <em class="parameter"><code>tc</code></em> specifies a valid
73*5268379eSantirez            identifier.</p></dd><dt><a name="MALLOC_TCACHE_NONE"></a><span class="term"><code class="constant">MALLOCX_TCACHE_NONE</code></span></dt><dd><p>Do not use a thread-specific cache (tcache).  Unless
74*5268379eSantirez            <code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)</code> or
75*5268379eSantirez            <code class="constant">MALLOCX_TCACHE_NONE</code> is specified, an
76*5268379eSantirez            automatically managed tcache will be used under many circumstances.
77*5268379eSantirez            This macro cannot be used in the same <em class="parameter"><code>flags</code></em>
78*5268379eSantirez            argument as
79*5268379eSantirez            <code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)</code>.</p></dd><dt><a name="MALLOCX_ARENA"></a><span class="term"><code class="constant">MALLOCX_ARENA(<em class="parameter"><code>a</code></em>)
80fceef8e0Santirez            </code></span></dt><dd><p>Use the arena specified by the index
81*5268379eSantirez            <em class="parameter"><code>a</code></em>.  This macro has no effect for regions that
82*5268379eSantirez            were allocated via an arena other than the one specified.  This
83*5268379eSantirez            macro does not validate that <em class="parameter"><code>a</code></em> specifies an
84*5268379eSantirez            arena index in the valid range.</p></dd></dl></div><p>
85fceef8e0Santirez      </p><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function allocates at
86fceef8e0Santirez      least <em class="parameter"><code>size</code></em> bytes of memory, and returns a pointer
87fceef8e0Santirez      to the base address of the allocation.  Behavior is undefined if
88fceef8e0Santirez      <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if request size
89fceef8e0Santirez      overflows due to size class and/or alignment constraints.</p><p>The <code class="function">rallocx</code>(<em class="parameter"><code></code></em>) function resizes the
90fceef8e0Santirez      allocation at <em class="parameter"><code>ptr</code></em> to be at least
91fceef8e0Santirez      <em class="parameter"><code>size</code></em> bytes, and returns a pointer to the base
92fceef8e0Santirez      address of the resulting allocation, which may or may not have moved from
93fceef8e0Santirez      its original location.  Behavior is undefined if
94fceef8e0Santirez      <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if request size
95fceef8e0Santirez      overflows due to size class and/or alignment constraints.</p><p>The <code class="function">xallocx</code>(<em class="parameter"><code></code></em>) function resizes the
96fceef8e0Santirez      allocation at <em class="parameter"><code>ptr</code></em> in place to be at least
97fceef8e0Santirez      <em class="parameter"><code>size</code></em> bytes, and returns the real size of the
98fceef8e0Santirez      allocation.  If <em class="parameter"><code>extra</code></em> is non-zero, an attempt is
99fceef8e0Santirez      made to resize the allocation to be at least <code class="code">(<em class="parameter"><code>size</code></em> +
100fceef8e0Santirez      <em class="parameter"><code>extra</code></em>)</code> bytes, though inability to allocate
101fceef8e0Santirez      the extra byte(s) will not by itself result in failure to resize.
102fceef8e0Santirez      Behavior is undefined if <em class="parameter"><code>size</code></em> is
103fceef8e0Santirez      <code class="constant">0</code>, or if <code class="code">(<em class="parameter"><code>size</code></em> + <em class="parameter"><code>extra</code></em>
104fceef8e0Santirez      &gt; <code class="constant">SIZE_T_MAX</code>)</code>.</p><p>The <code class="function">sallocx</code>(<em class="parameter"><code></code></em>) function returns the
105fceef8e0Santirez      real size of the allocation at <em class="parameter"><code>ptr</code></em>.</p><p>The <code class="function">dallocx</code>(<em class="parameter"><code></code></em>) function causes the
106fceef8e0Santirez      memory referenced by <em class="parameter"><code>ptr</code></em> to be made available for
107*5268379eSantirez      future allocations.</p><p>The <code class="function">sdallocx</code>(<em class="parameter"><code></code></em>) function is an
108*5268379eSantirez      extension of <code class="function">dallocx</code>(<em class="parameter"><code></code></em>) with a
109*5268379eSantirez      <em class="parameter"><code>size</code></em> parameter to allow the caller to pass in the
110*5268379eSantirez      allocation size as an optimization.  The minimum valid input size is the
111*5268379eSantirez      original requested size of the allocation, and the maximum valid input
112*5268379eSantirez      size is the corresponding value returned by
113*5268379eSantirez      <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) or
114*5268379eSantirez      <code class="function">sallocx</code>(<em class="parameter"><code></code></em>).</p><p>The <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) function allocates no
115fceef8e0Santirez      memory, but it performs the same size computation as the
116fceef8e0Santirez      <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function, and returns the real
117fceef8e0Santirez      size of the allocation that would result from the equivalent
118fceef8e0Santirez      <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function call.  Behavior is
119fceef8e0Santirez      undefined if <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if
120fceef8e0Santirez      request size overflows due to size class and/or alignment
121fceef8e0Santirez      constraints.</p><p>The <code class="function">mallctl</code>(<em class="parameter"><code></code></em>) function provides a
122a78e148bSantirez      general interface for introspecting the memory allocator, as well as
123a78e148bSantirez      setting modifiable parameters and triggering actions.  The
124a78e148bSantirez      period-separated <em class="parameter"><code>name</code></em> argument specifies a
125a78e148bSantirez      location in a tree-structured namespace; see the <a class="xref" href="#mallctl_namespace" title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for
126a78e148bSantirez      documentation on the tree contents.  To read a value, pass a pointer via
127a78e148bSantirez      <em class="parameter"><code>oldp</code></em> to adequate space to contain the value, and a
128a78e148bSantirez      pointer to its length via <em class="parameter"><code>oldlenp</code></em>; otherwise pass
129a78e148bSantirez      <code class="constant">NULL</code> and <code class="constant">NULL</code>.  Similarly, to
130a78e148bSantirez      write a value, pass a pointer to the value via
131a78e148bSantirez      <em class="parameter"><code>newp</code></em>, and its length via
132a78e148bSantirez      <em class="parameter"><code>newlen</code></em>; otherwise pass <code class="constant">NULL</code>
133a78e148bSantirez      and <code class="constant">0</code>.</p><p>The <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>) function
134a78e148bSantirez      provides a way to avoid repeated name lookups for applications that
135a78e148bSantirez      repeatedly query the same portion of the namespace, by translating a name
136a78e148bSantirez      to a &#8220;Management Information Base&#8221; (MIB) that can be passed
137a78e148bSantirez      repeatedly to <code class="function">mallctlbymib</code>(<em class="parameter"><code></code></em>).  Upon
138a78e148bSantirez      successful return from <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>),
139a78e148bSantirez      <em class="parameter"><code>mibp</code></em> contains an array of
140a78e148bSantirez      <em class="parameter"><code>*miblenp</code></em> integers, where
141a78e148bSantirez      <em class="parameter"><code>*miblenp</code></em> is the lesser of the number of components
142a78e148bSantirez      in <em class="parameter"><code>name</code></em> and the input value of
143a78e148bSantirez      <em class="parameter"><code>*miblenp</code></em>.  Thus it is possible to pass a
144a78e148bSantirez      <em class="parameter"><code>*miblenp</code></em> that is smaller than the number of
145a78e148bSantirez      period-separated name components, which results in a partial MIB that can
146a78e148bSantirez      be used as the basis for constructing a complete MIB.  For name
147a78e148bSantirez      components that are integers (e.g. the 2 in
148a78e148bSantirez      <a class="link" href="#arenas.bin.i.size">
149a78e148bSantirez    "<code class="mallctl">arenas.bin.2.size</code>"
150a78e148bSantirez  </a>),
151a78e148bSantirez      the corresponding MIB component will always be that integer.  Therefore,
152a78e148bSantirez      it is legitimate to construct code like the following: </p><pre class="programlisting">
153a78e148bSantirezunsigned nbins, i;
154fceef8e0Santirezsize_t mib[4];
155a78e148bSantirezsize_t len, miblen;
156a78e148bSantirez
157a78e148bSantirezlen = sizeof(nbins);
158a78e148bSantirezmallctl("arenas.nbins", &amp;nbins, &amp;len, NULL, 0);
159a78e148bSantirez
160a78e148bSantirezmiblen = 4;
161fceef8e0Santirezmallctlnametomib("arenas.bin.0.size", mib, &amp;miblen);
162a78e148bSantirezfor (i = 0; i &lt; nbins; i++) {
163a78e148bSantirez	size_t bin_size;
164a78e148bSantirez
165a78e148bSantirez	mib[2] = i;
166a78e148bSantirez	len = sizeof(bin_size);
167a78e148bSantirez	mallctlbymib(mib, miblen, &amp;bin_size, &amp;len, NULL, 0);
168a78e148bSantirez	/* Do something with bin_size... */
169fceef8e0Santirez}</pre><p>The <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>) function
170fceef8e0Santirez      writes human-readable summary statistics via the
171fceef8e0Santirez      <em class="parameter"><code>write_cb</code></em> callback function pointer and
172fceef8e0Santirez      <em class="parameter"><code>cbopaque</code></em> data passed to
173fceef8e0Santirez      <em class="parameter"><code>write_cb</code></em>, or
174fceef8e0Santirez      <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) if
175fceef8e0Santirez      <em class="parameter"><code>write_cb</code></em> is <code class="constant">NULL</code>.  This
176fceef8e0Santirez      function can be called repeatedly.  General information that never
177fceef8e0Santirez      changes during execution can be omitted by specifying "g" as a character
178fceef8e0Santirez      within the <em class="parameter"><code>opts</code></em> string.  Note that
179fceef8e0Santirez      <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) uses the
180fceef8e0Santirez      <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions internally, so
181fceef8e0Santirez      inconsistent statistics can be reported if multiple threads use these
182fceef8e0Santirez      functions simultaneously.  If <code class="option">--enable-stats</code> is
183fceef8e0Santirez      specified during configuration, &#8220;m&#8221; and &#8220;a&#8221; can
184fceef8e0Santirez      be specified to omit merged arena and per arena statistics, respectively;
185*5268379eSantirez      &#8220;b&#8221;, &#8220;l&#8221;, and &#8220;h&#8221; can be specified to
186*5268379eSantirez      omit per size class statistics for bins, large objects, and huge objects,
187*5268379eSantirez      respectively.  Unrecognized characters are silently ignored.  Note that
188*5268379eSantirez      thread caching may prevent some statistics from being completely up to
189*5268379eSantirez      date, since extra locking would be required to merge counters that track
190*5268379eSantirez      thread cache operations.
191fceef8e0Santirez      </p><p>The <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function
192fceef8e0Santirez      returns the usable size of the allocation pointed to by
193fceef8e0Santirez      <em class="parameter"><code>ptr</code></em>.  The return value may be larger than the size
194fceef8e0Santirez      that was requested during allocation.  The
195fceef8e0Santirez      <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function is not a
196fceef8e0Santirez      mechanism for in-place <code class="function">realloc</code>(<em class="parameter"><code></code></em>); rather
197fceef8e0Santirez      it is provided solely as a tool for introspection purposes.  Any
198fceef8e0Santirez      discrepancy between the requested allocation size and the size reported
199fceef8e0Santirez      by <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) should not be
200fceef8e0Santirez      depended on, since such behavior is entirely implementation-dependent.
201*5268379eSantirez      </p></div></div><div class="refsect1"><a name="tuning"></a><h2>TUNING</h2><p>Once, when the first call is made to one of the memory allocation
202a78e148bSantirez    routines, the allocator initializes its internals based in part on various
203a78e148bSantirez    options that can be specified at compile- or run-time.</p><p>The string pointed to by the global variable
204a78e148bSantirez    <code class="varname">malloc_conf</code>, the &#8220;name&#8221; of the file
205a78e148bSantirez    referenced by the symbolic link named <code class="filename">/etc/malloc.conf</code>, and the value of the
206a78e148bSantirez    environment variable <code class="envar">MALLOC_CONF</code>, will be interpreted, in
207fceef8e0Santirez    that order, from left to right as options.  Note that
208fceef8e0Santirez    <code class="varname">malloc_conf</code> may be read before
209fceef8e0Santirez    <code class="function">main</code>(<em class="parameter"><code></code></em>) is entered, so the declaration of
210fceef8e0Santirez    <code class="varname">malloc_conf</code> should specify an initializer that contains
211fceef8e0Santirez    the final value to be read by jemalloc.  <code class="varname">malloc_conf</code> is
212fceef8e0Santirez    a compile-time setting, whereas <code class="filename">/etc/malloc.conf</code> and <code class="envar">MALLOC_CONF</code>
213fceef8e0Santirez    can be safely set any time prior to program invocation.</p><p>An options string is a comma-separated list of option:value pairs.
214a78e148bSantirez    There is one key corresponding to each <a class="link" href="#opt.abort">
215a78e148bSantirez    "<code class="mallctl">opt.*</code>"
216a78e148bSantirez  </a> mallctl (see the <a class="xref" href="#mallctl_namespace" title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for options
217a78e148bSantirez    documentation).  For example, <code class="literal">abort:true,narenas:1</code> sets
218a78e148bSantirez    the <a class="link" href="#opt.abort">
219a78e148bSantirez    "<code class="mallctl">opt.abort</code>"
220a78e148bSantirez  </a> and <a class="link" href="#opt.narenas">
221a78e148bSantirez    "<code class="mallctl">opt.narenas</code>"
222a78e148bSantirez  </a> options.  Some
223a78e148bSantirez    options have boolean values (true/false), others have integer values (base
224a78e148bSantirez    8, 10, or 16, depending on prefix), and yet others have raw string
225fceef8e0Santirez    values.</p></div><div class="refsect1"><a name="implementation_notes"></a><h2>IMPLEMENTATION NOTES</h2><p>Traditionally, allocators have used
226a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> to obtain memory, which is
227a78e148bSantirez    suboptimal for several reasons, including race conditions, increased
228a78e148bSantirez    fragmentation, and artificial limitations on maximum usable memory.  If
229*5268379eSantirez    <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating
230*5268379eSantirez    system, this allocator uses both
231*5268379eSantirez    <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> and
232ad4c0b41Santirez    <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>, in that order of preference;
233a78e148bSantirez    otherwise only <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> is used.</p><p>This allocator uses multiple arenas in order to reduce lock
234a78e148bSantirez    contention for threaded programs on multi-processor systems.  This works
235a78e148bSantirez    well with regard to threading scalability, but incurs some costs.  There is
236a78e148bSantirez    a small fixed per-arena overhead, and additionally, arenas manage memory
237a78e148bSantirez    completely independently of each other, which means a small fixed increase
238a78e148bSantirez    in overall memory fragmentation.  These overheads are not generally an
239a78e148bSantirez    issue, given the number of arenas normally used.  Note that using
240a78e148bSantirez    substantially more arenas than the default is not likely to improve
241a78e148bSantirez    performance, mainly due to reduced cache performance.  However, it may make
242a78e148bSantirez    sense to reduce the number of arenas if an application does not make much
243a78e148bSantirez    use of the allocation functions.</p><p>In addition to multiple arenas, unless
244a78e148bSantirez    <code class="option">--disable-tcache</code> is specified during configuration, this
245a78e148bSantirez    allocator supports thread-specific caching for small and large objects, in
246a78e148bSantirez    order to make it possible to completely avoid synchronization for most
247a78e148bSantirez    allocation requests.  Such caching allows very fast allocation in the
248a78e148bSantirez    common case, but it increases memory usage and fragmentation, since a
249a78e148bSantirez    bounded number of objects can remain allocated in each thread cache.</p><p>Memory is conceptually broken into equal-sized chunks, where the
250a78e148bSantirez    chunk size is a power of two that is greater than the page size.  Chunks
251a78e148bSantirez    are always aligned to multiples of the chunk size.  This alignment makes it
252a78e148bSantirez    possible to find metadata for user objects very quickly.</p><p>User objects are broken into three categories according to size:
253*5268379eSantirez    small, large, and huge.  Small and large objects are managed entirely by
254*5268379eSantirez    arenas; huge objects are additionally aggregated in a single data structure
255*5268379eSantirez    that is shared by all threads.  Huge objects are typically used by
256*5268379eSantirez    applications infrequently enough that this single data structure is not a
257*5268379eSantirez    scalability issue.</p><p>Each chunk that is managed by an arena tracks its contents as runs of
258a78e148bSantirez    contiguous pages (unused, backing a set of small objects, or backing one
259a78e148bSantirez    large object).  The combination of chunk alignment and chunk page maps
260a78e148bSantirez    makes it possible to determine all metadata regarding small and large
261a78e148bSantirez    allocations in constant time.</p><p>Small objects are managed in groups by page runs.  Each run maintains
262*5268379eSantirez    a bitmap to track which regions are in use.  Allocation requests that are no
263*5268379eSantirez    more than half the quantum (8 or 16, depending on architecture) are rounded
264*5268379eSantirez    up to the nearest power of two that is at least <code class="code">sizeof(<span class="type">double</span>)</code>.  All other object size
265*5268379eSantirez    classes are multiples of the quantum, spaced such that there are four size
266*5268379eSantirez    classes for each doubling in size, which limits internal fragmentation to
267*5268379eSantirez    approximately 20% for all but the smallest size classes.  Small size classes
268*5268379eSantirez    are smaller than four times the page size, large size classes are smaller
269*5268379eSantirez    than the chunk size (see the <a class="link" href="#opt.lg_chunk">
270a78e148bSantirez    "<code class="mallctl">opt.lg_chunk</code>"
271*5268379eSantirez  </a> option), and
272*5268379eSantirez    huge size classes extend from the chunk size up to one size class less than
273*5268379eSantirez    the full address space size.</p><p>Allocations are packed tightly together, which can be an issue for
274a78e148bSantirez    multi-threaded applications.  If you need to assure that allocations do not
275a78e148bSantirez    suffer from cacheline sharing, round your allocation requests up to the
276a78e148bSantirez    nearest multiple of the cacheline size, or specify cacheline alignment when
277*5268379eSantirez    allocating.</p><p>The <code class="function">realloc</code>(<em class="parameter"><code></code></em>),
278*5268379eSantirez    <code class="function">rallocx</code>(<em class="parameter"><code></code></em>), and
279*5268379eSantirez    <code class="function">xallocx</code>(<em class="parameter"><code></code></em>) functions may resize allocations
280*5268379eSantirez    without moving them under limited circumstances.  Unlike the
281*5268379eSantirez    <code class="function">*allocx</code>(<em class="parameter"><code></code></em>) API, the standard API does not
282*5268379eSantirez    officially round up the usable size of an allocation to the nearest size
283*5268379eSantirez    class, so technically it is necessary to call
284*5268379eSantirez    <code class="function">realloc</code>(<em class="parameter"><code></code></em>) to grow e.g. a 9-byte allocation to
285*5268379eSantirez    16 bytes, or shrink a 16-byte allocation to 9 bytes.  Growth and shrinkage
286*5268379eSantirez    trivially succeeds in place as long as the pre-size and post-size both round
287*5268379eSantirez    up to the same size class.  No other API guarantees are made regarding
288*5268379eSantirez    in-place resizing, but the current implementation also tries to resize large
289*5268379eSantirez    and huge allocations in place, as long as the pre-size and post-size are
290*5268379eSantirez    both large or both huge.  In such cases shrinkage always succeeds for large
291*5268379eSantirez    size classes, but for huge size classes the chunk allocator must support
292*5268379eSantirez    splitting (see <a class="link" href="#arena.i.chunk_hooks">
293*5268379eSantirez    "<code class="mallctl">arena.&lt;i&gt;.chunk_hooks</code>"
294*5268379eSantirez  </a>).
295*5268379eSantirez    Growth only succeeds if the trailing memory is currently available, and
296*5268379eSantirez    additionally for huge size classes the chunk allocator must support
297*5268379eSantirez    merging.</p><p>Assuming 2 MiB chunks, 4 KiB pages, and a 16-byte quantum on a
298*5268379eSantirez    64-bit system, the size classes in each category are as shown in <a class="xref" href="#size_classes" title="Table�1.�Size classes">Table 1</a>.</p><div class="table"><a name="size_classes"></a><p class="title"><b>Table�1.�Size classes</b></p><div class="table-contents"><table summary="Size classes" border="1"><colgroup><col align="left" class="c1"><col align="right" class="c2"><col align="left" class="c3"></colgroup><thead><tr><th align="left">Category</th><th align="right">Spacing</th><th align="left">Size</th></tr></thead><tbody><tr><td rowspan="9" align="left">Small</td><td align="right">lg</td><td align="left">[8]</td></tr><tr><td align="right">16</td><td align="left">[16, 32, 48, 64, 80, 96, 112, 128]</td></tr><tr><td align="right">32</td><td align="left">[160, 192, 224, 256]</td></tr><tr><td align="right">64</td><td align="left">[320, 384, 448, 512]</td></tr><tr><td align="right">128</td><td align="left">[640, 768, 896, 1024]</td></tr><tr><td align="right">256</td><td align="left">[1280, 1536, 1792, 2048]</td></tr><tr><td align="right">512</td><td align="left">[2560, 3072, 3584, 4096]</td></tr><tr><td align="right">1 KiB</td><td align="left">[5 KiB, 6 KiB, 7 KiB, 8 KiB]</td></tr><tr><td align="right">2 KiB</td><td align="left">[10 KiB, 12 KiB, 14 KiB]</td></tr><tr><td rowspan="8" align="left">Large</td><td align="right">2 KiB</td><td align="left">[16 KiB]</td></tr><tr><td align="right">4 KiB</td><td align="left">[20 KiB, 24 KiB, 28 KiB, 32 KiB]</td></tr><tr><td align="right">8 KiB</td><td align="left">[40 KiB, 48 KiB, 54 KiB, 64 KiB]</td></tr><tr><td align="right">16 KiB</td><td align="left">[80 KiB, 96 KiB, 112 KiB, 128 KiB]</td></tr><tr><td align="right">32 KiB</td><td align="left">[160 KiB, 192 KiB, 224 KiB, 256 KiB]</td></tr><tr><td align="right">64 KiB</td><td align="left">[320 KiB, 384 KiB, 448 KiB, 512 KiB]</td></tr><tr><td align="right">128 KiB</td><td align="left">[640 KiB, 768 KiB, 896 KiB, 1 MiB]</td></tr><tr><td align="right">256 KiB</td><td align="left">[1280 KiB, 1536 KiB, 1792 KiB]</td></tr><tr><td rowspan="7" align="left">Huge</td><td align="right">256 KiB</td><td align="left">[2 MiB]</td></tr><tr><td align="right">512 KiB</td><td align="left">[2560 KiB, 3 MiB, 3584 KiB, 4 MiB]</td></tr><tr><td align="right">1 MiB</td><td align="left">[5 MiB, 6 MiB, 7 MiB, 8 MiB]</td></tr><tr><td align="right">2 MiB</td><td align="left">[10 MiB, 12 MiB, 14 MiB, 16 MiB]</td></tr><tr><td align="right">4 MiB</td><td align="left">[20 MiB, 24 MiB, 28 MiB, 32 MiB]</td></tr><tr><td align="right">8 MiB</td><td align="left">[40 MiB, 48 MiB, 56 MiB, 64 MiB]</td></tr><tr><td align="right">...</td><td align="left">...</td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="mallctl_namespace"></a><h2>MALLCTL NAMESPACE</h2><p>The following names are defined in the namespace accessible via the
299a78e148bSantirez    <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions.  Value types are
300a78e148bSantirez    specified in parentheses, their readable/writable statuses are encoded as
301a78e148bSantirez    <code class="literal">rw</code>, <code class="literal">r-</code>, <code class="literal">-w</code>, or
302a78e148bSantirez    <code class="literal">--</code>, and required build configuration flags follow, if
303a78e148bSantirez    any.  A name element encoded as <code class="literal">&lt;i&gt;</code> or
304a78e148bSantirez    <code class="literal">&lt;j&gt;</code> indicates an integer component, where the
305a78e148bSantirez    integer varies from 0 to some upper value that must be determined via
306a78e148bSantirez    introspection.  In the case of
307a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.*</code>"
308a78e148bSantirez  ,
309a78e148bSantirez    <code class="literal">&lt;i&gt;</code> equal to <a class="link" href="#arenas.narenas">
310a78e148bSantirez    "<code class="mallctl">arenas.narenas</code>"
311a78e148bSantirez  </a> can be
312a78e148bSantirez    used to access the summation of statistics from all arenas.  Take special
313a78e148bSantirez    note of the <a class="link" href="#epoch">
314a78e148bSantirez    "<code class="mallctl">epoch</code>"
315a78e148bSantirez  </a> mallctl,
316fceef8e0Santirez    which controls refreshing of cached dynamic statistics.</p><div class="variablelist"><dl class="variablelist"><dt><a name="version"></a><span class="term">
317a78e148bSantirez
318a78e148bSantirez    "<code class="mallctl">version</code>"
319a78e148bSantirez
320a78e148bSantirez          (<span class="type">const char *</span>)
321a78e148bSantirez          <code class="literal">r-</code>
322a78e148bSantirez        </span></dt><dd><p>Return the jemalloc version string.</p></dd><dt><a name="epoch"></a><span class="term">
323a78e148bSantirez
324a78e148bSantirez    "<code class="mallctl">epoch</code>"
325a78e148bSantirez
326a78e148bSantirez          (<span class="type">uint64_t</span>)
327a78e148bSantirez          <code class="literal">rw</code>
328a78e148bSantirez        </span></dt><dd><p>If a value is passed in, refresh the data from which
329a78e148bSantirez        the <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions report values,
330a78e148bSantirez        and increment the epoch.  Return the current epoch.  This is useful for
331*5268379eSantirez        detecting whether another thread caused a refresh.</p></dd><dt><a name="config.cache_oblivious"></a><span class="term">
332*5268379eSantirez
333*5268379eSantirez    "<code class="mallctl">config.cache_oblivious</code>"
334*5268379eSantirez
335*5268379eSantirez          (<span class="type">bool</span>)
336*5268379eSantirez          <code class="literal">r-</code>
337*5268379eSantirez        </span></dt><dd><p><code class="option">--enable-cache-oblivious</code> was specified
338*5268379eSantirez        during build configuration.</p></dd><dt><a name="config.debug"></a><span class="term">
339a78e148bSantirez
340a78e148bSantirez    "<code class="mallctl">config.debug</code>"
341a78e148bSantirez
342a78e148bSantirez          (<span class="type">bool</span>)
343a78e148bSantirez          <code class="literal">r-</code>
344a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-debug</code> was specified during
345fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.fill"></a><span class="term">
346a78e148bSantirez
347a78e148bSantirez    "<code class="mallctl">config.fill</code>"
348a78e148bSantirez
349a78e148bSantirez          (<span class="type">bool</span>)
350a78e148bSantirez          <code class="literal">r-</code>
351a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-fill</code> was specified during
352fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.lazy_lock"></a><span class="term">
353a78e148bSantirez
354a78e148bSantirez    "<code class="mallctl">config.lazy_lock</code>"
355a78e148bSantirez
356a78e148bSantirez          (<span class="type">bool</span>)
357a78e148bSantirez          <code class="literal">r-</code>
358a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-lazy-lock</code> was specified
359*5268379eSantirez        during build configuration.</p></dd><dt><a name="config.munmap"></a><span class="term">
360ad4c0b41Santirez
361ad4c0b41Santirez    "<code class="mallctl">config.munmap</code>"
362ad4c0b41Santirez
363ad4c0b41Santirez          (<span class="type">bool</span>)
364ad4c0b41Santirez          <code class="literal">r-</code>
365ad4c0b41Santirez        </span></dt><dd><p><code class="option">--enable-munmap</code> was specified during
366fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.prof"></a><span class="term">
367ad4c0b41Santirez
368a78e148bSantirez    "<code class="mallctl">config.prof</code>"
369a78e148bSantirez
370a78e148bSantirez          (<span class="type">bool</span>)
371a78e148bSantirez          <code class="literal">r-</code>
372a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-prof</code> was specified during
373fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.prof_libgcc"></a><span class="term">
374a78e148bSantirez
375a78e148bSantirez    "<code class="mallctl">config.prof_libgcc</code>"
376a78e148bSantirez
377a78e148bSantirez          (<span class="type">bool</span>)
378a78e148bSantirez          <code class="literal">r-</code>
379a78e148bSantirez        </span></dt><dd><p><code class="option">--disable-prof-libgcc</code> was not
380fceef8e0Santirez        specified during build configuration.</p></dd><dt><a name="config.prof_libunwind"></a><span class="term">
381a78e148bSantirez
382a78e148bSantirez    "<code class="mallctl">config.prof_libunwind</code>"
383a78e148bSantirez
384a78e148bSantirez          (<span class="type">bool</span>)
385a78e148bSantirez          <code class="literal">r-</code>
386a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-prof-libunwind</code> was specified
387fceef8e0Santirez        during build configuration.</p></dd><dt><a name="config.stats"></a><span class="term">
388a78e148bSantirez
389a78e148bSantirez    "<code class="mallctl">config.stats</code>"
390a78e148bSantirez
391a78e148bSantirez          (<span class="type">bool</span>)
392a78e148bSantirez          <code class="literal">r-</code>
393a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-stats</code> was specified during
394fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.tcache"></a><span class="term">
395a78e148bSantirez
396a78e148bSantirez    "<code class="mallctl">config.tcache</code>"
397a78e148bSantirez
398a78e148bSantirez          (<span class="type">bool</span>)
399a78e148bSantirez          <code class="literal">r-</code>
400a78e148bSantirez        </span></dt><dd><p><code class="option">--disable-tcache</code> was not specified
401fceef8e0Santirez        during build configuration.</p></dd><dt><a name="config.tls"></a><span class="term">
402a78e148bSantirez
403a78e148bSantirez    "<code class="mallctl">config.tls</code>"
404a78e148bSantirez
405a78e148bSantirez          (<span class="type">bool</span>)
406a78e148bSantirez          <code class="literal">r-</code>
407a78e148bSantirez        </span></dt><dd><p><code class="option">--disable-tls</code> was not specified during
408fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.utrace"></a><span class="term">
409a78e148bSantirez
410ad4c0b41Santirez    "<code class="mallctl">config.utrace</code>"
411ad4c0b41Santirez
412ad4c0b41Santirez          (<span class="type">bool</span>)
413ad4c0b41Santirez          <code class="literal">r-</code>
414ad4c0b41Santirez        </span></dt><dd><p><code class="option">--enable-utrace</code> was specified during
415fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.valgrind"></a><span class="term">
416ad4c0b41Santirez
417ad4c0b41Santirez    "<code class="mallctl">config.valgrind</code>"
418ad4c0b41Santirez
419ad4c0b41Santirez          (<span class="type">bool</span>)
420ad4c0b41Santirez          <code class="literal">r-</code>
421ad4c0b41Santirez        </span></dt><dd><p><code class="option">--enable-valgrind</code> was specified during
422fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.xmalloc"></a><span class="term">
423ad4c0b41Santirez
424a78e148bSantirez    "<code class="mallctl">config.xmalloc</code>"
425a78e148bSantirez
426a78e148bSantirez          (<span class="type">bool</span>)
427a78e148bSantirez          <code class="literal">r-</code>
428a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-xmalloc</code> was specified during
429a78e148bSantirez        build configuration.</p></dd><dt><a name="opt.abort"></a><span class="term">
430a78e148bSantirez
431a78e148bSantirez    "<code class="mallctl">opt.abort</code>"
432a78e148bSantirez
433a78e148bSantirez          (<span class="type">bool</span>)
434a78e148bSantirez          <code class="literal">r-</code>
435a78e148bSantirez        </span></dt><dd><p>Abort-on-warning enabled/disabled.  If true, most
436a78e148bSantirez        warnings are fatal.  The process will call
437a78e148bSantirez        <span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span> in these cases.  This option is
438a78e148bSantirez        disabled by default unless <code class="option">--enable-debug</code> is
439a78e148bSantirez        specified during configuration, in which case it is enabled by default.
440fceef8e0Santirez        </p></dd><dt><a name="opt.dss"></a><span class="term">
4417383c3b1Santirez
4427383c3b1Santirez    "<code class="mallctl">opt.dss</code>"
4437383c3b1Santirez
4447383c3b1Santirez          (<span class="type">const char *</span>)
4457383c3b1Santirez          <code class="literal">r-</code>
4467383c3b1Santirez        </span></dt><dd><p>dss (<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>) allocation precedence as
4477383c3b1Santirez        related to <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> allocation.  The following
448*5268379eSantirez        settings are supported if
449*5268379eSantirez        <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating
450*5268379eSantirez        system: &#8220;disabled&#8221;, &#8220;primary&#8221;, and
451*5268379eSantirez        &#8220;secondary&#8221;; otherwise only &#8220;disabled&#8221; is
452*5268379eSantirez        supported.  The default is &#8220;secondary&#8221; if
453*5268379eSantirez        <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating
454*5268379eSantirez        system; &#8220;disabled&#8221; otherwise.
455fceef8e0Santirez        </p></dd><dt><a name="opt.lg_chunk"></a><span class="term">
456fceef8e0Santirez
457fceef8e0Santirez    "<code class="mallctl">opt.lg_chunk</code>"
458fceef8e0Santirez
459fceef8e0Santirez          (<span class="type">size_t</span>)
460fceef8e0Santirez          <code class="literal">r-</code>
461fceef8e0Santirez        </span></dt><dd><p>Virtual memory chunk size (log base 2).  If a chunk
462fceef8e0Santirez        size outside the supported size range is specified, the size is
463fceef8e0Santirez        silently clipped to the minimum/maximum supported size.  The default
464*5268379eSantirez        chunk size is 2 MiB (2^21).
465fceef8e0Santirez        </p></dd><dt><a name="opt.narenas"></a><span class="term">
466a78e148bSantirez
467a78e148bSantirez    "<code class="mallctl">opt.narenas</code>"
468a78e148bSantirez
469a78e148bSantirez          (<span class="type">size_t</span>)
470a78e148bSantirez          <code class="literal">r-</code>
4717383c3b1Santirez        </span></dt><dd><p>Maximum number of arenas to use for automatic
4727383c3b1Santirez        multiplexing of threads and arenas.  The default is four times the
4737383c3b1Santirez        number of CPUs, or one if there is a single CPU.</p></dd><dt><a name="opt.lg_dirty_mult"></a><span class="term">
474a78e148bSantirez
475a78e148bSantirez    "<code class="mallctl">opt.lg_dirty_mult</code>"
476a78e148bSantirez
477a78e148bSantirez          (<span class="type">ssize_t</span>)
478a78e148bSantirez          <code class="literal">r-</code>
479a78e148bSantirez        </span></dt><dd><p>Per-arena minimum ratio (log base 2) of active to dirty
480a78e148bSantirez        pages.  Some dirty unused pages may be allowed to accumulate, within
481a78e148bSantirez        the limit set by the ratio (or one chunk worth of dirty pages,
482a78e148bSantirez        whichever is greater), before informing the kernel about some of those
483a78e148bSantirez        pages via <span class="citerefentry"><span class="refentrytitle">madvise</span>(2)</span> or a similar system call.  This
484a78e148bSantirez        provides the kernel with sufficient information to recycle dirty pages
485a78e148bSantirez        if physical memory becomes scarce and the pages remain unused.  The
4867383c3b1Santirez        default minimum ratio is 8:1 (2^3:1); an option value of -1 will
487*5268379eSantirez        disable dirty page purging.  See <a class="link" href="#arenas.lg_dirty_mult">
488*5268379eSantirez    "<code class="mallctl">arenas.lg_dirty_mult</code>"
489*5268379eSantirez  </a>
490*5268379eSantirez        and <a class="link" href="#arena.i.lg_dirty_mult">
491*5268379eSantirez    "<code class="mallctl">arena.&lt;i&gt;.lg_dirty_mult</code>"
492*5268379eSantirez  </a>
493*5268379eSantirez        for related dynamic control options.</p></dd><dt><a name="opt.stats_print"></a><span class="term">
494a78e148bSantirez
495a78e148bSantirez    "<code class="mallctl">opt.stats_print</code>"
496a78e148bSantirez
497a78e148bSantirez          (<span class="type">bool</span>)
498a78e148bSantirez          <code class="literal">r-</code>
499a78e148bSantirez        </span></dt><dd><p>Enable/disable statistics printing at exit.  If
500a78e148bSantirez        enabled, the <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>)
501a78e148bSantirez        function is called at program exit via an
502a78e148bSantirez        <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function.  If
503a78e148bSantirez        <code class="option">--enable-stats</code> is specified during configuration, this
504a78e148bSantirez        has the potential to cause deadlock for a multi-threaded process that
505a78e148bSantirez        exits while one or more threads are executing in the memory allocation
506*5268379eSantirez        functions.  Furthermore, <code class="function">atexit</code>(<em class="parameter"><code></code></em>) may
507*5268379eSantirez        allocate memory during application initialization and then deadlock
508*5268379eSantirez        internally when jemalloc in turn calls
509*5268379eSantirez        <code class="function">atexit</code>(<em class="parameter"><code></code></em>), so this option is not
510*5268379eSantirez        univerally usable (though the application can register its own
511*5268379eSantirez        <code class="function">atexit</code>(<em class="parameter"><code></code></em>) function with equivalent
512*5268379eSantirez        functionality).  Therefore, this option should only be used with care;
513*5268379eSantirez        it is primarily intended as a performance tuning aid during application
514a78e148bSantirez        development.  This option is disabled by default.</p></dd><dt><a name="opt.junk"></a><span class="term">
515a78e148bSantirez
516a78e148bSantirez    "<code class="mallctl">opt.junk</code>"
517a78e148bSantirez
518*5268379eSantirez          (<span class="type">const char *</span>)
519a78e148bSantirez          <code class="literal">r-</code>
520a78e148bSantirez          [<code class="option">--enable-fill</code>]
521*5268379eSantirez        </span></dt><dd><p>Junk filling.  If set to "alloc", each byte of
522*5268379eSantirez        uninitialized allocated memory will be initialized to
523*5268379eSantirez        <code class="literal">0xa5</code>.  If set to "free", all deallocated memory will
524*5268379eSantirez        be initialized to <code class="literal">0x5a</code>.  If set to "true", both
525*5268379eSantirez        allocated and deallocated memory will be initialized, and if set to
526*5268379eSantirez        "false", junk filling be disabled entirely.  This is intended for
527*5268379eSantirez        debugging and will impact performance negatively.  This option is
528*5268379eSantirez        "false" by default unless <code class="option">--enable-debug</code> is specified
529*5268379eSantirez        during configuration, in which case it is "true" by default unless
530*5268379eSantirez        running inside <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>.</p></dd><dt><a name="opt.quarantine"></a><span class="term">
531ad4c0b41Santirez
532ad4c0b41Santirez    "<code class="mallctl">opt.quarantine</code>"
533ad4c0b41Santirez
534ad4c0b41Santirez          (<span class="type">size_t</span>)
535ad4c0b41Santirez          <code class="literal">r-</code>
536ad4c0b41Santirez          [<code class="option">--enable-fill</code>]
537ad4c0b41Santirez        </span></dt><dd><p>Per thread quarantine size in bytes.  If non-zero, each
538ad4c0b41Santirez        thread maintains a FIFO object quarantine that stores up to the
539ad4c0b41Santirez        specified number of bytes of memory.  The quarantined memory is not
540ad4c0b41Santirez        freed until it is released from quarantine, though it is immediately
541ad4c0b41Santirez        junk-filled if the <a class="link" href="#opt.junk">
542ad4c0b41Santirez    "<code class="mallctl">opt.junk</code>"
543ad4c0b41Santirez  </a> option is
544ad4c0b41Santirez        enabled.  This feature is of particular use in combination with <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>, which can detect attempts
545ad4c0b41Santirez        to access quarantined objects.  This is intended for debugging and will
5467383c3b1Santirez        impact performance negatively.  The default quarantine size is 0 unless
5477383c3b1Santirez        running inside Valgrind, in which case the default is 16
5487383c3b1Santirez        MiB.</p></dd><dt><a name="opt.redzone"></a><span class="term">
549ad4c0b41Santirez
550ad4c0b41Santirez    "<code class="mallctl">opt.redzone</code>"
551ad4c0b41Santirez
552ad4c0b41Santirez          (<span class="type">bool</span>)
553ad4c0b41Santirez          <code class="literal">r-</code>
554ad4c0b41Santirez          [<code class="option">--enable-fill</code>]
555ad4c0b41Santirez        </span></dt><dd><p>Redzones enabled/disabled.  If enabled, small
556ad4c0b41Santirez        allocations have redzones before and after them.  Furthermore, if the
557ad4c0b41Santirez        <a class="link" href="#opt.junk">
558ad4c0b41Santirez    "<code class="mallctl">opt.junk</code>"
559ad4c0b41Santirez  </a> option is
560ad4c0b41Santirez        enabled, the redzones are checked for corruption during deallocation.
561ad4c0b41Santirez        However, the primary intended purpose of this feature is to be used in
562ad4c0b41Santirez        combination with <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>,
563ad4c0b41Santirez        which needs redzones in order to do effective buffer overflow/underflow
564ad4c0b41Santirez        detection.  This option is intended for debugging and will impact
565ad4c0b41Santirez        performance negatively.  This option is disabled by
5667383c3b1Santirez        default unless running inside Valgrind.</p></dd><dt><a name="opt.zero"></a><span class="term">
567a78e148bSantirez
568a78e148bSantirez    "<code class="mallctl">opt.zero</code>"
569a78e148bSantirez
570a78e148bSantirez          (<span class="type">bool</span>)
571a78e148bSantirez          <code class="literal">r-</code>
572a78e148bSantirez          [<code class="option">--enable-fill</code>]
573a78e148bSantirez        </span></dt><dd><p>Zero filling enabled/disabled.  If enabled, each byte
574a78e148bSantirez        of uninitialized allocated memory will be initialized to 0.  Note that
575a78e148bSantirez        this initialization only happens once for each byte, so
576*5268379eSantirez        <code class="function">realloc</code>(<em class="parameter"><code></code></em>) and
577*5268379eSantirez        <code class="function">rallocx</code>(<em class="parameter"><code></code></em>) calls do not zero memory that
578a78e148bSantirez        was previously allocated.  This is intended for debugging and will
579a78e148bSantirez        impact performance negatively.  This option is disabled by default.
580ad4c0b41Santirez        </p></dd><dt><a name="opt.utrace"></a><span class="term">
581a78e148bSantirez
582ad4c0b41Santirez    "<code class="mallctl">opt.utrace</code>"
583a78e148bSantirez
584a78e148bSantirez          (<span class="type">bool</span>)
585a78e148bSantirez          <code class="literal">r-</code>
586ad4c0b41Santirez          [<code class="option">--enable-utrace</code>]
587ad4c0b41Santirez        </span></dt><dd><p>Allocation tracing based on
588ad4c0b41Santirez        <span class="citerefentry"><span class="refentrytitle">utrace</span>(2)</span> enabled/disabled.  This option
589*5268379eSantirez        is disabled by default.</p></dd><dt><a name="opt.xmalloc"></a><span class="term">
590a78e148bSantirez
591a78e148bSantirez    "<code class="mallctl">opt.xmalloc</code>"
592a78e148bSantirez
593a78e148bSantirez          (<span class="type">bool</span>)
594a78e148bSantirez          <code class="literal">r-</code>
595a78e148bSantirez          [<code class="option">--enable-xmalloc</code>]
596a78e148bSantirez        </span></dt><dd><p>Abort-on-out-of-memory enabled/disabled.  If enabled,
597a78e148bSantirez        rather than returning failure for any allocation function, display a
598a78e148bSantirez        diagnostic message on <code class="constant">STDERR_FILENO</code> and cause the
599a78e148bSantirez        program to drop core (using
600a78e148bSantirez        <span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span>).  If an application is
601a78e148bSantirez        designed to depend on this behavior, set the option at compile time by
602a78e148bSantirez        including the following in the source code:
603a78e148bSantirez        </p><pre class="programlisting">
604a78e148bSantirezmalloc_conf = "xmalloc:true";</pre><p>
605a78e148bSantirez        This option is disabled by default.</p></dd><dt><a name="opt.tcache"></a><span class="term">
606a78e148bSantirez
607a78e148bSantirez    "<code class="mallctl">opt.tcache</code>"
608a78e148bSantirez
609a78e148bSantirez          (<span class="type">bool</span>)
610a78e148bSantirez          <code class="literal">r-</code>
611a78e148bSantirez          [<code class="option">--enable-tcache</code>]
612*5268379eSantirez        </span></dt><dd><p>Thread-specific caching (tcache) enabled/disabled.  When
613*5268379eSantirez        there are multiple threads, each thread uses a tcache for objects up to
614*5268379eSantirez        a certain size.  Thread-specific caching allows many allocations to be
615*5268379eSantirez        satisfied without performing any thread synchronization, at the cost of
616*5268379eSantirez        increased memory use.  See the <a class="link" href="#opt.lg_tcache_max">
617a78e148bSantirez    "<code class="mallctl">opt.lg_tcache_max</code>"
618a78e148bSantirez  </a>
619ad4c0b41Santirez        option for related tuning information.  This option is enabled by
620*5268379eSantirez        default unless running inside <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>, in which case it is
621*5268379eSantirez        forcefully disabled.</p></dd><dt><a name="opt.lg_tcache_max"></a><span class="term">
622a78e148bSantirez
623a78e148bSantirez    "<code class="mallctl">opt.lg_tcache_max</code>"
624a78e148bSantirez
625a78e148bSantirez          (<span class="type">size_t</span>)
626a78e148bSantirez          <code class="literal">r-</code>
627a78e148bSantirez          [<code class="option">--enable-tcache</code>]
628a78e148bSantirez        </span></dt><dd><p>Maximum size class (log base 2) to cache in the
629*5268379eSantirez        thread-specific cache (tcache).  At a minimum, all small size classes
630*5268379eSantirez        are cached, and at a maximum all large size classes are cached.  The
631a78e148bSantirez        default maximum is 32 KiB (2^15).</p></dd><dt><a name="opt.prof"></a><span class="term">
632a78e148bSantirez
633a78e148bSantirez    "<code class="mallctl">opt.prof</code>"
634a78e148bSantirez
635a78e148bSantirez          (<span class="type">bool</span>)
636a78e148bSantirez          <code class="literal">r-</code>
637a78e148bSantirez          [<code class="option">--enable-prof</code>]
638a78e148bSantirez        </span></dt><dd><p>Memory profiling enabled/disabled.  If enabled, profile
639ad4c0b41Santirez        memory allocation activity.  See the <a class="link" href="#opt.prof_active">
640a78e148bSantirez    "<code class="mallctl">opt.prof_active</code>"
641a78e148bSantirez  </a>
642a78e148bSantirez        option for on-the-fly activation/deactivation.  See the <a class="link" href="#opt.lg_prof_sample">
643a78e148bSantirez    "<code class="mallctl">opt.lg_prof_sample</code>"
644a78e148bSantirez  </a>
645a78e148bSantirez        option for probabilistic sampling control.  See the <a class="link" href="#opt.prof_accum">
646a78e148bSantirez    "<code class="mallctl">opt.prof_accum</code>"
647a78e148bSantirez  </a>
648ad4c0b41Santirez        option for control of cumulative sample reporting.  See the <a class="link" href="#opt.lg_prof_interval">
649a78e148bSantirez    "<code class="mallctl">opt.lg_prof_interval</code>"
650a78e148bSantirez  </a>
651ad4c0b41Santirez        option for information on interval-triggered profile dumping, the <a class="link" href="#opt.prof_gdump">
652a78e148bSantirez    "<code class="mallctl">opt.prof_gdump</code>"
653a78e148bSantirez  </a>
654ad4c0b41Santirez        option for information on high-water-triggered profile dumping, and the
655ad4c0b41Santirez        <a class="link" href="#opt.prof_final">
656ad4c0b41Santirez    "<code class="mallctl">opt.prof_final</code>"
657ad4c0b41Santirez  </a>
658ad4c0b41Santirez        option for final profile dumping.  Profile output is compatible with
659*5268379eSantirez        the <span class="command"><strong>jeprof</strong></span> command, which is based on the
660*5268379eSantirez        <span class="command"><strong>pprof</strong></span> that is developed as part of the <a class="ulink" href="http://code.google.com/p/gperftools/" target="_top">gperftools
661a78e148bSantirez        package</a>.</p></dd><dt><a name="opt.prof_prefix"></a><span class="term">
662a78e148bSantirez
663a78e148bSantirez    "<code class="mallctl">opt.prof_prefix</code>"
664a78e148bSantirez
665a78e148bSantirez          (<span class="type">const char *</span>)
666a78e148bSantirez          <code class="literal">r-</code>
667a78e148bSantirez          [<code class="option">--enable-prof</code>]
668a78e148bSantirez        </span></dt><dd><p>Filename prefix for profile dumps.  If the prefix is
669a78e148bSantirez        set to the empty string, no automatic dumps will occur; this is
670a78e148bSantirez        primarily useful for disabling the automatic final heap dump (which
671a78e148bSantirez        also disables leak reporting, if enabled).  The default prefix is
672ad4c0b41Santirez        <code class="filename">jeprof</code>.</p></dd><dt><a name="opt.prof_active"></a><span class="term">
673a78e148bSantirez
674a78e148bSantirez    "<code class="mallctl">opt.prof_active</code>"
675a78e148bSantirez
676a78e148bSantirez          (<span class="type">bool</span>)
677*5268379eSantirez          <code class="literal">r-</code>
678a78e148bSantirez          [<code class="option">--enable-prof</code>]
679a78e148bSantirez        </span></dt><dd><p>Profiling activated/deactivated.  This is a secondary
680a78e148bSantirez        control mechanism that makes it possible to start the application with
681a78e148bSantirez        profiling enabled (see the <a class="link" href="#opt.prof">
682a78e148bSantirez    "<code class="mallctl">opt.prof</code>"
683a78e148bSantirez  </a> option) but
684a78e148bSantirez        inactive, then toggle profiling at any time during program execution
685a78e148bSantirez        with the <a class="link" href="#prof.active">
686a78e148bSantirez    "<code class="mallctl">prof.active</code>"
687a78e148bSantirez  </a> mallctl.
688*5268379eSantirez        This option is enabled by default.</p></dd><dt><a name="opt.prof_thread_active_init"></a><span class="term">
689*5268379eSantirez
690*5268379eSantirez    "<code class="mallctl">opt.prof_thread_active_init</code>"
691*5268379eSantirez
692*5268379eSantirez          (<span class="type">bool</span>)
693*5268379eSantirez          <code class="literal">r-</code>
694*5268379eSantirez          [<code class="option">--enable-prof</code>]
695*5268379eSantirez        </span></dt><dd><p>Initial setting for <a class="link" href="#thread.prof.active">
696*5268379eSantirez    "<code class="mallctl">thread.prof.active</code>"
697*5268379eSantirez  </a>
698*5268379eSantirez        in newly created threads.  The initial setting for newly created threads
699*5268379eSantirez        can also be changed during execution via the <a class="link" href="#prof.thread_active_init">
700*5268379eSantirez    "<code class="mallctl">prof.thread_active_init</code>"
701*5268379eSantirez  </a>
702*5268379eSantirez        mallctl.  This option is enabled by default.</p></dd><dt><a name="opt.lg_prof_sample"></a><span class="term">
703a78e148bSantirez
704a78e148bSantirez    "<code class="mallctl">opt.lg_prof_sample</code>"
705a78e148bSantirez
706*5268379eSantirez          (<span class="type">size_t</span>)
707a78e148bSantirez          <code class="literal">r-</code>
708a78e148bSantirez          [<code class="option">--enable-prof</code>]
709a78e148bSantirez        </span></dt><dd><p>Average interval (log base 2) between allocation
710a78e148bSantirez        samples, as measured in bytes of allocation activity.  Increasing the
711a78e148bSantirez        sampling interval decreases profile fidelity, but also decreases the
712ad4c0b41Santirez        computational overhead.  The default sample interval is 512 KiB (2^19
713ad4c0b41Santirez        B).</p></dd><dt><a name="opt.prof_accum"></a><span class="term">
714a78e148bSantirez
715a78e148bSantirez    "<code class="mallctl">opt.prof_accum</code>"
716a78e148bSantirez
717a78e148bSantirez          (<span class="type">bool</span>)
718a78e148bSantirez          <code class="literal">r-</code>
719a78e148bSantirez          [<code class="option">--enable-prof</code>]
720a78e148bSantirez        </span></dt><dd><p>Reporting of cumulative object/byte counts in profile
721a78e148bSantirez        dumps enabled/disabled.  If this option is enabled, every unique
722a78e148bSantirez        backtrace must be stored for the duration of execution.  Depending on
723a78e148bSantirez        the application, this can impose a large memory overhead, and the
724ad4c0b41Santirez        cumulative counts are not always of interest.  This option is disabled
725ad4c0b41Santirez        by default.</p></dd><dt><a name="opt.lg_prof_interval"></a><span class="term">
726a78e148bSantirez
727a78e148bSantirez    "<code class="mallctl">opt.lg_prof_interval</code>"
728a78e148bSantirez
729a78e148bSantirez          (<span class="type">ssize_t</span>)
730a78e148bSantirez          <code class="literal">r-</code>
731a78e148bSantirez          [<code class="option">--enable-prof</code>]
732a78e148bSantirez        </span></dt><dd><p>Average interval (log base 2) between memory profile
733a78e148bSantirez        dumps, as measured in bytes of allocation activity.  The actual
734a78e148bSantirez        interval between dumps may be sporadic because decentralized allocation
735a78e148bSantirez        counters are used to avoid synchronization bottlenecks.  Profiles are
736a78e148bSantirez        dumped to files named according to the pattern
737a78e148bSantirez        <code class="filename">&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.i&lt;iseq&gt;.heap</code>,
738a78e148bSantirez        where <code class="literal">&lt;prefix&gt;</code> is controlled by the
739a78e148bSantirez        <a class="link" href="#opt.prof_prefix">
740a78e148bSantirez    "<code class="mallctl">opt.prof_prefix</code>"
741a78e148bSantirez  </a>
742a78e148bSantirez        option.  By default, interval-triggered profile dumping is disabled
743a78e148bSantirez        (encoded as -1).
744a78e148bSantirez        </p></dd><dt><a name="opt.prof_gdump"></a><span class="term">
745a78e148bSantirez
746a78e148bSantirez    "<code class="mallctl">opt.prof_gdump</code>"
747a78e148bSantirez
748a78e148bSantirez          (<span class="type">bool</span>)
749a78e148bSantirez          <code class="literal">r-</code>
750a78e148bSantirez          [<code class="option">--enable-prof</code>]
751*5268379eSantirez        </span></dt><dd><p>Set the initial state of <a class="link" href="#prof.gdump">
752*5268379eSantirez    "<code class="mallctl">prof.gdump</code>"
753*5268379eSantirez  </a>, which when
754*5268379eSantirez        enabled triggers a memory profile dump every time the total virtual
755*5268379eSantirez        memory exceeds the previous maximum.  This option is disabled by
756*5268379eSantirez        default.</p></dd><dt><a name="opt.prof_final"></a><span class="term">
757ad4c0b41Santirez
758ad4c0b41Santirez    "<code class="mallctl">opt.prof_final</code>"
759ad4c0b41Santirez
760ad4c0b41Santirez          (<span class="type">bool</span>)
761ad4c0b41Santirez          <code class="literal">r-</code>
762ad4c0b41Santirez          [<code class="option">--enable-prof</code>]
763ad4c0b41Santirez        </span></dt><dd><p>Use an
764ad4c0b41Santirez        <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function to dump final memory
765ad4c0b41Santirez        usage to a file named according to the pattern
766ad4c0b41Santirez        <code class="filename">&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.f.heap</code>,
767ad4c0b41Santirez        where <code class="literal">&lt;prefix&gt;</code> is controlled by the <a class="link" href="#opt.prof_prefix">
768ad4c0b41Santirez    "<code class="mallctl">opt.prof_prefix</code>"
769ad4c0b41Santirez  </a>
770*5268379eSantirez        option.  Note that <code class="function">atexit</code>(<em class="parameter"><code></code></em>) may allocate
771*5268379eSantirez        memory during application initialization and then deadlock internally
772*5268379eSantirez        when jemalloc in turn calls <code class="function">atexit</code>(<em class="parameter"><code></code></em>), so
773*5268379eSantirez        this option is not univerally usable (though the application can
774*5268379eSantirez        register its own <code class="function">atexit</code>(<em class="parameter"><code></code></em>) function with
775*5268379eSantirez        equivalent functionality).  This option is disabled by
776*5268379eSantirez        default.</p></dd><dt><a name="opt.prof_leak"></a><span class="term">
777a78e148bSantirez
778a78e148bSantirez    "<code class="mallctl">opt.prof_leak</code>"
779a78e148bSantirez
780a78e148bSantirez          (<span class="type">bool</span>)
781a78e148bSantirez          <code class="literal">r-</code>
782a78e148bSantirez          [<code class="option">--enable-prof</code>]
783a78e148bSantirez        </span></dt><dd><p>Leak reporting enabled/disabled.  If enabled, use an
784a78e148bSantirez        <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function to report memory leaks
785a78e148bSantirez        detected by allocation sampling.  See the
786a78e148bSantirez        <a class="link" href="#opt.prof">
787a78e148bSantirez    "<code class="mallctl">opt.prof</code>"
788a78e148bSantirez  </a> option for
789a78e148bSantirez        information on analyzing heap profile output.  This option is disabled
790fceef8e0Santirez        by default.</p></dd><dt><a name="thread.arena"></a><span class="term">
791a78e148bSantirez
792a78e148bSantirez    "<code class="mallctl">thread.arena</code>"
793a78e148bSantirez
794a78e148bSantirez          (<span class="type">unsigned</span>)
795a78e148bSantirez          <code class="literal">rw</code>
796a78e148bSantirez        </span></dt><dd><p>Get or set the arena associated with the calling
7977383c3b1Santirez        thread.  If the specified arena was not initialized beforehand (see the
7987383c3b1Santirez        <a class="link" href="#arenas.initialized">
799a78e148bSantirez    "<code class="mallctl">arenas.initialized</code>"
800a78e148bSantirez  </a>
801a78e148bSantirez        mallctl), it will be automatically initialized as a side effect of
802a78e148bSantirez        calling this interface.</p></dd><dt><a name="thread.allocated"></a><span class="term">
803a78e148bSantirez
804a78e148bSantirez    "<code class="mallctl">thread.allocated</code>"
805a78e148bSantirez
806a78e148bSantirez          (<span class="type">uint64_t</span>)
807a78e148bSantirez          <code class="literal">r-</code>
808a78e148bSantirez          [<code class="option">--enable-stats</code>]
809a78e148bSantirez        </span></dt><dd><p>Get the total number of bytes ever allocated by the
810a78e148bSantirez        calling thread.  This counter has the potential to wrap around; it is
811a78e148bSantirez        up to the application to appropriately interpret the counter in such
812fceef8e0Santirez        cases.</p></dd><dt><a name="thread.allocatedp"></a><span class="term">
813a78e148bSantirez
814a78e148bSantirez    "<code class="mallctl">thread.allocatedp</code>"
815a78e148bSantirez
816a78e148bSantirez          (<span class="type">uint64_t *</span>)
817a78e148bSantirez          <code class="literal">r-</code>
818a78e148bSantirez          [<code class="option">--enable-stats</code>]
819a78e148bSantirez        </span></dt><dd><p>Get a pointer to the the value that is returned by the
820a78e148bSantirez        <a class="link" href="#thread.allocated">
821a78e148bSantirez    "<code class="mallctl">thread.allocated</code>"
822a78e148bSantirez  </a>
823a78e148bSantirez        mallctl.  This is useful for avoiding the overhead of repeated
824a78e148bSantirez        <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) calls.</p></dd><dt><a name="thread.deallocated"></a><span class="term">
825a78e148bSantirez
826a78e148bSantirez    "<code class="mallctl">thread.deallocated</code>"
827a78e148bSantirez
828a78e148bSantirez          (<span class="type">uint64_t</span>)
829a78e148bSantirez          <code class="literal">r-</code>
830a78e148bSantirez          [<code class="option">--enable-stats</code>]
831a78e148bSantirez        </span></dt><dd><p>Get the total number of bytes ever deallocated by the
832a78e148bSantirez        calling thread.  This counter has the potential to wrap around; it is
833a78e148bSantirez        up to the application to appropriately interpret the counter in such
834fceef8e0Santirez        cases.</p></dd><dt><a name="thread.deallocatedp"></a><span class="term">
835a78e148bSantirez
836a78e148bSantirez    "<code class="mallctl">thread.deallocatedp</code>"
837a78e148bSantirez
838a78e148bSantirez          (<span class="type">uint64_t *</span>)
839a78e148bSantirez          <code class="literal">r-</code>
840a78e148bSantirez          [<code class="option">--enable-stats</code>]
841a78e148bSantirez        </span></dt><dd><p>Get a pointer to the the value that is returned by the
842a78e148bSantirez        <a class="link" href="#thread.deallocated">
843a78e148bSantirez    "<code class="mallctl">thread.deallocated</code>"
844a78e148bSantirez  </a>
845a78e148bSantirez        mallctl.  This is useful for avoiding the overhead of repeated
846fceef8e0Santirez        <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) calls.</p></dd><dt><a name="thread.tcache.enabled"></a><span class="term">
847ad4c0b41Santirez
848ad4c0b41Santirez    "<code class="mallctl">thread.tcache.enabled</code>"
849ad4c0b41Santirez
850ad4c0b41Santirez          (<span class="type">bool</span>)
851ad4c0b41Santirez          <code class="literal">rw</code>
852ad4c0b41Santirez          [<code class="option">--enable-tcache</code>]
853ad4c0b41Santirez        </span></dt><dd><p>Enable/disable calling thread's tcache.  The tcache is
854ad4c0b41Santirez        implicitly flushed as a side effect of becoming
855*5268379eSantirez        disabled (see <a class="link" href="#thread.tcache.flush">
856ad4c0b41Santirez    "<code class="mallctl">thread.tcache.flush</code>"
857*5268379eSantirez  </a>).
858fceef8e0Santirez        </p></dd><dt><a name="thread.tcache.flush"></a><span class="term">
859ad4c0b41Santirez
860ad4c0b41Santirez    "<code class="mallctl">thread.tcache.flush</code>"
861ad4c0b41Santirez
862ad4c0b41Santirez          (<span class="type">void</span>)
863ad4c0b41Santirez          <code class="literal">--</code>
864ad4c0b41Santirez          [<code class="option">--enable-tcache</code>]
865*5268379eSantirez        </span></dt><dd><p>Flush calling thread's thread-specific cache (tcache).
866*5268379eSantirez        This interface releases all cached objects and internal data structures
867*5268379eSantirez        associated with the calling thread's tcache.  Ordinarily, this interface
868ad4c0b41Santirez        need not be called, since automatic periodic incremental garbage
869ad4c0b41Santirez        collection occurs, and the thread cache is automatically discarded when
870ad4c0b41Santirez        a thread exits.  However, garbage collection is triggered by allocation
871ad4c0b41Santirez        activity, so it is possible for a thread that stops
872ad4c0b41Santirez        allocating/deallocating to retain its cache indefinitely, in which case
873*5268379eSantirez        the developer may find manual flushing useful.</p></dd><dt><a name="thread.prof.name"></a><span class="term">
874*5268379eSantirez
875*5268379eSantirez    "<code class="mallctl">thread.prof.name</code>"
876*5268379eSantirez
877*5268379eSantirez          (<span class="type">const char *</span>)
878*5268379eSantirez          <code class="literal">r-</code> or
879*5268379eSantirez          <code class="literal">-w</code>
880*5268379eSantirez          [<code class="option">--enable-prof</code>]
881*5268379eSantirez        </span></dt><dd><p>Get/set the descriptive name associated with the calling
882*5268379eSantirez        thread in memory profile dumps.  An internal copy of the name string is
883*5268379eSantirez        created, so the input string need not be maintained after this interface
884*5268379eSantirez        completes execution.  The output string of this interface should be
885*5268379eSantirez        copied for non-ephemeral uses, because multiple implementation details
886*5268379eSantirez        can cause asynchronous string deallocation.  Furthermore, each
887*5268379eSantirez        invocation of this interface can only read or write; simultaneous
888*5268379eSantirez        read/write is not supported due to string lifetime limitations.  The
889*5268379eSantirez        name string must nil-terminated and comprised only of characters in the
890*5268379eSantirez        sets recognized
891*5268379eSantirez        by <span class="citerefentry"><span class="refentrytitle">isgraph</span>(3)</span> and
892*5268379eSantirez        <span class="citerefentry"><span class="refentrytitle">isblank</span>(3)</span>.</p></dd><dt><a name="thread.prof.active"></a><span class="term">
893*5268379eSantirez
894*5268379eSantirez    "<code class="mallctl">thread.prof.active</code>"
895*5268379eSantirez
896*5268379eSantirez          (<span class="type">bool</span>)
897*5268379eSantirez          <code class="literal">rw</code>
898*5268379eSantirez          [<code class="option">--enable-prof</code>]
899*5268379eSantirez        </span></dt><dd><p>Control whether sampling is currently active for the
900*5268379eSantirez        calling thread.  This is an activation mechanism in addition to <a class="link" href="#prof.active">
901*5268379eSantirez    "<code class="mallctl">prof.active</code>"
902*5268379eSantirez  </a>; both must
903*5268379eSantirez        be active for the calling thread to sample.  This flag is enabled by
904*5268379eSantirez        default.</p></dd><dt><a name="tcache.create"></a><span class="term">
905*5268379eSantirez
906*5268379eSantirez    "<code class="mallctl">tcache.create</code>"
907*5268379eSantirez
908*5268379eSantirez          (<span class="type">unsigned</span>)
909*5268379eSantirez          <code class="literal">r-</code>
910*5268379eSantirez          [<code class="option">--enable-tcache</code>]
911*5268379eSantirez        </span></dt><dd><p>Create an explicit thread-specific cache (tcache) and
912*5268379eSantirez        return an identifier that can be passed to the <a class="link" href="#MALLOCX_TCACHE"><code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)</code></a>
913*5268379eSantirez        macro to explicitly use the specified cache rather than the
914*5268379eSantirez        automatically managed one that is used by default.  Each explicit cache
915*5268379eSantirez        can be used by only one thread at a time; the application must assure
916*5268379eSantirez        that this constraint holds.
917*5268379eSantirez        </p></dd><dt><a name="tcache.flush"></a><span class="term">
918*5268379eSantirez
919*5268379eSantirez    "<code class="mallctl">tcache.flush</code>"
920*5268379eSantirez
921*5268379eSantirez          (<span class="type">unsigned</span>)
922*5268379eSantirez          <code class="literal">-w</code>
923*5268379eSantirez          [<code class="option">--enable-tcache</code>]
924*5268379eSantirez        </span></dt><dd><p>Flush the specified thread-specific cache (tcache).  The
925*5268379eSantirez        same considerations apply to this interface as to <a class="link" href="#thread.tcache.flush">
926*5268379eSantirez    "<code class="mallctl">thread.tcache.flush</code>"
927*5268379eSantirez  </a>,
928*5268379eSantirez        except that the tcache will never be automatically be discarded.
929*5268379eSantirez        </p></dd><dt><a name="tcache.destroy"></a><span class="term">
930*5268379eSantirez
931*5268379eSantirez    "<code class="mallctl">tcache.destroy</code>"
932*5268379eSantirez
933*5268379eSantirez          (<span class="type">unsigned</span>)
934*5268379eSantirez          <code class="literal">-w</code>
935*5268379eSantirez          [<code class="option">--enable-tcache</code>]
936*5268379eSantirez        </span></dt><dd><p>Flush the specified thread-specific cache (tcache) and
937*5268379eSantirez        make the identifier available for use during a future tcache creation.
938*5268379eSantirez        </p></dd><dt><a name="arena.i.purge"></a><span class="term">
9397383c3b1Santirez
9407383c3b1Santirez    "<code class="mallctl">arena.&lt;i&gt;.purge</code>"
9417383c3b1Santirez
942*5268379eSantirez          (<span class="type">void</span>)
9437383c3b1Santirez          <code class="literal">--</code>
9447383c3b1Santirez        </span></dt><dd><p>Purge unused dirty pages for arena &lt;i&gt;, or for
9457383c3b1Santirez        all arenas if &lt;i&gt; equals <a class="link" href="#arenas.narenas">
9467383c3b1Santirez    "<code class="mallctl">arenas.narenas</code>"
9477383c3b1Santirez  </a>.
9487383c3b1Santirez        </p></dd><dt><a name="arena.i.dss"></a><span class="term">
9497383c3b1Santirez
9507383c3b1Santirez    "<code class="mallctl">arena.&lt;i&gt;.dss</code>"
9517383c3b1Santirez
9527383c3b1Santirez          (<span class="type">const char *</span>)
9537383c3b1Santirez          <code class="literal">rw</code>
9547383c3b1Santirez        </span></dt><dd><p>Set the precedence of dss allocation as related to mmap
9557383c3b1Santirez        allocation for arena &lt;i&gt;, or for all arenas if &lt;i&gt; equals
9567383c3b1Santirez        <a class="link" href="#arenas.narenas">
9577383c3b1Santirez    "<code class="mallctl">arenas.narenas</code>"
958*5268379eSantirez  </a>.  See
959*5268379eSantirez        <a class="link" href="#opt.dss">
9607383c3b1Santirez    "<code class="mallctl">opt.dss</code>"
9617383c3b1Santirez  </a> for supported
962*5268379eSantirez        settings.</p></dd><dt><a name="arena.i.lg_dirty_mult"></a><span class="term">
963*5268379eSantirez
964*5268379eSantirez    "<code class="mallctl">arena.&lt;i&gt;.lg_dirty_mult</code>"
965*5268379eSantirez
966*5268379eSantirez          (<span class="type">ssize_t</span>)
967*5268379eSantirez          <code class="literal">rw</code>
968*5268379eSantirez        </span></dt><dd><p>Current per-arena minimum ratio (log base 2) of active
969*5268379eSantirez        to dirty pages for arena &lt;i&gt;.  Each time this interface is set and
970*5268379eSantirez        the ratio is increased, pages are synchronously purged as necessary to
971*5268379eSantirez        impose the new ratio.  See <a class="link" href="#opt.lg_dirty_mult">
972*5268379eSantirez    "<code class="mallctl">opt.lg_dirty_mult</code>"
973*5268379eSantirez  </a>
974*5268379eSantirez        for additional information.</p></dd><dt><a name="arena.i.chunk_hooks"></a><span class="term">
975*5268379eSantirez
976*5268379eSantirez    "<code class="mallctl">arena.&lt;i&gt;.chunk_hooks</code>"
977*5268379eSantirez
978*5268379eSantirez          (<span class="type">chunk_hooks_t</span>)
979*5268379eSantirez          <code class="literal">rw</code>
980*5268379eSantirez        </span></dt><dd><p>Get or set the chunk management hook functions for arena
981*5268379eSantirez        &lt;i&gt;.  The functions must be capable of operating on all extant
982*5268379eSantirez        chunks associated with arena &lt;i&gt;, usually by passing unknown
983*5268379eSantirez        chunks to the replaced functions.  In practice, it is feasible to
984*5268379eSantirez        control allocation for arenas created via <a class="link" href="#arenas.extend">
985*5268379eSantirez    "<code class="mallctl">arenas.extend</code>"
986*5268379eSantirez  </a> such
987*5268379eSantirez        that all chunks originate from an application-supplied chunk allocator
988*5268379eSantirez        (by setting custom chunk hook functions just after arena creation), but
989*5268379eSantirez        the automatically created arenas may have already created chunks prior
990*5268379eSantirez        to the application having an opportunity to take over chunk
991*5268379eSantirez        allocation.</p><pre class="programlisting">
992*5268379eSantireztypedef struct {
993*5268379eSantirez	chunk_alloc_t		*alloc;
994*5268379eSantirez	chunk_dalloc_t		*dalloc;
995*5268379eSantirez	chunk_commit_t		*commit;
996*5268379eSantirez	chunk_decommit_t	*decommit;
997*5268379eSantirez	chunk_purge_t		*purge;
998*5268379eSantirez	chunk_split_t		*split;
999*5268379eSantirez	chunk_merge_t		*merge;
1000*5268379eSantirez} chunk_hooks_t;</pre><p>The <span class="type">chunk_hooks_t</span> structure comprises function
1001*5268379eSantirez        pointers which are described individually below.  jemalloc uses these
1002*5268379eSantirez        functions to manage chunk lifetime, which starts off with allocation of
1003*5268379eSantirez        mapped committed memory, in the simplest case followed by deallocation.
1004*5268379eSantirez        However, there are performance and platform reasons to retain chunks for
1005*5268379eSantirez        later reuse.  Cleanup attempts cascade from deallocation to decommit to
1006*5268379eSantirez        purging, which gives the chunk management functions opportunities to
1007*5268379eSantirez        reject the most permanent cleanup operations in favor of less permanent
1008*5268379eSantirez        (and often less costly) operations.  The chunk splitting and merging
1009*5268379eSantirez        operations can also be opted out of, but this is mainly intended to
1010*5268379eSantirez        support platforms on which virtual memory mappings provided by the
1011*5268379eSantirez        operating system kernel do not automatically coalesce and split, e.g.
1012*5268379eSantirez        Windows.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef void *<b class="fsfunc">(chunk_alloc_t)</b>(</code></td><td>void *<var class="pdparam">chunk</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">alignment</var>, </td></tr><tr><td>�</td><td>bool *<var class="pdparam">zero</var>, </td></tr><tr><td>�</td><td>bool *<var class="pdparam">commit</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk allocation function conforms to the
1013*5268379eSantirez        <span class="type">chunk_alloc_t</span> type and upon success returns a pointer to
1014*5268379eSantirez        <em class="parameter"><code>size</code></em> bytes of mapped memory on behalf of arena
1015*5268379eSantirez        <em class="parameter"><code>arena_ind</code></em> such that the chunk's base address is a
1016*5268379eSantirez        multiple of <em class="parameter"><code>alignment</code></em>, as well as setting
1017*5268379eSantirez        <em class="parameter"><code>*zero</code></em> to indicate whether the chunk is zeroed and
1018*5268379eSantirez        <em class="parameter"><code>*commit</code></em> to indicate whether the chunk is
1019*5268379eSantirez        committed.  Upon error the function returns <code class="constant">NULL</code>
1020*5268379eSantirez        and leaves <em class="parameter"><code>*zero</code></em> and
1021*5268379eSantirez        <em class="parameter"><code>*commit</code></em> unmodified.  The
1022*5268379eSantirez        <em class="parameter"><code>size</code></em> parameter is always a multiple of the chunk
1023*5268379eSantirez        size.  The <em class="parameter"><code>alignment</code></em> parameter is always a power
1024*5268379eSantirez        of two at least as large as the chunk size.  Zeroing is mandatory if
1025*5268379eSantirez        <em class="parameter"><code>*zero</code></em> is true upon function entry.  Committing is
1026*5268379eSantirez        mandatory if <em class="parameter"><code>*commit</code></em> is true upon function entry.
1027*5268379eSantirez        If <em class="parameter"><code>chunk</code></em> is not <code class="constant">NULL</code>, the
1028*5268379eSantirez        returned pointer must be <em class="parameter"><code>chunk</code></em> on success or
1029*5268379eSantirez        <code class="constant">NULL</code> on error.  Committed memory may be committed
1030*5268379eSantirez        in absolute terms as on a system that does not overcommit, or in
1031*5268379eSantirez        implicit terms as on a system that overcommits and satisfies physical
1032*5268379eSantirez        memory needs on demand via soft page faults.  Note that replacing the
1033*5268379eSantirez        default chunk allocation function makes the arena's <a class="link" href="#arena.i.dss">
1034*5268379eSantirez    "<code class="mallctl">arena.&lt;i&gt;.dss</code>"
1035*5268379eSantirez  </a>
1036*5268379eSantirez        setting irrelevant.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_dalloc_t)</b>(</code></td><td>void *<var class="pdparam">chunk</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>bool <var class="pdparam">committed</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>
1037*5268379eSantirez        A chunk deallocation function conforms to the
1038*5268379eSantirez        <span class="type">chunk_dalloc_t</span> type and deallocates a
1039*5268379eSantirez        <em class="parameter"><code>chunk</code></em> of given <em class="parameter"><code>size</code></em> with
1040*5268379eSantirez        <em class="parameter"><code>committed</code></em>/decommited memory as indicated, on
1041*5268379eSantirez        behalf of arena <em class="parameter"><code>arena_ind</code></em>, returning false upon
1042*5268379eSantirez        success.  If the function returns true, this indicates opt-out from
1043*5268379eSantirez        deallocation; the virtual memory mapping associated with the chunk
1044*5268379eSantirez        remains mapped, in the same commit state, and available for future use,
1045*5268379eSantirez        in which case it will be automatically retained for later reuse.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_commit_t)</b>(</code></td><td>void *<var class="pdparam">chunk</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">offset</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">length</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk commit function conforms to the
1046*5268379eSantirez        <span class="type">chunk_commit_t</span> type and commits zeroed physical memory to
1047*5268379eSantirez        back pages within a <em class="parameter"><code>chunk</code></em> of given
1048*5268379eSantirez        <em class="parameter"><code>size</code></em> at <em class="parameter"><code>offset</code></em> bytes,
1049*5268379eSantirez        extending for <em class="parameter"><code>length</code></em> on behalf of arena
1050*5268379eSantirez        <em class="parameter"><code>arena_ind</code></em>, returning false upon success.
1051*5268379eSantirez        Committed memory may be committed in absolute terms as on a system that
1052*5268379eSantirez        does not overcommit, or in implicit terms as on a system that
1053*5268379eSantirez        overcommits and satisfies physical memory needs on demand via soft page
1054*5268379eSantirez        faults. If the function returns true, this indicates insufficient
1055*5268379eSantirez        physical memory to satisfy the request.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_decommit_t)</b>(</code></td><td>void *<var class="pdparam">chunk</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">offset</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">length</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk decommit function conforms to the
1056*5268379eSantirez        <span class="type">chunk_decommit_t</span> type and decommits any physical memory
1057*5268379eSantirez        that is backing pages within a <em class="parameter"><code>chunk</code></em> of given
1058*5268379eSantirez        <em class="parameter"><code>size</code></em> at <em class="parameter"><code>offset</code></em> bytes,
1059*5268379eSantirez        extending for <em class="parameter"><code>length</code></em> on behalf of arena
1060*5268379eSantirez        <em class="parameter"><code>arena_ind</code></em>, returning false upon success, in which
1061*5268379eSantirez        case the pages will be committed via the chunk commit function before
1062*5268379eSantirez        being reused.  If the function returns true, this indicates opt-out from
1063*5268379eSantirez        decommit; the memory remains committed and available for future use, in
1064*5268379eSantirez        which case it will be automatically retained for later reuse.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_purge_t)</b>(</code></td><td>void *<var class="pdparam">chunk</var>, </td></tr><tr><td>�</td><td>size_t<var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">offset</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">length</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk purge function conforms to the <span class="type">chunk_purge_t</span>
1065*5268379eSantirez        type and optionally discards physical pages within the virtual memory
1066*5268379eSantirez        mapping associated with <em class="parameter"><code>chunk</code></em> of given
1067*5268379eSantirez        <em class="parameter"><code>size</code></em> at <em class="parameter"><code>offset</code></em> bytes,
1068*5268379eSantirez        extending for <em class="parameter"><code>length</code></em> on behalf of arena
1069*5268379eSantirez        <em class="parameter"><code>arena_ind</code></em>, returning false if pages within the
1070*5268379eSantirez        purged virtual memory range will be zero-filled the next time they are
1071*5268379eSantirez        accessed.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_split_t)</b>(</code></td><td>void *<var class="pdparam">chunk</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size_a</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size_b</var>, </td></tr><tr><td>�</td><td>bool <var class="pdparam">committed</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk split function conforms to the <span class="type">chunk_split_t</span>
1072*5268379eSantirez        type and optionally splits <em class="parameter"><code>chunk</code></em> of given
1073*5268379eSantirez        <em class="parameter"><code>size</code></em> into two adjacent chunks, the first of
1074*5268379eSantirez        <em class="parameter"><code>size_a</code></em> bytes, and the second of
1075*5268379eSantirez        <em class="parameter"><code>size_b</code></em> bytes, operating on
1076*5268379eSantirez        <em class="parameter"><code>committed</code></em>/decommitted memory as indicated, on
1077*5268379eSantirez        behalf of arena <em class="parameter"><code>arena_ind</code></em>, returning false upon
1078*5268379eSantirez        success.  If the function returns true, this indicates that the chunk
1079*5268379eSantirez        remains unsplit and therefore should continue to be operated on as a
1080*5268379eSantirez        whole.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_merge_t)</b>(</code></td><td>void *<var class="pdparam">chunk_a</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size_a</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">chunk_b</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size_b</var>, </td></tr><tr><td>�</td><td>bool <var class="pdparam">committed</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk merge function conforms to the <span class="type">chunk_merge_t</span>
1081*5268379eSantirez        type and optionally merges adjacent chunks,
1082*5268379eSantirez        <em class="parameter"><code>chunk_a</code></em> of given <em class="parameter"><code>size_a</code></em>
1083*5268379eSantirez        and <em class="parameter"><code>chunk_b</code></em> of given
1084*5268379eSantirez        <em class="parameter"><code>size_b</code></em> into one contiguous chunk, operating on
1085*5268379eSantirez        <em class="parameter"><code>committed</code></em>/decommitted memory as indicated, on
1086*5268379eSantirez        behalf of arena <em class="parameter"><code>arena_ind</code></em>, returning false upon
1087*5268379eSantirez        success.  If the function returns true, this indicates that the chunks
1088*5268379eSantirez        remain distinct mappings and therefore should continue to be operated on
1089*5268379eSantirez        independently.</p></dd><dt><a name="arenas.narenas"></a><span class="term">
1090a78e148bSantirez
1091a78e148bSantirez    "<code class="mallctl">arenas.narenas</code>"
1092a78e148bSantirez
1093a78e148bSantirez          (<span class="type">unsigned</span>)
1094a78e148bSantirez          <code class="literal">r-</code>
10957383c3b1Santirez        </span></dt><dd><p>Current limit on number of arenas.</p></dd><dt><a name="arenas.initialized"></a><span class="term">
1096a78e148bSantirez
1097a78e148bSantirez    "<code class="mallctl">arenas.initialized</code>"
1098a78e148bSantirez
1099a78e148bSantirez          (<span class="type">bool *</span>)
1100a78e148bSantirez          <code class="literal">r-</code>
1101a78e148bSantirez        </span></dt><dd><p>An array of <a class="link" href="#arenas.narenas">
1102a78e148bSantirez    "<code class="mallctl">arenas.narenas</code>"
1103a78e148bSantirez  </a>
1104a78e148bSantirez        booleans.  Each boolean indicates whether the corresponding arena is
1105*5268379eSantirez        initialized.</p></dd><dt><a name="arenas.lg_dirty_mult"></a><span class="term">
1106*5268379eSantirez
1107*5268379eSantirez    "<code class="mallctl">arenas.lg_dirty_mult</code>"
1108*5268379eSantirez
1109*5268379eSantirez          (<span class="type">ssize_t</span>)
1110*5268379eSantirez          <code class="literal">rw</code>
1111*5268379eSantirez        </span></dt><dd><p>Current default per-arena minimum ratio (log base 2) of
1112*5268379eSantirez        active to dirty pages, used to initialize <a class="link" href="#arena.i.lg_dirty_mult">
1113*5268379eSantirez    "<code class="mallctl">arena.&lt;i&gt;.lg_dirty_mult</code>"
1114*5268379eSantirez  </a>
1115*5268379eSantirez        during arena creation.  See <a class="link" href="#opt.lg_dirty_mult">
1116*5268379eSantirez    "<code class="mallctl">opt.lg_dirty_mult</code>"
1117*5268379eSantirez  </a>
1118*5268379eSantirez        for additional information.</p></dd><dt><a name="arenas.quantum"></a><span class="term">
1119a78e148bSantirez
1120a78e148bSantirez    "<code class="mallctl">arenas.quantum</code>"
1121a78e148bSantirez
1122a78e148bSantirez          (<span class="type">size_t</span>)
1123a78e148bSantirez          <code class="literal">r-</code>
1124fceef8e0Santirez        </span></dt><dd><p>Quantum size.</p></dd><dt><a name="arenas.page"></a><span class="term">
1125a78e148bSantirez
1126ad4c0b41Santirez    "<code class="mallctl">arenas.page</code>"
1127a78e148bSantirez
1128a78e148bSantirez          (<span class="type">size_t</span>)
1129a78e148bSantirez          <code class="literal">r-</code>
1130fceef8e0Santirez        </span></dt><dd><p>Page size.</p></dd><dt><a name="arenas.tcache_max"></a><span class="term">
1131a78e148bSantirez
1132a78e148bSantirez    "<code class="mallctl">arenas.tcache_max</code>"
1133a78e148bSantirez
1134a78e148bSantirez          (<span class="type">size_t</span>)
1135a78e148bSantirez          <code class="literal">r-</code>
1136a78e148bSantirez          [<code class="option">--enable-tcache</code>]
1137fceef8e0Santirez        </span></dt><dd><p>Maximum thread-cached size class.</p></dd><dt><a name="arenas.nbins"></a><span class="term">
1138a78e148bSantirez
1139a78e148bSantirez    "<code class="mallctl">arenas.nbins</code>"
1140a78e148bSantirez
1141a78e148bSantirez          (<span class="type">unsigned</span>)
1142a78e148bSantirez          <code class="literal">r-</code>
1143fceef8e0Santirez        </span></dt><dd><p>Number of bin size classes.</p></dd><dt><a name="arenas.nhbins"></a><span class="term">
1144a78e148bSantirez
1145a78e148bSantirez    "<code class="mallctl">arenas.nhbins</code>"
1146a78e148bSantirez
1147a78e148bSantirez          (<span class="type">unsigned</span>)
1148a78e148bSantirez          <code class="literal">r-</code>
1149a78e148bSantirez          [<code class="option">--enable-tcache</code>]
1150a78e148bSantirez        </span></dt><dd><p>Total number of thread cache bin size
1151a78e148bSantirez        classes.</p></dd><dt><a name="arenas.bin.i.size"></a><span class="term">
1152a78e148bSantirez
1153a78e148bSantirez    "<code class="mallctl">arenas.bin.&lt;i&gt;.size</code>"
1154a78e148bSantirez
1155a78e148bSantirez          (<span class="type">size_t</span>)
1156a78e148bSantirez          <code class="literal">r-</code>
1157fceef8e0Santirez        </span></dt><dd><p>Maximum size supported by size class.</p></dd><dt><a name="arenas.bin.i.nregs"></a><span class="term">
1158a78e148bSantirez
1159a78e148bSantirez    "<code class="mallctl">arenas.bin.&lt;i&gt;.nregs</code>"
1160a78e148bSantirez
1161a78e148bSantirez          (<span class="type">uint32_t</span>)
1162a78e148bSantirez          <code class="literal">r-</code>
1163fceef8e0Santirez        </span></dt><dd><p>Number of regions per page run.</p></dd><dt><a name="arenas.bin.i.run_size"></a><span class="term">
1164a78e148bSantirez
1165a78e148bSantirez    "<code class="mallctl">arenas.bin.&lt;i&gt;.run_size</code>"
1166a78e148bSantirez
1167a78e148bSantirez          (<span class="type">size_t</span>)
1168a78e148bSantirez          <code class="literal">r-</code>
1169fceef8e0Santirez        </span></dt><dd><p>Number of bytes per page run.</p></dd><dt><a name="arenas.nlruns"></a><span class="term">
1170a78e148bSantirez
1171a78e148bSantirez    "<code class="mallctl">arenas.nlruns</code>"
1172a78e148bSantirez
1173*5268379eSantirez          (<span class="type">unsigned</span>)
1174a78e148bSantirez          <code class="literal">r-</code>
1175fceef8e0Santirez        </span></dt><dd><p>Total number of large size classes.</p></dd><dt><a name="arenas.lrun.i.size"></a><span class="term">
1176a78e148bSantirez
1177a78e148bSantirez    "<code class="mallctl">arenas.lrun.&lt;i&gt;.size</code>"
1178a78e148bSantirez
1179a78e148bSantirez          (<span class="type">size_t</span>)
1180a78e148bSantirez          <code class="literal">r-</code>
1181a78e148bSantirez        </span></dt><dd><p>Maximum size supported by this large size
1182*5268379eSantirez        class.</p></dd><dt><a name="arenas.nhchunks"></a><span class="term">
1183a78e148bSantirez
1184*5268379eSantirez    "<code class="mallctl">arenas.nhchunks</code>"
1185a78e148bSantirez
1186a78e148bSantirez          (<span class="type">unsigned</span>)
1187*5268379eSantirez          <code class="literal">r-</code>
1188*5268379eSantirez        </span></dt><dd><p>Total number of huge size classes.</p></dd><dt><a name="arenas.hchunk.i.size"></a><span class="term">
1189*5268379eSantirez
1190*5268379eSantirez    "<code class="mallctl">arenas.hchunk.&lt;i&gt;.size</code>"
1191*5268379eSantirez
1192*5268379eSantirez          (<span class="type">size_t</span>)
1193*5268379eSantirez          <code class="literal">r-</code>
1194*5268379eSantirez        </span></dt><dd><p>Maximum size supported by this huge size
1195*5268379eSantirez        class.</p></dd><dt><a name="arenas.extend"></a><span class="term">
11967383c3b1Santirez
11977383c3b1Santirez    "<code class="mallctl">arenas.extend</code>"
11987383c3b1Santirez
11997383c3b1Santirez          (<span class="type">unsigned</span>)
12007383c3b1Santirez          <code class="literal">r-</code>
12017383c3b1Santirez        </span></dt><dd><p>Extend the array of arenas by appending a new arena,
1202*5268379eSantirez        and returning the new arena index.</p></dd><dt><a name="prof.thread_active_init"></a><span class="term">
1203*5268379eSantirez
1204*5268379eSantirez    "<code class="mallctl">prof.thread_active_init</code>"
1205*5268379eSantirez
1206*5268379eSantirez          (<span class="type">bool</span>)
1207*5268379eSantirez          <code class="literal">rw</code>
1208*5268379eSantirez          [<code class="option">--enable-prof</code>]
1209*5268379eSantirez        </span></dt><dd><p>Control the initial setting for <a class="link" href="#thread.prof.active">
1210*5268379eSantirez    "<code class="mallctl">thread.prof.active</code>"
1211*5268379eSantirez  </a>
1212*5268379eSantirez        in newly created threads.  See the <a class="link" href="#opt.prof_thread_active_init">
1213*5268379eSantirez    "<code class="mallctl">opt.prof_thread_active_init</code>"
1214*5268379eSantirez  </a>
1215*5268379eSantirez        option for additional information.</p></dd><dt><a name="prof.active"></a><span class="term">
1216a78e148bSantirez
1217a78e148bSantirez    "<code class="mallctl">prof.active</code>"
1218a78e148bSantirez
1219a78e148bSantirez          (<span class="type">bool</span>)
1220a78e148bSantirez          <code class="literal">rw</code>
1221a78e148bSantirez          [<code class="option">--enable-prof</code>]
1222a78e148bSantirez        </span></dt><dd><p>Control whether sampling is currently active.  See the
1223a78e148bSantirez        <a class="link" href="#opt.prof_active">
1224a78e148bSantirez    "<code class="mallctl">opt.prof_active</code>"
1225a78e148bSantirez  </a>
1226*5268379eSantirez        option for additional information, as well as the interrelated <a class="link" href="#thread.prof.active">
1227*5268379eSantirez    "<code class="mallctl">thread.prof.active</code>"
1228*5268379eSantirez  </a>
1229*5268379eSantirez        mallctl.</p></dd><dt><a name="prof.dump"></a><span class="term">
1230a78e148bSantirez
1231a78e148bSantirez    "<code class="mallctl">prof.dump</code>"
1232a78e148bSantirez
1233a78e148bSantirez          (<span class="type">const char *</span>)
1234a78e148bSantirez          <code class="literal">-w</code>
1235a78e148bSantirez          [<code class="option">--enable-prof</code>]
1236a78e148bSantirez        </span></dt><dd><p>Dump a memory profile to the specified file, or if NULL
1237a78e148bSantirez        is specified, to a file according to the pattern
1238a78e148bSantirez        <code class="filename">&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.m&lt;mseq&gt;.heap</code>,
1239a78e148bSantirez        where <code class="literal">&lt;prefix&gt;</code> is controlled by the
1240a78e148bSantirez        <a class="link" href="#opt.prof_prefix">
1241a78e148bSantirez    "<code class="mallctl">opt.prof_prefix</code>"
1242a78e148bSantirez  </a>
1243*5268379eSantirez        option.</p></dd><dt><a name="prof.gdump"></a><span class="term">
1244*5268379eSantirez
1245*5268379eSantirez    "<code class="mallctl">prof.gdump</code>"
1246*5268379eSantirez
1247*5268379eSantirez          (<span class="type">bool</span>)
1248*5268379eSantirez          <code class="literal">rw</code>
1249*5268379eSantirez          [<code class="option">--enable-prof</code>]
1250*5268379eSantirez        </span></dt><dd><p>When enabled, trigger a memory profile dump every time
1251*5268379eSantirez        the total virtual memory exceeds the previous maximum.  Profiles are
1252*5268379eSantirez        dumped to files named according to the pattern
1253*5268379eSantirez        <code class="filename">&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.u&lt;useq&gt;.heap</code>,
1254*5268379eSantirez        where <code class="literal">&lt;prefix&gt;</code> is controlled by the <a class="link" href="#opt.prof_prefix">
1255*5268379eSantirez    "<code class="mallctl">opt.prof_prefix</code>"
1256*5268379eSantirez  </a>
1257*5268379eSantirez        option.</p></dd><dt><a name="prof.reset"></a><span class="term">
1258*5268379eSantirez
1259*5268379eSantirez    "<code class="mallctl">prof.reset</code>"
1260*5268379eSantirez
1261*5268379eSantirez          (<span class="type">size_t</span>)
1262*5268379eSantirez          <code class="literal">-w</code>
1263*5268379eSantirez          [<code class="option">--enable-prof</code>]
1264*5268379eSantirez        </span></dt><dd><p>Reset all memory profile statistics, and optionally
1265*5268379eSantirez        update the sample rate (see <a class="link" href="#opt.lg_prof_sample">
1266*5268379eSantirez    "<code class="mallctl">opt.lg_prof_sample</code>"
1267*5268379eSantirez  </a>
1268*5268379eSantirez        and <a class="link" href="#prof.lg_sample">
1269*5268379eSantirez    "<code class="mallctl">prof.lg_sample</code>"
1270*5268379eSantirez  </a>).
1271*5268379eSantirez        </p></dd><dt><a name="prof.lg_sample"></a><span class="term">
1272*5268379eSantirez
1273*5268379eSantirez    "<code class="mallctl">prof.lg_sample</code>"
1274*5268379eSantirez
1275*5268379eSantirez          (<span class="type">size_t</span>)
1276*5268379eSantirez          <code class="literal">r-</code>
1277*5268379eSantirez          [<code class="option">--enable-prof</code>]
1278*5268379eSantirez        </span></dt><dd><p>Get the current sample rate (see <a class="link" href="#opt.lg_prof_sample">
1279*5268379eSantirez    "<code class="mallctl">opt.lg_prof_sample</code>"
1280*5268379eSantirez  </a>).
1281*5268379eSantirez        </p></dd><dt><a name="prof.interval"></a><span class="term">
1282a78e148bSantirez
1283a78e148bSantirez    "<code class="mallctl">prof.interval</code>"
1284a78e148bSantirez
1285a78e148bSantirez          (<span class="type">uint64_t</span>)
1286a78e148bSantirez          <code class="literal">r-</code>
1287a78e148bSantirez          [<code class="option">--enable-prof</code>]
1288a78e148bSantirez        </span></dt><dd><p>Average number of bytes allocated between
1289a78e148bSantirez        inverval-based profile dumps.  See the
1290a78e148bSantirez        <a class="link" href="#opt.lg_prof_interval">
1291a78e148bSantirez    "<code class="mallctl">opt.lg_prof_interval</code>"
1292a78e148bSantirez  </a>
1293a78e148bSantirez        option for additional information.</p></dd><dt><a name="stats.cactive"></a><span class="term">
1294a78e148bSantirez
1295a78e148bSantirez    "<code class="mallctl">stats.cactive</code>"
1296a78e148bSantirez
1297a78e148bSantirez          (<span class="type">size_t *</span>)
1298a78e148bSantirez          <code class="literal">r-</code>
1299a78e148bSantirez          [<code class="option">--enable-stats</code>]
1300a78e148bSantirez        </span></dt><dd><p>Pointer to a counter that contains an approximate count
1301a78e148bSantirez        of the current number of bytes in active pages.  The estimate may be
1302*5268379eSantirez        high, but never low, because each arena rounds up when computing its
1303*5268379eSantirez        contribution to the counter.  Note that the <a class="link" href="#epoch">
1304a78e148bSantirez    "<code class="mallctl">epoch</code>"
1305a78e148bSantirez  </a> mallctl has no bearing
1306a78e148bSantirez        on this counter.  Furthermore, counter consistency is maintained via
1307a78e148bSantirez        atomic operations, so it is necessary to use an atomic operation in
1308a78e148bSantirez        order to guarantee a consistent read when dereferencing the pointer.
1309a78e148bSantirez        </p></dd><dt><a name="stats.allocated"></a><span class="term">
1310a78e148bSantirez
1311a78e148bSantirez    "<code class="mallctl">stats.allocated</code>"
1312a78e148bSantirez
1313a78e148bSantirez          (<span class="type">size_t</span>)
1314a78e148bSantirez          <code class="literal">r-</code>
1315a78e148bSantirez          [<code class="option">--enable-stats</code>]
1316a78e148bSantirez        </span></dt><dd><p>Total number of bytes allocated by the
1317a78e148bSantirez        application.</p></dd><dt><a name="stats.active"></a><span class="term">
1318a78e148bSantirez
1319a78e148bSantirez    "<code class="mallctl">stats.active</code>"
1320a78e148bSantirez
1321a78e148bSantirez          (<span class="type">size_t</span>)
1322a78e148bSantirez          <code class="literal">r-</code>
1323a78e148bSantirez          [<code class="option">--enable-stats</code>]
1324a78e148bSantirez        </span></dt><dd><p>Total number of bytes in active pages allocated by the
1325a78e148bSantirez        application.  This is a multiple of the page size, and greater than or
1326a78e148bSantirez        equal to <a class="link" href="#stats.allocated">
1327a78e148bSantirez    "<code class="mallctl">stats.allocated</code>"
1328a78e148bSantirez  </a>.
13297383c3b1Santirez        This does not include <a class="link" href="#stats.arenas.i.pdirty">
13307383c3b1Santirez
13317383c3b1Santirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.pdirty</code>"
1332*5268379eSantirez  </a>, nor pages
1333*5268379eSantirez        entirely devoted to allocator metadata.</p></dd><dt><a name="stats.metadata"></a><span class="term">
1334*5268379eSantirez
1335*5268379eSantirez    "<code class="mallctl">stats.metadata</code>"
1336*5268379eSantirez
1337*5268379eSantirez          (<span class="type">size_t</span>)
1338*5268379eSantirez          <code class="literal">r-</code>
1339*5268379eSantirez          [<code class="option">--enable-stats</code>]
1340*5268379eSantirez        </span></dt><dd><p>Total number of bytes dedicated to metadata, which
1341*5268379eSantirez        comprise base allocations used for bootstrap-sensitive internal
1342*5268379eSantirez        allocator data structures, arena chunk headers (see <a class="link" href="#stats.arenas.i.metadata.mapped">
1343*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.metadata.mapped</code>"
1344*5268379eSantirez  </a>),
1345*5268379eSantirez        and internal allocations (see <a class="link" href="#stats.arenas.i.metadata.allocated">
1346*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.metadata.allocated</code>"
1347*5268379eSantirez  </a>).</p></dd><dt><a name="stats.resident"></a><span class="term">
1348*5268379eSantirez
1349*5268379eSantirez    "<code class="mallctl">stats.resident</code>"
1350*5268379eSantirez
1351*5268379eSantirez          (<span class="type">size_t</span>)
1352*5268379eSantirez          <code class="literal">r-</code>
1353*5268379eSantirez          [<code class="option">--enable-stats</code>]
1354*5268379eSantirez        </span></dt><dd><p>Maximum number of bytes in physically resident data
1355*5268379eSantirez        pages mapped by the allocator, comprising all pages dedicated to
1356*5268379eSantirez        allocator metadata, pages backing active allocations, and unused dirty
1357*5268379eSantirez        pages.  This is a maximum rather than precise because pages may not
1358*5268379eSantirez        actually be physically resident if they correspond to demand-zeroed
1359*5268379eSantirez        virtual memory that has not yet been touched.  This is a multiple of the
1360*5268379eSantirez        page size, and is larger than <a class="link" href="#stats.active">
1361*5268379eSantirez    "<code class="mallctl">stats.active</code>"
1362*5268379eSantirez  </a>.</p></dd><dt><a name="stats.mapped"></a><span class="term">
1363a78e148bSantirez
1364a78e148bSantirez    "<code class="mallctl">stats.mapped</code>"
1365a78e148bSantirez
1366a78e148bSantirez          (<span class="type">size_t</span>)
1367a78e148bSantirez          <code class="literal">r-</code>
1368a78e148bSantirez          [<code class="option">--enable-stats</code>]
1369*5268379eSantirez        </span></dt><dd><p>Total number of bytes in active chunks mapped by the
1370*5268379eSantirez        allocator.  This is a multiple of the chunk size, and is larger than
1371*5268379eSantirez        <a class="link" href="#stats.active">
1372a78e148bSantirez    "<code class="mallctl">stats.active</code>"
1373*5268379eSantirez  </a>.
1374*5268379eSantirez        This does not include inactive chunks, even those that contain unused
1375*5268379eSantirez        dirty pages, which means that there is no strict ordering between this
1376*5268379eSantirez        and <a class="link" href="#stats.resident">
1377*5268379eSantirez    "<code class="mallctl">stats.resident</code>"
1378*5268379eSantirez  </a>.</p></dd><dt><a name="stats.arenas.i.dss"></a><span class="term">
1379a78e148bSantirez
13807383c3b1Santirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.dss</code>"
13817383c3b1Santirez
13827383c3b1Santirez          (<span class="type">const char *</span>)
13837383c3b1Santirez          <code class="literal">r-</code>
13847383c3b1Santirez        </span></dt><dd><p>dss (<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>) allocation precedence as
13857383c3b1Santirez        related to <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> allocation.  See <a class="link" href="#opt.dss">
13867383c3b1Santirez    "<code class="mallctl">opt.dss</code>"
13877383c3b1Santirez  </a> for details.
1388*5268379eSantirez        </p></dd><dt><a name="stats.arenas.i.lg_dirty_mult"></a><span class="term">
1389*5268379eSantirez
1390*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lg_dirty_mult</code>"
1391*5268379eSantirez
1392*5268379eSantirez          (<span class="type">ssize_t</span>)
1393*5268379eSantirez          <code class="literal">r-</code>
1394*5268379eSantirez        </span></dt><dd><p>Minimum ratio (log base 2) of active to dirty pages.
1395*5268379eSantirez        See <a class="link" href="#opt.lg_dirty_mult">
1396*5268379eSantirez    "<code class="mallctl">opt.lg_dirty_mult</code>"
1397*5268379eSantirez  </a>
1398*5268379eSantirez        for details.</p></dd><dt><a name="stats.arenas.i.nthreads"></a><span class="term">
13997383c3b1Santirez
1400a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.nthreads</code>"
1401a78e148bSantirez
1402a78e148bSantirez          (<span class="type">unsigned</span>)
1403a78e148bSantirez          <code class="literal">r-</code>
1404a78e148bSantirez        </span></dt><dd><p>Number of threads currently assigned to
1405fceef8e0Santirez        arena.</p></dd><dt><a name="stats.arenas.i.pactive"></a><span class="term">
1406a78e148bSantirez
1407a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.pactive</code>"
1408a78e148bSantirez
1409a78e148bSantirez          (<span class="type">size_t</span>)
1410a78e148bSantirez          <code class="literal">r-</code>
14117383c3b1Santirez        </span></dt><dd><p>Number of pages in active runs.</p></dd><dt><a name="stats.arenas.i.pdirty"></a><span class="term">
1412a78e148bSantirez
1413a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.pdirty</code>"
1414a78e148bSantirez
1415a78e148bSantirez          (<span class="type">size_t</span>)
1416a78e148bSantirez          <code class="literal">r-</code>
1417a78e148bSantirez        </span></dt><dd><p>Number of pages within unused runs that are potentially
1418a78e148bSantirez        dirty, and for which <code class="function">madvise</code>(<em class="parameter"><code>...</code></em>,
1419a78e148bSantirez        <em class="parameter"><code><code class="constant">MADV_DONTNEED</code></code></em>) or
1420fceef8e0Santirez        similar has not been called.</p></dd><dt><a name="stats.arenas.i.mapped"></a><span class="term">
1421a78e148bSantirez
1422a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.mapped</code>"
1423a78e148bSantirez
1424a78e148bSantirez          (<span class="type">size_t</span>)
1425a78e148bSantirez          <code class="literal">r-</code>
1426a78e148bSantirez          [<code class="option">--enable-stats</code>]
1427*5268379eSantirez        </span></dt><dd><p>Number of mapped bytes.</p></dd><dt><a name="stats.arenas.i.metadata.mapped"></a><span class="term">
1428*5268379eSantirez
1429*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.metadata.mapped</code>"
1430*5268379eSantirez
1431*5268379eSantirez          (<span class="type">size_t</span>)
1432*5268379eSantirez          <code class="literal">r-</code>
1433*5268379eSantirez          [<code class="option">--enable-stats</code>]
1434*5268379eSantirez        </span></dt><dd><p>Number of mapped bytes in arena chunk headers, which
1435*5268379eSantirez        track the states of the non-metadata pages.</p></dd><dt><a name="stats.arenas.i.metadata.allocated"></a><span class="term">
1436*5268379eSantirez
1437*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.metadata.allocated</code>"
1438*5268379eSantirez
1439*5268379eSantirez          (<span class="type">size_t</span>)
1440*5268379eSantirez          <code class="literal">r-</code>
1441*5268379eSantirez          [<code class="option">--enable-stats</code>]
1442*5268379eSantirez        </span></dt><dd><p>Number of bytes dedicated to internal allocations.
1443*5268379eSantirez        Internal allocations differ from application-originated allocations in
1444*5268379eSantirez        that they are for internal use, and that they are omitted from heap
1445*5268379eSantirez        profiles.  This statistic is reported separately from <a class="link" href="#stats.metadata">
1446*5268379eSantirez    "<code class="mallctl">stats.metadata</code>"
1447*5268379eSantirez  </a> and
1448*5268379eSantirez        <a class="link" href="#stats.arenas.i.metadata.mapped">
1449*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.metadata.mapped</code>"
1450*5268379eSantirez  </a>
1451*5268379eSantirez        because it overlaps with e.g. the <a class="link" href="#stats.allocated">
1452*5268379eSantirez    "<code class="mallctl">stats.allocated</code>"
1453*5268379eSantirez  </a> and
1454*5268379eSantirez        <a class="link" href="#stats.active">
1455*5268379eSantirez    "<code class="mallctl">stats.active</code>"
1456*5268379eSantirez  </a>
1457*5268379eSantirez        statistics, whereas the other metadata statistics do
1458*5268379eSantirez        not.</p></dd><dt><a name="stats.arenas.i.npurge"></a><span class="term">
1459a78e148bSantirez
1460a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.npurge</code>"
1461a78e148bSantirez
1462a78e148bSantirez          (<span class="type">uint64_t</span>)
1463a78e148bSantirez          <code class="literal">r-</code>
1464a78e148bSantirez          [<code class="option">--enable-stats</code>]
1465a78e148bSantirez        </span></dt><dd><p>Number of dirty page purge sweeps performed.
1466fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.nmadvise"></a><span class="term">
1467a78e148bSantirez
1468a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.nmadvise</code>"
1469a78e148bSantirez
1470a78e148bSantirez          (<span class="type">uint64_t</span>)
1471a78e148bSantirez          <code class="literal">r-</code>
1472a78e148bSantirez          [<code class="option">--enable-stats</code>]
1473a78e148bSantirez        </span></dt><dd><p>Number of <code class="function">madvise</code>(<em class="parameter"><code>...</code></em>,
1474a78e148bSantirez        <em class="parameter"><code><code class="constant">MADV_DONTNEED</code></code></em>) or
1475fceef8e0Santirez        similar calls made to purge dirty pages.</p></dd><dt><a name="stats.arenas.i.purged"></a><span class="term">
1476a78e148bSantirez
1477fceef8e0Santirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.purged</code>"
1478a78e148bSantirez
1479a78e148bSantirez          (<span class="type">uint64_t</span>)
1480a78e148bSantirez          <code class="literal">r-</code>
1481a78e148bSantirez          [<code class="option">--enable-stats</code>]
1482fceef8e0Santirez        </span></dt><dd><p>Number of pages purged.</p></dd><dt><a name="stats.arenas.i.small.allocated"></a><span class="term">
1483a78e148bSantirez
1484a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.small.allocated</code>"
1485a78e148bSantirez
1486a78e148bSantirez          (<span class="type">size_t</span>)
1487a78e148bSantirez          <code class="literal">r-</code>
1488a78e148bSantirez          [<code class="option">--enable-stats</code>]
1489a78e148bSantirez        </span></dt><dd><p>Number of bytes currently allocated by small objects.
1490fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.small.nmalloc"></a><span class="term">
1491a78e148bSantirez
1492a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.small.nmalloc</code>"
1493a78e148bSantirez
1494a78e148bSantirez          (<span class="type">uint64_t</span>)
1495a78e148bSantirez          <code class="literal">r-</code>
1496a78e148bSantirez          [<code class="option">--enable-stats</code>]
1497a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocation requests served by
1498fceef8e0Santirez        small bins.</p></dd><dt><a name="stats.arenas.i.small.ndalloc"></a><span class="term">
1499a78e148bSantirez
1500a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.small.ndalloc</code>"
1501a78e148bSantirez
1502a78e148bSantirez          (<span class="type">uint64_t</span>)
1503a78e148bSantirez          <code class="literal">r-</code>
1504a78e148bSantirez          [<code class="option">--enable-stats</code>]
1505a78e148bSantirez        </span></dt><dd><p>Cumulative number of small objects returned to bins.
1506fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.small.nrequests"></a><span class="term">
1507a78e148bSantirez
1508a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.small.nrequests</code>"
1509a78e148bSantirez
1510a78e148bSantirez          (<span class="type">uint64_t</span>)
1511a78e148bSantirez          <code class="literal">r-</code>
1512a78e148bSantirez          [<code class="option">--enable-stats</code>]
1513a78e148bSantirez        </span></dt><dd><p>Cumulative number of small allocation requests.
1514fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.large.allocated"></a><span class="term">
1515a78e148bSantirez
1516a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.large.allocated</code>"
1517a78e148bSantirez
1518a78e148bSantirez          (<span class="type">size_t</span>)
1519a78e148bSantirez          <code class="literal">r-</code>
1520a78e148bSantirez          [<code class="option">--enable-stats</code>]
1521a78e148bSantirez        </span></dt><dd><p>Number of bytes currently allocated by large objects.
1522fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.large.nmalloc"></a><span class="term">
1523a78e148bSantirez
1524a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.large.nmalloc</code>"
1525a78e148bSantirez
1526a78e148bSantirez          (<span class="type">uint64_t</span>)
1527a78e148bSantirez          <code class="literal">r-</code>
1528a78e148bSantirez          [<code class="option">--enable-stats</code>]
1529a78e148bSantirez        </span></dt><dd><p>Cumulative number of large allocation requests served
1530fceef8e0Santirez        directly by the arena.</p></dd><dt><a name="stats.arenas.i.large.ndalloc"></a><span class="term">
1531a78e148bSantirez
1532a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.large.ndalloc</code>"
1533a78e148bSantirez
1534a78e148bSantirez          (<span class="type">uint64_t</span>)
1535a78e148bSantirez          <code class="literal">r-</code>
1536a78e148bSantirez          [<code class="option">--enable-stats</code>]
1537a78e148bSantirez        </span></dt><dd><p>Cumulative number of large deallocation requests served
1538fceef8e0Santirez        directly by the arena.</p></dd><dt><a name="stats.arenas.i.large.nrequests"></a><span class="term">
1539a78e148bSantirez
1540a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.large.nrequests</code>"
1541a78e148bSantirez
1542a78e148bSantirez          (<span class="type">uint64_t</span>)
1543a78e148bSantirez          <code class="literal">r-</code>
1544a78e148bSantirez          [<code class="option">--enable-stats</code>]
1545a78e148bSantirez        </span></dt><dd><p>Cumulative number of large allocation requests.
1546*5268379eSantirez        </p></dd><dt><a name="stats.arenas.i.huge.allocated"></a><span class="term">
1547a78e148bSantirez
1548*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.huge.allocated</code>"
1549a78e148bSantirez
1550a78e148bSantirez          (<span class="type">size_t</span>)
1551a78e148bSantirez          <code class="literal">r-</code>
1552a78e148bSantirez          [<code class="option">--enable-stats</code>]
1553*5268379eSantirez        </span></dt><dd><p>Number of bytes currently allocated by huge objects.
1554*5268379eSantirez        </p></dd><dt><a name="stats.arenas.i.huge.nmalloc"></a><span class="term">
1555*5268379eSantirez
1556*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.huge.nmalloc</code>"
1557*5268379eSantirez
1558*5268379eSantirez          (<span class="type">uint64_t</span>)
1559*5268379eSantirez          <code class="literal">r-</code>
1560*5268379eSantirez          [<code class="option">--enable-stats</code>]
1561*5268379eSantirez        </span></dt><dd><p>Cumulative number of huge allocation requests served
1562*5268379eSantirez        directly by the arena.</p></dd><dt><a name="stats.arenas.i.huge.ndalloc"></a><span class="term">
1563*5268379eSantirez
1564*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.huge.ndalloc</code>"
1565*5268379eSantirez
1566*5268379eSantirez          (<span class="type">uint64_t</span>)
1567*5268379eSantirez          <code class="literal">r-</code>
1568*5268379eSantirez          [<code class="option">--enable-stats</code>]
1569*5268379eSantirez        </span></dt><dd><p>Cumulative number of huge deallocation requests served
1570*5268379eSantirez        directly by the arena.</p></dd><dt><a name="stats.arenas.i.huge.nrequests"></a><span class="term">
1571*5268379eSantirez
1572*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.huge.nrequests</code>"
1573*5268379eSantirez
1574*5268379eSantirez          (<span class="type">uint64_t</span>)
1575*5268379eSantirez          <code class="literal">r-</code>
1576*5268379eSantirez          [<code class="option">--enable-stats</code>]
1577*5268379eSantirez        </span></dt><dd><p>Cumulative number of huge allocation requests.
1578*5268379eSantirez        </p></dd><dt><a name="stats.arenas.i.bins.j.nmalloc"></a><span class="term">
1579a78e148bSantirez
1580a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nmalloc</code>"
1581a78e148bSantirez
1582a78e148bSantirez          (<span class="type">uint64_t</span>)
1583a78e148bSantirez          <code class="literal">r-</code>
1584a78e148bSantirez          [<code class="option">--enable-stats</code>]
1585a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocations served by bin.
1586fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.bins.j.ndalloc"></a><span class="term">
1587a78e148bSantirez
1588a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.ndalloc</code>"
1589a78e148bSantirez
1590a78e148bSantirez          (<span class="type">uint64_t</span>)
1591a78e148bSantirez          <code class="literal">r-</code>
1592a78e148bSantirez          [<code class="option">--enable-stats</code>]
1593a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocations returned to bin.
1594fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.bins.j.nrequests"></a><span class="term">
1595a78e148bSantirez
1596a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nrequests</code>"
1597a78e148bSantirez
1598a78e148bSantirez          (<span class="type">uint64_t</span>)
1599a78e148bSantirez          <code class="literal">r-</code>
1600a78e148bSantirez          [<code class="option">--enable-stats</code>]
1601a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocation
1602*5268379eSantirez        requests.</p></dd><dt><a name="stats.arenas.i.bins.j.curregs"></a><span class="term">
1603*5268379eSantirez
1604*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.curregs</code>"
1605*5268379eSantirez
1606*5268379eSantirez          (<span class="type">size_t</span>)
1607*5268379eSantirez          <code class="literal">r-</code>
1608*5268379eSantirez          [<code class="option">--enable-stats</code>]
1609*5268379eSantirez        </span></dt><dd><p>Current number of regions for this size
1610*5268379eSantirez        class.</p></dd><dt><a name="stats.arenas.i.bins.j.nfills"></a><span class="term">
1611a78e148bSantirez
1612a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nfills</code>"
1613a78e148bSantirez
1614a78e148bSantirez          (<span class="type">uint64_t</span>)
1615a78e148bSantirez          <code class="literal">r-</code>
1616a78e148bSantirez          [<code class="option">--enable-stats</code> <code class="option">--enable-tcache</code>]
1617fceef8e0Santirez        </span></dt><dd><p>Cumulative number of tcache fills.</p></dd><dt><a name="stats.arenas.i.bins.j.nflushes"></a><span class="term">
1618a78e148bSantirez
1619a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nflushes</code>"
1620a78e148bSantirez
1621a78e148bSantirez          (<span class="type">uint64_t</span>)
1622a78e148bSantirez          <code class="literal">r-</code>
1623a78e148bSantirez          [<code class="option">--enable-stats</code> <code class="option">--enable-tcache</code>]
1624fceef8e0Santirez        </span></dt><dd><p>Cumulative number of tcache flushes.</p></dd><dt><a name="stats.arenas.i.bins.j.nruns"></a><span class="term">
1625a78e148bSantirez
1626a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nruns</code>"
1627a78e148bSantirez
1628a78e148bSantirez          (<span class="type">uint64_t</span>)
1629a78e148bSantirez          <code class="literal">r-</code>
1630a78e148bSantirez          [<code class="option">--enable-stats</code>]
1631fceef8e0Santirez        </span></dt><dd><p>Cumulative number of runs created.</p></dd><dt><a name="stats.arenas.i.bins.j.nreruns"></a><span class="term">
1632a78e148bSantirez
1633a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nreruns</code>"
1634a78e148bSantirez
1635a78e148bSantirez          (<span class="type">uint64_t</span>)
1636a78e148bSantirez          <code class="literal">r-</code>
1637a78e148bSantirez          [<code class="option">--enable-stats</code>]
1638a78e148bSantirez        </span></dt><dd><p>Cumulative number of times the current run from which
1639fceef8e0Santirez        to allocate changed.</p></dd><dt><a name="stats.arenas.i.bins.j.curruns"></a><span class="term">
1640a78e148bSantirez
1641a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.curruns</code>"
1642a78e148bSantirez
1643a78e148bSantirez          (<span class="type">size_t</span>)
1644a78e148bSantirez          <code class="literal">r-</code>
1645a78e148bSantirez          [<code class="option">--enable-stats</code>]
1646fceef8e0Santirez        </span></dt><dd><p>Current number of runs.</p></dd><dt><a name="stats.arenas.i.lruns.j.nmalloc"></a><span class="term">
1647a78e148bSantirez
1648a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.nmalloc</code>"
1649a78e148bSantirez
1650a78e148bSantirez          (<span class="type">uint64_t</span>)
1651a78e148bSantirez          <code class="literal">r-</code>
1652a78e148bSantirez          [<code class="option">--enable-stats</code>]
1653a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocation requests for this size
1654fceef8e0Santirez        class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.lruns.j.ndalloc"></a><span class="term">
1655a78e148bSantirez
1656a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.ndalloc</code>"
1657a78e148bSantirez
1658a78e148bSantirez          (<span class="type">uint64_t</span>)
1659a78e148bSantirez          <code class="literal">r-</code>
1660a78e148bSantirez          [<code class="option">--enable-stats</code>]
1661a78e148bSantirez        </span></dt><dd><p>Cumulative number of deallocation requests for this
1662fceef8e0Santirez        size class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.lruns.j.nrequests"></a><span class="term">
1663a78e148bSantirez
1664a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.nrequests</code>"
1665a78e148bSantirez
1666a78e148bSantirez          (<span class="type">uint64_t</span>)
1667a78e148bSantirez          <code class="literal">r-</code>
1668a78e148bSantirez          [<code class="option">--enable-stats</code>]
1669a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocation requests for this size
1670fceef8e0Santirez        class.</p></dd><dt><a name="stats.arenas.i.lruns.j.curruns"></a><span class="term">
1671a78e148bSantirez
1672a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.curruns</code>"
1673a78e148bSantirez
1674a78e148bSantirez          (<span class="type">size_t</span>)
1675a78e148bSantirez          <code class="literal">r-</code>
1676a78e148bSantirez          [<code class="option">--enable-stats</code>]
1677a78e148bSantirez        </span></dt><dd><p>Current number of runs for this size class.
1678*5268379eSantirez        </p></dd><dt><a name="stats.arenas.i.hchunks.j.nmalloc"></a><span class="term">
1679*5268379eSantirez
1680*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.hchunks.&lt;j&gt;.nmalloc</code>"
1681*5268379eSantirez
1682*5268379eSantirez          (<span class="type">uint64_t</span>)
1683*5268379eSantirez          <code class="literal">r-</code>
1684*5268379eSantirez          [<code class="option">--enable-stats</code>]
1685*5268379eSantirez        </span></dt><dd><p>Cumulative number of allocation requests for this size
1686*5268379eSantirez        class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.hchunks.j.ndalloc"></a><span class="term">
1687*5268379eSantirez
1688*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.hchunks.&lt;j&gt;.ndalloc</code>"
1689*5268379eSantirez
1690*5268379eSantirez          (<span class="type">uint64_t</span>)
1691*5268379eSantirez          <code class="literal">r-</code>
1692*5268379eSantirez          [<code class="option">--enable-stats</code>]
1693*5268379eSantirez        </span></dt><dd><p>Cumulative number of deallocation requests for this
1694*5268379eSantirez        size class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.hchunks.j.nrequests"></a><span class="term">
1695*5268379eSantirez
1696*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.hchunks.&lt;j&gt;.nrequests</code>"
1697*5268379eSantirez
1698*5268379eSantirez          (<span class="type">uint64_t</span>)
1699*5268379eSantirez          <code class="literal">r-</code>
1700*5268379eSantirez          [<code class="option">--enable-stats</code>]
1701*5268379eSantirez        </span></dt><dd><p>Cumulative number of allocation requests for this size
1702*5268379eSantirez        class.</p></dd><dt><a name="stats.arenas.i.hchunks.j.curhchunks"></a><span class="term">
1703*5268379eSantirez
1704*5268379eSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.hchunks.&lt;j&gt;.curhchunks</code>"
1705*5268379eSantirez
1706*5268379eSantirez          (<span class="type">size_t</span>)
1707*5268379eSantirez          <code class="literal">r-</code>
1708*5268379eSantirez          [<code class="option">--enable-stats</code>]
1709*5268379eSantirez        </span></dt><dd><p>Current number of huge allocations for this size class.
1710fceef8e0Santirez        </p></dd></dl></div></div><div class="refsect1"><a name="debugging_malloc_problems"></a><h2>DEBUGGING MALLOC PROBLEMS</h2><p>When debugging, it is a good idea to configure/build jemalloc with
1711a78e148bSantirez    the <code class="option">--enable-debug</code> and <code class="option">--enable-fill</code>
1712a78e148bSantirez    options, and recompile the program with suitable options and symbols for
1713a78e148bSantirez    debugger support.  When so configured, jemalloc incorporates a wide variety
1714a78e148bSantirez    of run-time assertions that catch application errors such as double-free,
1715a78e148bSantirez    write-after-free, etc.</p><p>Programs often accidentally depend on &#8220;uninitialized&#8221;
1716a78e148bSantirez    memory actually being filled with zero bytes.  Junk filling
1717a78e148bSantirez    (see the <a class="link" href="#opt.junk">
1718a78e148bSantirez    "<code class="mallctl">opt.junk</code>"
1719a78e148bSantirez  </a>
1720a78e148bSantirez    option) tends to expose such bugs in the form of obviously incorrect
1721a78e148bSantirez    results and/or coredumps.  Conversely, zero
1722a78e148bSantirez    filling (see the <a class="link" href="#opt.zero">
1723a78e148bSantirez    "<code class="mallctl">opt.zero</code>"
1724a78e148bSantirez  </a> option) eliminates
1725a78e148bSantirez    the symptoms of such bugs.  Between these two options, it is usually
1726a78e148bSantirez    possible to quickly detect, diagnose, and eliminate such bugs.</p><p>This implementation does not provide much detail about the problems
1727a78e148bSantirez    it detects, because the performance impact for storing such information
1728ad4c0b41Santirez    would be prohibitive.  However, jemalloc does integrate with the most
1729ad4c0b41Santirez    excellent <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a> tool if the
1730fceef8e0Santirez    <code class="option">--enable-valgrind</code> configuration option is enabled.</p></div><div class="refsect1"><a name="diagnostic_messages"></a><h2>DIAGNOSTIC MESSAGES</h2><p>If any of the memory allocation/deallocation functions detect an
1731a78e148bSantirez    error or warning condition, a message will be printed to file descriptor
1732a78e148bSantirez    <code class="constant">STDERR_FILENO</code>.  Errors will result in the process
1733a78e148bSantirez    dumping core.  If the <a class="link" href="#opt.abort">
1734a78e148bSantirez    "<code class="mallctl">opt.abort</code>"
1735a78e148bSantirez  </a> option is set, most
1736a78e148bSantirez    warnings are treated as errors.</p><p>The <code class="varname">malloc_message</code> variable allows the programmer
1737a78e148bSantirez    to override the function which emits the text strings forming the errors
1738a78e148bSantirez    and warnings if for some reason the <code class="constant">STDERR_FILENO</code> file
1739a78e148bSantirez    descriptor is not suitable for this.
1740a78e148bSantirez    <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) takes the
1741a78e148bSantirez    <em class="parameter"><code>cbopaque</code></em> pointer argument that is
1742a78e148bSantirez    <code class="constant">NULL</code> unless overridden by the arguments in a call to
1743a78e148bSantirez    <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>), followed by a string
1744a78e148bSantirez    pointer.  Please note that doing anything which tries to allocate memory in
1745a78e148bSantirez    this function is likely to result in a crash or deadlock.</p><p>All messages are prefixed by
1746*5268379eSantirez    &#8220;<code class="computeroutput">&lt;jemalloc&gt;: </code>&#8221;.</p></div><div class="refsect1"><a name="return_values"></a><h2>RETURN VALUES</h2><div class="refsect2"><a name="idp46949776"></a><h3>Standard API</h3><p>The <code class="function">malloc</code>(<em class="parameter"><code></code></em>) and
1747a78e148bSantirez      <code class="function">calloc</code>(<em class="parameter"><code></code></em>) functions return a pointer to the
1748a78e148bSantirez      allocated memory if successful; otherwise a <code class="constant">NULL</code>
1749a78e148bSantirez      pointer is returned and <code class="varname">errno</code> is set to
1750a78e148bSantirez      <span class="errorname">ENOMEM</span>.</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function
1751a78e148bSantirez      returns the value 0 if successful; otherwise it returns an error value.
1752a78e148bSantirez      The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function will fail
1753a78e148bSantirez      if:
1754fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorname">EINVAL</span></span></dt><dd><p>The <em class="parameter"><code>alignment</code></em> parameter is
1755a78e148bSantirez            not a power of 2 at least as large as
1756a78e148bSantirez            <code class="code">sizeof(<span class="type">void *</span>)</code>.
1757a78e148bSantirez            </p></dd><dt><span class="term"><span class="errorname">ENOMEM</span></span></dt><dd><p>Memory allocation error.</p></dd></dl></div><p>
1758ad4c0b41Santirez      </p><p>The <code class="function">aligned_alloc</code>(<em class="parameter"><code></code></em>) function returns
1759ad4c0b41Santirez      a pointer to the allocated memory if successful; otherwise a
1760ad4c0b41Santirez      <code class="constant">NULL</code> pointer is returned and
1761ad4c0b41Santirez      <code class="varname">errno</code> is set.  The
1762ad4c0b41Santirez      <code class="function">aligned_alloc</code>(<em class="parameter"><code></code></em>) function will fail if:
1763fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorname">EINVAL</span></span></dt><dd><p>The <em class="parameter"><code>alignment</code></em> parameter is
1764ad4c0b41Santirez            not a power of 2.
1765ad4c0b41Santirez            </p></dd><dt><span class="term"><span class="errorname">ENOMEM</span></span></dt><dd><p>Memory allocation error.</p></dd></dl></div><p>
1766a78e148bSantirez      </p><p>The <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function returns a
1767a78e148bSantirez      pointer, possibly identical to <em class="parameter"><code>ptr</code></em>, to the
1768a78e148bSantirez      allocated memory if successful; otherwise a <code class="constant">NULL</code>
1769a78e148bSantirez      pointer is returned, and <code class="varname">errno</code> is set to
1770a78e148bSantirez      <span class="errorname">ENOMEM</span> if the error was the result of an
1771a78e148bSantirez      allocation failure.  The <code class="function">realloc</code>(<em class="parameter"><code></code></em>)
1772a78e148bSantirez      function always leaves the original buffer intact when an error occurs.
1773a78e148bSantirez      </p><p>The <code class="function">free</code>(<em class="parameter"><code></code></em>) function returns no
1774*5268379eSantirez      value.</p></div><div class="refsect2"><a name="idp46974576"></a><h3>Non-standard API</h3><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) and
1775fceef8e0Santirez      <code class="function">rallocx</code>(<em class="parameter"><code></code></em>) functions return a pointer to
1776fceef8e0Santirez      the allocated memory if successful; otherwise a <code class="constant">NULL</code>
1777fceef8e0Santirez      pointer is returned to indicate insufficient contiguous memory was
1778fceef8e0Santirez      available to service the allocation request.  </p><p>The <code class="function">xallocx</code>(<em class="parameter"><code></code></em>) function returns the
1779fceef8e0Santirez      real size of the resulting resized allocation pointed to by
1780fceef8e0Santirez      <em class="parameter"><code>ptr</code></em>, which is a value less than
1781fceef8e0Santirez      <em class="parameter"><code>size</code></em> if the allocation could not be adequately
1782fceef8e0Santirez      grown in place.  </p><p>The <code class="function">sallocx</code>(<em class="parameter"><code></code></em>) function returns the
1783fceef8e0Santirez      real size of the allocation pointed to by <em class="parameter"><code>ptr</code></em>.
1784fceef8e0Santirez      </p><p>The <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) returns the real size
1785fceef8e0Santirez      that would result from a successful equivalent
1786fceef8e0Santirez      <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function call, or zero if
1787fceef8e0Santirez      insufficient memory is available to perform the size computation.  </p><p>The <code class="function">mallctl</code>(<em class="parameter"><code></code></em>),
1788a78e148bSantirez      <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>), and
1789a78e148bSantirez      <code class="function">mallctlbymib</code>(<em class="parameter"><code></code></em>) functions return 0 on
1790a78e148bSantirez      success; otherwise they return an error value.  The functions will fail
1791a78e148bSantirez      if:
1792fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorname">EINVAL</span></span></dt><dd><p><em class="parameter"><code>newp</code></em> is not
1793a78e148bSantirez            <code class="constant">NULL</code>, and <em class="parameter"><code>newlen</code></em> is too
1794a78e148bSantirez            large or too small.  Alternatively, <em class="parameter"><code>*oldlenp</code></em>
1795a78e148bSantirez            is too large or too small; in this case as much data as possible
1796fceef8e0Santirez            are read despite the error.</p></dd><dt><span class="term"><span class="errorname">ENOENT</span></span></dt><dd><p><em class="parameter"><code>name</code></em> or
1797a78e148bSantirez            <em class="parameter"><code>mib</code></em> specifies an unknown/invalid
1798a78e148bSantirez            value.</p></dd><dt><span class="term"><span class="errorname">EPERM</span></span></dt><dd><p>Attempt to read or write void value, or attempt to
1799a78e148bSantirez            write read-only value.</p></dd><dt><span class="term"><span class="errorname">EAGAIN</span></span></dt><dd><p>A memory allocation failure
1800a78e148bSantirez            occurred.</p></dd><dt><span class="term"><span class="errorname">EFAULT</span></span></dt><dd><p>An interface with side effects failed in some way
1801a78e148bSantirez            not directly related to <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>)
1802a78e148bSantirez            read/write processing.</p></dd></dl></div><p>
1803fceef8e0Santirez      </p><p>The <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function
1804fceef8e0Santirez      returns the usable size of the allocation pointed to by
1805*5268379eSantirez      <em class="parameter"><code>ptr</code></em>.  </p></div></div><div class="refsect1"><a name="environment"></a><h2>ENVIRONMENT</h2><p>The following environment variable affects the execution of the
1806a78e148bSantirez    allocation functions:
1807fceef8e0Santirez      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">MALLOC_CONF</code></span></dt><dd><p>If the environment variable
1808a78e148bSantirez          <code class="envar">MALLOC_CONF</code> is set, the characters it contains
1809a78e148bSantirez          will be interpreted as options.</p></dd></dl></div><p>
1810fceef8e0Santirez    </p></div><div class="refsect1"><a name="examples"></a><h2>EXAMPLES</h2><p>To dump core whenever a problem occurs:
1811a78e148bSantirez      </p><pre class="screen">ln -s 'abort:true' /etc/malloc.conf</pre><p>
1812a78e148bSantirez    </p><p>To specify in the source a chunk size that is 16 MiB:
1813a78e148bSantirez      </p><pre class="programlisting">
1814fceef8e0Santirezmalloc_conf = "lg_chunk:24";</pre></div><div class="refsect1"><a name="see_also"></a><h2>SEE ALSO</h2><p><span class="citerefentry"><span class="refentrytitle">madvise</span>(2)</span>,
1815a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span>,
1816a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>,
1817ad4c0b41Santirez    <span class="citerefentry"><span class="refentrytitle">utrace</span>(2)</span>,
1818a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">alloca</span>(3)</span>,
1819a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span>,
1820fceef8e0Santirez    <span class="citerefentry"><span class="refentrytitle">getpagesize</span>(3)</span></p></div><div class="refsect1"><a name="standards"></a><h2>STANDARDS</h2><p>The <code class="function">malloc</code>(<em class="parameter"><code></code></em>),
1821a78e148bSantirez    <code class="function">calloc</code>(<em class="parameter"><code></code></em>),
1822a78e148bSantirez    <code class="function">realloc</code>(<em class="parameter"><code></code></em>), and
1823a78e148bSantirez    <code class="function">free</code>(<em class="parameter"><code></code></em>) functions conform to ISO/IEC
1824a78e148bSantirez    9899:1990 (&#8220;ISO C90&#8221;).</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function conforms
1825a78e148bSantirez    to IEEE Std 1003.1-2001 (&#8220;POSIX.1&#8221;).</p></div></div></body></html>
1826