can be found at the <aclass="ulink"href="http://www.canonware.com/jemalloc/"target="_top">jemalloc website</a>.</p></div><divclass="refsynopsisdiv"title="SYNOPSIS"><h2>SYNOPSIS</h2><divclass="funcsynopsis"><preclass="funcsynopsisinfo">#include <<codeclass="filename">stdlib.h</code>>
<emclass="parameter"><code>size</code></em> bytes of uninitialized memory. The allocated
space is suitably aligned (after possible pointer coercion) for storage
of any type of object.</p><p>The <codeclass="function">calloc</code>(<emclass="parameter"><code></code></em>) function allocates
space for <emclass="parameter"><code>number</code></em> objects, each
<emclass="parameter"><code>size</code></em> bytes in length. The result is identical to
calling <codeclass="function">malloc</code>(<emclass="parameter"><code></code></em>) with an argument of
<emclass="parameter"><code>number</code></em> * <emclass="parameter"><code>size</code></em>, with the
exception that the allocated memory is explicitly initialized to zero
bytes.</p><p>The <codeclass="function">posix_memalign</code>(<emclass="parameter"><code></code></em>) function
allocates <emclass="parameter"><code>size</code></em> bytes of memory such that the
allocation's base address is an even multiple of
<emclass="parameter"><code>alignment</code></em>, and returns the allocation in the value
pointed to by <emclass="parameter"><code>ptr</code></em>. The requested
<emclass="parameter"><code>alignment</code></em> must be a power of 2 at least as large
as <codeclass="code">sizeof(<spanclass="type">void *</span>)</code>.</p><p>The <codeclass="function">realloc</code>(<emclass="parameter"><code></code></em>) function changes the
size of the previously allocated memory referenced by
<emclass="parameter"><code>ptr</code></em> to <emclass="parameter"><code>size</code></em> bytes. The
contents of the memory are unchanged up to the lesser of the new and old
sizes. If the new size is larger, the contents of the newly allocated
portion of the memory are undefined. Upon success, the memory referenced
by <emclass="parameter"><code>ptr</code></em> is freed and a pointer to the newly
allocated memory is returned. Note that
<codeclass="function">realloc</code>(<emclass="parameter"><code></code></em>) may move the memory allocation,
resulting in a different return value than <emclass="parameter"><code>ptr</code></em>.
If <emclass="parameter"><code>ptr</code></em> is <codeclass="constant">NULL</code>, the
<codeclass="function">realloc</code>(<emclass="parameter"><code></code></em>) function behaves identically to
<codeclass="function">malloc</code>(<emclass="parameter"><code></code></em>) for the specified size.</p><p>The <codeclass="function">free</code>(<emclass="parameter"><code></code></em>) function causes the
allocated memory referenced by <emclass="parameter"><code>ptr</code></em> to be made
available for future allocations. If <emclass="parameter"><code>ptr</code></em> is
<codeclass="constant">NULL</code>, no action occurs.</p></div><divclass="refsect2"title="Non-standard API"><aname="id3025603"></a><h3>Non-standard API</h3><p>The <codeclass="function">malloc_usable_size</code>(<emclass="parameter"><code></code></em>) function
}</pre></div><divclass="refsect2"title="Experimental API"><aname="id3013809"></a><h3>Experimental API</h3><p>The experimental API is subject to change or removal without regard
</code></span></dt><dd><p>Align the memory allocation to start at an address
that is a multiple of <emclass="parameter"><code>a</code></em>, where
<emclass="parameter"><code>a</code></em> is a power of two. This macro does not
validate that <emclass="parameter"><code>a</code></em> is a power of 2.
</p></dd><dt><spanclass="term"><codeclass="constant">ALLOCM_ZERO</code></span></dt><dd><p>Initialize newly allocated memory to contain zero
bytes. In the growing reallocation case, the real size prior to
reallocation defines the boundary between untouched bytes and those
that are initialized to contain zero bytes. If this option is
absent, newly allocated memory is uninitialized.</p></dd><dt><spanclass="term"><codeclass="constant">ALLOCM_NO_MOVE</code></span></dt><dd><p>For reallocation, fail rather than moving the
object. This constraint can apply to both growth and
shrinkage.</p></dd></dl></div><p>
</p><p>The <codeclass="function">allocm</code>(<emclass="parameter"><code></code></em>) function allocates at
least <emclass="parameter"><code>size</code></em> bytes of memory, sets
<emclass="parameter"><code>*ptr</code></em> to the base address of the allocation, and
sets <emclass="parameter"><code>*rsize</code></em> to the real size of the allocation if
<emclass="parameter"><code>rsize</code></em> is not <codeclass="constant">NULL</code>.</p><p>The <codeclass="function">rallocm</code>(<emclass="parameter"><code></code></em>) function resizes the
allocation at <emclass="parameter"><code>*ptr</code></em> to be at least
<emclass="parameter"><code>size</code></em> bytes, sets <emclass="parameter"><code>*ptr</code></em> to
the base address of the allocation if it moved, and sets
<emclass="parameter"><code>*rsize</code></em> to the real size of the allocation if
<emclass="parameter"><code>rsize</code></em> is not <codeclass="constant">NULL</code>. If
<emclass="parameter"><code>extra</code></em> is non-zero, an attempt is made to resize
the allocation to be at least <codeclass="code"><emclass="parameter"><code>size</code></em> +
<emclass="parameter"><code>extra</code></em>)</code> bytes, though inability to allocate
the extra byte(s) will not by itself result in failure. Behavior is
undefined if <codeclass="code">(<emclass="parameter"><code>size</code></em> +
<emclass="parameter"><code>extra</code></em>>
<codeclass="constant">SIZE_T_MAX</code>)</code>.</p><p>The <codeclass="function">sallocm</code>(<emclass="parameter"><code></code></em>) function sets
<emclass="parameter"><code>*rsize</code></em> to the real size of the allocation.</p><p>The <codeclass="function">dallocm</code>(<emclass="parameter"><code></code></em>) function causes the
memory referenced by <emclass="parameter"><code>ptr</code></em> to be made available for
future allocations.</p></div></div><divclass="refsect1"title="TUNING"><aname="tuning"></a><h2>TUNING</h2><p>Once, when the first call is made to one of the memory allocation
routines, the allocator initializes its internals based in part on various
options that can be specified at compile- or run-time.</p><p>The string pointed to by the global variable
<codeclass="varname">malloc_conf</code>, the “name” of the file
referenced by the symbolic link named <codeclass="filename">/etc/malloc.conf</code>, and the value of the
environment variable <codeclass="envar">MALLOC_CONF</code>, will be interpreted, in
that order, from left to right as options.</p><p>An options string is a comma-separated list of option:value pairs.
There is one key corresponding to each <aclass="link"href="#opt.abort">
"<codeclass="mallctl">opt.*</code>"
</a> mallctl (see the <aclass="xref"href="#mallctl_namespace"title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for options
documentation). For example, <codeclass="literal">abort:true,narenas:1</code> sets
the <aclass="link"href="#opt.abort">
"<codeclass="mallctl">opt.abort</code>"
</a> and <aclass="link"href="#opt.narenas">
"<codeclass="mallctl">opt.narenas</code>"
</a> options. Some
options have boolean values (true/false), others have integer values (base
8, 10, or 16, depending on prefix), and yet others have raw string
values.</p></div><divclass="refsect1"title="IMPLEMENTATION NOTES"><aname="implementation_notes"></a><h2>IMPLEMENTATION NOTES</h2><p>Traditionally, allocators have used
<spanclass="citerefentry"><spanclass="refentrytitle">sbrk</span>(2)</span> to obtain memory, which is
suboptimal for several reasons, including race conditions, increased
fragmentation, and artificial limitations on maximum usable memory. If
<codeclass="option">--enable-dss</code> is specified during configuration, this
allocator uses both <spanclass="citerefentry"><spanclass="refentrytitle">sbrk</span>(2)</span> and
<spanclass="citerefentry"><spanclass="refentrytitle">mmap</span>(2)</span>, in that order of preference;
otherwise only <spanclass="citerefentry"><spanclass="refentrytitle">mmap</span>(2)</span> is used.</p><p>This allocator uses multiple arenas in order to reduce lock
contention for threaded programs on multi-processor systems. This works
well with regard to threading scalability, but incurs some costs. There is
a small fixed per-arena overhead, and additionally, arenas manage memory
completely independently of each other, which means a small fixed increase
in overall memory fragmentation. These overheads are not generally an
issue, given the number of arenas normally used. Note that using
substantially more arenas than the default is not likely to improve
performance, mainly due to reduced cache performance. However, it may make
sense to reduce the number of arenas if an application does not make much
use of the allocation functions.</p><p>In addition to multiple arenas, unless
<codeclass="option">--disable-tcache</code> is specified during configuration, this
allocator supports thread-specific caching for small and large objects, in
order to make it possible to completely avoid synchronization for most
allocation requests. Such caching allows very fast allocation in the
common case, but it increases memory usage and fragmentation, since a
bounded number of objects can remain allocated in each thread cache.</p><p>Memory is conceptually broken into equal-sized chunks, where the
chunk size is a power of two that is greater than the page size. Chunks
are always aligned to multiples of the chunk size. This alignment makes it
possible to find metadata for user objects very quickly.</p><p>User objects are broken into three categories according to size:
small, large, and huge. Small objects are smaller than one page. Large
objects are smaller than the chunk size. Huge objects are a multiple of
the chunk size. Small and large objects are managed by arenas; huge
objects are managed separately in a single data structure that is shared by
all threads. Huge objects are used by applications infrequently enough
that this single data structure is not a scalability issue.</p><p>Each chunk that is managed by an arena tracks its contents as runs of
contiguous pages (unused, backing a set of small objects, or backing one
large object). The combination of chunk alignment and chunk page maps
makes it possible to determine all metadata regarding small and large
allocations in constant time.</p><p>Small objects are managed in groups by page runs. Each run maintains
a frontier and free list to track which regions are in use. Unless
<codeclass="option">--disable-tiny</code> is specified during configuration,
allocation requests that are no more than half the quantum (8 or 16,
depending on architecture) are rounded up to the nearest power of two that
is at least <codeclass="code">sizeof(<spanclass="type">void *</span>)</code>.
Allocation requests that are more than half the quantum, but no more than
the minimum cacheline-multiple size class (see the <aclass="link"href="#opt.lg_qspace_max">
"<codeclass="mallctl">opt.lg_qspace_max</code>"
</a>
option) are rounded up to the nearest multiple of the quantum. Allocation
requests that are more than the minimum cacheline-multiple size class, but
no more than the minimum subpage-multiple size class (see the <aclass="link"href="#opt.lg_cspace_max">
"<codeclass="mallctl">opt.lg_cspace_max</code>"
</a>
option) are rounded up to the nearest multiple of the cacheline size (64).
Allocation requests that are more than the minimum subpage-multiple size
class, but no more than the maximum subpage-multiple size class are rounded
up to the nearest multiple of the subpage size (256). Allocation requests
that are more than the maximum subpage-multiple size class, but small
enough to fit in an arena-managed chunk (see the <aclass="link"href="#opt.lg_chunk">
"<codeclass="mallctl">opt.lg_chunk</code>"
</a> option), are
rounded up to the nearest run size. Allocation requests that are too large
to fit in an arena-managed chunk are rounded up to the nearest multiple of
the chunk size.</p><p>Allocations are packed tightly together, which can be an issue for
multi-threaded applications. If you need to assure that allocations do not
suffer from cacheline sharing, round your allocation requests up to the
nearest multiple of the cacheline size, or specify cacheline alignment when
allocating.</p><p>Assuming 4 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 64-bit
system, the size classes in each category are as shown in <aclass="xref"href="#size_classes"title="Table<6C>1.<2E>Size classes">Table 1</a>.</p><divclass="table"><aname="size_classes"></a><pclass="title"><b>Table<EFBFBD>1.<2E>Size classes</b></p><divclass="table-contents"><tablesummary="Size classes"border="1"><colgroup><colalign="left"><colalign="left"><colalign="left"></colgroup><thead><tr><thalign="left">Category</th><thalign="left">Subcategory</th><thalign="left">Size</th></tr></thead><tbody><tr><tdrowspan="4"align="left">Small</td><tdalign="left">Tiny</td><tdalign="left">[8]</td></tr><tr><tdalign="left">Quantum-spaced</td><tdalign="left">[16, 32, 48, ..., 128]</td></tr><tr><tdalign="left">Cacheline-spaced</td><tdalign="left">[192, 256, 320, ..., 512]</td></tr><tr><tdalign="left">Subpage-spaced</td><tdalign="left">[768, 1024, 1280, ..., 3840]</td></tr><tr><tdcolspan="2"align="left">Large</td><tdalign="left">[4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB]</td></tr><tr><tdcolspan="2"align="left">Huge</td><tdalign="left">[4 MiB, 8 MiB, 12 MiB, ...]</td></tr></tbody></table></div></div><brclass="table-break"></div><divclass="refsect1"title="MALLCTL NAMESPACE"><aname="mallctl_namespace"></a><h2>MALLCTL NAMESPACE</h2><p>The following names are defined in the namespace accessible via the
<codeclass="function">mallctl*</code>(<emclass="parameter"><code></code></em>) functions. Value types are
specified in parentheses, their readable/writable statuses are encoded as
<codeclass="literal">rw</code>, <codeclass="literal">r-</code>, <codeclass="literal">-w</code>, or
<codeclass="literal">--</code>, and required build configuration flags follow, if
any. A name element encoded as <codeclass="literal"><i></code> or
<codeclass="literal"><j></code> indicates an integer component, where the
integer varies from 0 to some upper value that must be determined via
</span></dt><dd><p>When written to, the files associated with the
specified file descriptors are contiguously mapped via
<spanclass="citerefentry"><spanclass="refentrytitle">mmap</span>(2)</span>. The resulting virtual memory
region is preferred over anonymous
<spanclass="citerefentry"><spanclass="refentrytitle">mmap</span>(2)</span> and
<spanclass="citerefentry"><spanclass="refentrytitle">sbrk</span>(2)</span> memory. Note that if a file's
size is not a multiple of the page size, it is automatically truncated
to the nearest page size multiple. See the
<aclass="link"href="#swap.prezeroed">
"<codeclass="mallctl">swap.prezeroed</code>"
</a>
mallctl for specifying that the files are pre-zeroed.</p></dd></dl></div></div><divclass="refsect1"title="DEBUGGING MALLOC PROBLEMS"><aname="debugging_malloc_problems"></a><h2>DEBUGGING MALLOC PROBLEMS</h2><p>When debugging, it is a good idea to configure/build jemalloc with
the <codeclass="option">--enable-debug</code> and <codeclass="option">--enable-fill</code>
options, and recompile the program with suitable options and symbols for
debugger support. When so configured, jemalloc incorporates a wide variety
of run-time assertions that catch application errors such as double-free,
write-after-free, etc.</p><p>Programs often accidentally depend on “uninitialized”
memory actually being filled with zero bytes. Junk filling
(see the <aclass="link"href="#opt.junk">
"<codeclass="mallctl">opt.junk</code>"
</a>
option) tends to expose such bugs in the form of obviously incorrect
results and/or coredumps. Conversely, zero
filling (see the <aclass="link"href="#opt.zero">
"<codeclass="mallctl">opt.zero</code>"
</a> option) eliminates
the symptoms of such bugs. Between these two options, it is usually
possible to quickly detect, diagnose, and eliminate such bugs.</p><p>This implementation does not provide much detail about the problems
it detects, because the performance impact for storing such information
would be prohibitive. There are a number of allocator implementations
available on the Internet which focus on detecting and pinpointing problems
by trading performance for extra sanity checks and detailed
diagnostics.</p></div><divclass="refsect1"title="DIAGNOSTIC MESSAGES"><aname="diagnostic_messages"></a><h2>DIAGNOSTIC MESSAGES</h2><p>If any of the memory allocation/deallocation functions detect an
error or warning condition, a message will be printed to file descriptor
<codeclass="constant">STDERR_FILENO</code>. Errors will result in the process
dumping core. If the <aclass="link"href="#opt.abort">
"<codeclass="mallctl">opt.abort</code>"
</a> option is set, most
warnings are treated as errors.</p><p>The <codeclass="varname">malloc_message</code> variable allows the programmer
to override the function which emits the text strings forming the errors
and warnings if for some reason the <codeclass="constant">STDERR_FILENO</code> file
descriptor is not suitable for this.
<codeclass="function">malloc_message</code>(<emclass="parameter"><code></code></em>) takes the
<emclass="parameter"><code>cbopaque</code></em> pointer argument that is
<codeclass="constant">NULL</code> unless overridden by the arguments in a call to
<codeclass="function">malloc_stats_print</code>(<emclass="parameter"><code></code></em>), followed by a string
pointer. Please note that doing anything which tries to allocate memory in
this function is likely to result in a crash or deadlock.</p><p>All messages are prefixed by
<codeclass="function">calloc</code>(<emclass="parameter"><code></code></em>) functions return a pointer to the
allocated memory if successful; otherwise a <codeclass="constant">NULL</code>
pointer is returned and <codeclass="varname">errno</code> is set to
<spanclass="errorname">ENOMEM</span>.</p><p>The <codeclass="function">posix_memalign</code>(<emclass="parameter"><code></code></em>) function
returns the value 0 if successful; otherwise it returns an error value.
The <codeclass="function">posix_memalign</code>(<emclass="parameter"><code></code></em>) function will fail
if:
</p><divclass="variablelist"><dl><dt><spanclass="term"><spanclass="errorname">EINVAL</span></span></dt><dd><p>The <emclass="parameter"><code>alignment</code></em> parameter is
value.</p></div><divclass="refsect2"title="Non-standard API"><aname="id3029403"></a><h3>Non-standard API</h3><p>The <codeclass="function">malloc_usable_size</code>(<emclass="parameter"><code></code></em>) function
<codeclass="function">mallctlnametomib</code>(<emclass="parameter"><code></code></em>), and
<codeclass="function">mallctlbymib</code>(<emclass="parameter"><code></code></em>) functions return 0 on
success; otherwise they return an error value. The functions will fail
if:
</p><divclass="variablelist"><dl><dt><spanclass="term"><spanclass="errorname">EINVAL</span></span></dt><dd><p><emclass="parameter"><code>newp</code></em> is not
<codeclass="constant">NULL</code>, and <emclass="parameter"><code>newlen</code></em> is too
large or too small. Alternatively, <emclass="parameter"><code>*oldlenp</code></em>
is too large or too small; in this case as much data as possible
are read despite the error.</p></dd><dt><spanclass="term"><spanclass="errorname">ENOMEM</span></span></dt><dd><p><emclass="parameter"><code>*oldlenp</code></em> is too short to
hold the requested value.</p></dd><dt><spanclass="term"><spanclass="errorname">ENOENT</span></span></dt><dd><p><emclass="parameter"><code>name</code></em> or
<emclass="parameter"><code>mib</code></em> specifies an unknown/invalid
value.</p></dd><dt><spanclass="term"><spanclass="errorname">EPERM</span></span></dt><dd><p>Attempt to read or write void value, or attempt to
<codeclass="constant">ALLOCM_SUCCESS</code> on success; otherwise they return an
error value. The <codeclass="function">allocm</code>(<emclass="parameter"><code></code></em>) and
<codeclass="function">rallocm</code>(<emclass="parameter"><code></code></em>) functions will fail if:
</p><divclass="variablelist"><dl><dt><spanclass="term"><spanclass="errorname">ALLOCM_ERR_OOM</span></span></dt><dd><p>Out of memory. Insufficient contiguous memory was
available to service the allocation request. The
<codeclass="function">allocm</code>(<emclass="parameter"><code></code></em>) function additionally sets
<emclass="parameter"><code>*ptr</code></em> to <codeclass="constant">NULL</code>, whereas
the <codeclass="function">rallocm</code>(<emclass="parameter"><code></code></em>) function leaves
The <codeclass="function">rallocm</code>(<emclass="parameter"><code></code></em>) function will also
fail if:
</p><divclass="variablelist"><dl><dt><spanclass="term"><spanclass="errorname">ALLOCM_ERR_NOT_MOVED</span></span></dt><dd><p><codeclass="constant">ALLOCM_NO_MOVE</code> was specified,
but the reallocation request could not be serviced without moving
the object.</p></dd></dl></div><p>
</p></div></div><divclass="refsect1"title="ENVIRONMENT"><aname="environment"></a><h2>ENVIRONMENT</h2><p>The following environment variable affects the execution of the
allocation functions:
</p><divclass="variablelist"><dl><dt><spanclass="term"><codeclass="envar">MALLOC_CONF</code></span></dt><dd><p>If the environment variable
<codeclass="envar">MALLOC_CONF</code> is set, the characters it contains
will be interpreted as options.</p></dd></dl></div><p>
</p></div><divclass="refsect1"title="EXAMPLES"><aname="examples"></a><h2>EXAMPLES</h2><p>To dump core whenever a problem occurs:
