href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>

        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

]>

<refentry>

  <refentryinfo>

    <title>User Manual</title>

    <productname>jemalloc</productname>

    <releaseinfo role="version">@jemalloc_version@</releaseinfo>

    <authorgroup>

      <author>

        <firstname>Jason</firstname>

        <surname>Evans</surname>

        <personblurb>Author</personblurb>

      </author>

    </authorgroup>

  </refentryinfo>

  <refmeta>

    <refentrytitle>JEMALLOC</refentrytitle>

    <manvolnum>3</manvolnum>

  </refmeta>

  <refnamediv>

    <refdescriptor>jemalloc</refdescriptor>

    <refname>jemalloc</refname>

         the system malloc(3) implementation would these files be appropriate.

    <refname>malloc</refname>

    <refname>calloc</refname>

    <refname>posix_memalign</refname>

    <refname>aligned_alloc</refname>

    <refname>realloc</refname>

    <refname>free</refname>

    <refname>mallocx</refname>

    <refname>rallocx</refname>

    <refname>xallocx</refname>

    <refname>sallocx</refname>

    <refname>dallocx</refname>

    <refname>sdallocx</refname>

    <refname>nallocx</refname>

    <refname>mallctl</refname>

    <refname>mallctlnametomib</refname>

    <refname>mallctlbymib</refname>

    <refname>malloc_stats_print</refname>

    <refname>malloc_usable_size</refname>

    -->

    <refpurpose>general purpose memory allocation functions</refpurpose>

  </refnamediv>

  <refsect1 id="library">

    <title>LIBRARY</title>

    <para>This manual describes jemalloc @jemalloc_version@.  More information

    can be found at the 

    url="http://jemalloc.net/">jemalloc website</ulink>.</para>

  </refsect1>

  <refsynopsisdiv>

    <title>SYNOPSIS</title>

    <funcsynopsis>

      <funcsynopsisinfo>#include <<filename class="headerfile">jemalloc/jemalloc.h</filename>></funcsynopsisinfo>

      <refsect2>

        <title>Standard API</title>

        <funcprototype>

          <funcdef>void *<function>malloc</function></funcdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void *<function>calloc</function></funcdef>

          <paramdef>size_t <parameter>number</parameter></paramdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>int <function>posix_memalign</function></funcdef>

          <paramdef>void **<parameter>ptr</parameter></paramdef>

          <paramdef>size_t <parameter>alignment</parameter></paramdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void *<function>aligned_alloc</function></funcdef>

          <paramdef>size_t <parameter>alignment</parameter></paramdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void *<function>realloc</function></funcdef>

          <paramdef>void *<parameter>ptr</parameter></paramdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void <function>free</function></funcdef>

          <paramdef>void *<parameter>ptr</parameter></paramdef>

        </funcprototype>

      </refsect2>

      <refsect2>

        <title>Non-standard API</title>

        <funcprototype>

          <funcdef>void *<function>mallocx</function></funcdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

          <paramdef>int <parameter>flags</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void *<function>rallocx</function></funcdef>

          <paramdef>void *<parameter>ptr</parameter></paramdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

          <paramdef>int <parameter>flags</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>size_t <function>xallocx</function></funcdef>

          <paramdef>void *<parameter>ptr</parameter></paramdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

          <paramdef>size_t <parameter>extra</parameter></paramdef>

          <paramdef>int <parameter>flags</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>size_t <function>sallocx</function></funcdef>

          <paramdef>void *<parameter>ptr</parameter></paramdef>

          <paramdef>int <parameter>flags</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void <function>dallocx</function></funcdef>

          <paramdef>void *<parameter>ptr</parameter></paramdef>

          <paramdef>int <parameter>flags</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void <function>sdallocx</function></funcdef>

          <paramdef>void *<parameter>ptr</parameter></paramdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

          <paramdef>int <parameter>flags</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>size_t <function>nallocx</function></funcdef>

          <paramdef>size_t <parameter>size</parameter></paramdef>

          <paramdef>int <parameter>flags</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>int <function>mallctl</function></funcdef>

          <paramdef>const char *<parameter>name</parameter></paramdef>

          <paramdef>void *<parameter>oldp</parameter></paramdef>

          <paramdef>size_t *<parameter>oldlenp</parameter></paramdef>

          <paramdef>void *<parameter>newp</parameter></paramdef>

          <paramdef>size_t <parameter>newlen</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>int <function>mallctlnametomib</function></funcdef>

          <paramdef>const char *<parameter>name</parameter></paramdef>

          <paramdef>size_t *<parameter>mibp</parameter></paramdef>

          <paramdef>size_t *<parameter>miblenp</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>int <function>mallctlbymib</function></funcdef>

          <paramdef>const size_t *<parameter>mib</parameter></paramdef>

          <paramdef>size_t <parameter>miblen</parameter></paramdef>

          <paramdef>void *<parameter>oldp</parameter></paramdef>

          <paramdef>size_t *<parameter>oldlenp</parameter></paramdef>

          <paramdef>void *<parameter>newp</parameter></paramdef>

          <paramdef>size_t <parameter>newlen</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void <function>malloc_stats_print</function></funcdef>

          <paramdef>void <parameter>(*write_cb)</parameter>

            <funcparams>void *, const char *</funcparams>

          </paramdef>

          <paramdef>void *<parameter>cbopaque</parameter></paramdef>

          <paramdef>const char *<parameter>opts</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>size_t <function>malloc_usable_size</function></funcdef>

          <paramdef>const void *<parameter>ptr</parameter></paramdef>

        </funcprototype>

        <funcprototype>

          <funcdef>void <function>(*malloc_message)</function></funcdef>

          <paramdef>void *<parameter>cbopaque</parameter></paramdef>

          <paramdef>const char *<parameter>s</parameter></paramdef>

        </funcprototype>

        <para><type>const char *</type><varname>malloc_conf</varname>;</para>

      </refsect2>

    </funcsynopsis>

  </refsynopsisdiv>

  <refsect1 id="description">

    <title>DESCRIPTION</title>

    <refsect2>

      <title>Standard API</title>

      <para>The <function>malloc()</function> function allocates

      <parameter>size</parameter> bytes of uninitialized memory.  The allocated

      space is suitably aligned (after possible pointer coercion) for storage

      of any type of object.</para>

      <para>The <function>calloc()</function> function allocates

      space for <parameter>number</parameter> objects, each

      <parameter>size</parameter> bytes in length.  The result is identical to

      calling <function>malloc()</function> with an argument of

      <parameter>number</parameter> * <parameter>size</parameter>, with the

      exception that the allocated memory is explicitly initialized to zero

      bytes.</para>

      <para>The <function>posix_memalign()</function> function

      allocates <parameter>size</parameter> bytes of memory such that the

      allocation's base address is a multiple of

      <parameter>alignment</parameter>, and returns the allocation in the value

      pointed to by <parameter>ptr</parameter>.  The requested

      <parameter>alignment</parameter> must be a power of 2 at least as large as

      sizeof(<type>void *</type>).</para>

      <para>The <function>aligned_alloc()</function> function

      allocates <parameter>size</parameter> bytes of memory such that the

      allocation's base address is a multiple of

      <parameter>alignment</parameter>.  The requested

      <parameter>alignment</parameter> must be a power of 2.  Behavior is

      undefined if <parameter>size</parameter> is not an integral multiple of

      <parameter>alignment</parameter>.</para>

      <para>The <function>realloc()</function> function changes the

      size of the previously allocated memory referenced by

      <parameter>ptr</parameter> to <parameter>size</parameter> 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 <parameter>ptr</parameter> is freed and a pointer to the newly

      allocated memory is returned.  Note that

      <function>realloc()</function> may move the memory allocation,

      resulting in a different return value than <parameter>ptr</parameter>.

      If <parameter>ptr</parameter> is <constant>NULL</constant>, the

      <function>realloc()</function> function behaves identically to

      <function>malloc()</function> for the specified size.</para>

      <para>The <function>free()</function> function causes the

      allocated memory referenced by <parameter>ptr</parameter> to be made

      available for future allocations.  If <parameter>ptr</parameter> is

      <constant>NULL</constant>, no action occurs.</para>

    </refsect2>

    <refsect2>

      <title>Non-standard API</title>

      <para>The <function>mallocx()</function>,

      <function>rallocx()</function>,

      <function>xallocx()</function>,

      <function>sallocx()</function>,

      <function>dallocx()</function>,

      <function>sdallocx()</function>, and

      <function>nallocx()</function> functions all have a

      <parameter>flags</parameter> argument that can be used to specify

      options.  The functions only check the options that are contextually

      relevant.  Use bitwise or (|) operations to

      specify one or more of the following:

        <variablelist>

          <varlistentry id="MALLOCX_LG_ALIGN">

            <term><constant>MALLOCX_LG_ALIGN(<parameter>la</parameter>)

            </constant></term>

            <listitem><para>Align the memory allocation to start at an address

            that is a multiple of (1 <<

            <parameter>la</parameter>).  This macro does not validate

            that <parameter>la</parameter> is within the valid

            range.</para></listitem>

          </varlistentry>

          <varlistentry id="MALLOCX_ALIGN">

            <term><constant>MALLOCX_ALIGN(<parameter>a</parameter>)

            </constant></term>

            <listitem><para>Align the memory allocation to start at an address

            that is a multiple of <parameter>a</parameter>, where

            <parameter>a</parameter> is a power of two.  This macro does not

            validate that <parameter>a</parameter> is a power of 2.

            </para></listitem>

          </varlistentry>

          <varlistentry id="MALLOCX_ZERO">

            <term><constant>MALLOCX_ZERO</constant></term>

            <listitem><para>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 macro is

            absent, newly allocated memory is uninitialized.</para></listitem>

          </varlistentry>

          <varlistentry id="MALLOCX_TCACHE">

            <term><constant>MALLOCX_TCACHE(<parameter>tc</parameter>)

            </constant></term>

            <listitem><para>Use the thread-specific cache (tcache) specified by

            the identifier <parameter>tc</parameter>, which must have been

            acquired via the 

            linkend="tcache.create"><mallctl>tcache.create</mallctl></link>

            mallctl.  This macro does not validate that

            <parameter>tc</parameter> specifies a valid

            identifier.</para></listitem>

          </varlistentry>

          <varlistentry id="MALLOC_TCACHE_NONE">

            <term><constant>MALLOCX_TCACHE_NONE</constant></term>

            <listitem><para>Do not use a thread-specific cache (tcache).  Unless

            <constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant> or

            <constant>MALLOCX_TCACHE_NONE</constant> is specified, an

            automatically managed tcache will be used under many circumstances.

            This macro cannot be used in the same <parameter>flags</parameter>

            argument as

            <constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant>.</para></listitem>

          </varlistentry>

          <varlistentry id="MALLOCX_ARENA">

            <term><constant>MALLOCX_ARENA(<parameter>a</parameter>)

            </constant></term>

            <listitem><para>Use the arena specified by the index

            <parameter>a</parameter>.  This macro has no effect for regions that

            were allocated via an arena other than the one specified.  This

            macro does not validate that <parameter>a</parameter> specifies an

            arena index in the valid range.</para></listitem>

          </varlistentry>

        </variablelist>

      </para>

      <para>The <function>mallocx()</function> function allocates at

      least <parameter>size</parameter> bytes of memory, and returns a pointer

      to the base address of the allocation.  Behavior is undefined if

      <parameter>size</parameter> is <constant>0</constant>.</para>

      <para>The <function>rallocx()</function> function resizes the

      allocation at <parameter>ptr</parameter> to be at least

      <parameter>size</parameter> bytes, and returns a pointer to the base

      address of the resulting allocation, which may or may not have moved from

      its original location.  Behavior is undefined if

      <parameter>size</parameter> is <constant>0</constant>.</para>

      <para>The <function>xallocx()</function> function resizes the

      allocation at <parameter>ptr</parameter> in place to be at least

      <parameter>size</parameter> bytes, and returns the real size of the

      allocation.  If <parameter>extra</parameter> is non-zero, an attempt is

      made to resize the allocation to be at least 

      language="C">(<parameter>size</parameter> +

      <parameter>extra</parameter>) bytes, though inability to allocate

      the extra byte(s) will not by itself result in failure to resize.

      Behavior is undefined if <parameter>size</parameter> is

      <constant>0</constant>, or if 

      language="C">(<parameter>size</parameter> + <parameter>extra</parameter>

      > <constant>SIZE_T_MAX</constant>).</para>

      <para>The <function>sallocx()</function> function returns the

      real size of the allocation at <parameter>ptr</parameter>.</para>

      <para>The <function>dallocx()</function> function causes the

      memory referenced by <parameter>ptr</parameter> to be made available for

      future allocations.</para>

      <para>The <function>sdallocx()</function> function is an

      extension of <function>dallocx()</function> with a

      <parameter>size</parameter> parameter to allow the caller to pass in the

      allocation size as an optimization.  The minimum valid input size is the

      original requested size of the allocation, and the maximum valid input

      size is the corresponding value returned by

      <function>nallocx()</function> or

      <function>sallocx()</function>.</para>

      <para>The <function>nallocx()</function> function allocates no

      memory, but it performs the same size computation as the

      <function>mallocx()</function> function, and returns the real

      size of the allocation that would result from the equivalent

      <function>mallocx()</function> function call, or

      <constant>0</constant> if the inputs exceed the maximum supported size

      class and/or alignment.  Behavior is undefined if

      <parameter>size</parameter> is <constant>0</constant>.</para>

      <para>The <function>mallctl()</function> function provides a

      general interface for introspecting the memory allocator, as well as

      setting modifiable parameters and triggering actions.  The

      period-separated <parameter>name</parameter> argument specifies a

      location in a tree-structured namespace; see the 

      linkend="mallctl_namespace" xrefstyle="template:%t"/> section for

      documentation on the tree contents.  To read a value, pass a pointer via

      <parameter>oldp</parameter> to adequate space to contain the value, and a

      pointer to its length via <parameter>oldlenp</parameter>; otherwise pass

      <constant>NULL</constant> and <constant>NULL</constant>.  Similarly, to

      write a value, pass a pointer to the value via

      <parameter>newp</parameter>, and its length via

      <parameter>newlen</parameter>; otherwise pass <constant>NULL</constant>

      and <constant>0</constant>.</para>

      <para>The <function>mallctlnametomib()</function> function

      provides a way to avoid repeated name lookups for applications that

      repeatedly query the same portion of the namespace, by translating a name

      to a <quote>Management Information Base</quote> (MIB) that can be passed

      repeatedly to <function>mallctlbymib()</function>.  Upon

      successful return from <function>mallctlnametomib()</function>,

      <parameter>mibp</parameter> contains an array of

      <parameter>*miblenp</parameter> integers, where

      <parameter>*miblenp</parameter> is the lesser of the number of components

      in <parameter>name</parameter> and the input value of

      <parameter>*miblenp</parameter>.  Thus it is possible to pass a

      <parameter>*miblenp</parameter> that is smaller than the number of

      period-separated name components, which results in a partial MIB that can

      be used as the basis for constructing a complete MIB.  For name

      components that are integers (e.g. the 2 in

      linkend="arenas.bin.i.size"><mallctl>arenas.bin.2.size</mallctl></link>),

      the corresponding MIB component will always be that integer.  Therefore,

      it is legitimate to construct code like the following: 

      language="C">

unsigned nbins, i;

size_t mib[4];

size_t len, miblen;

len = sizeof(nbins);

mallctl("arenas.nbins", &nbins, &len, NULL, 0);

miblen = 4;

mallctlnametomib("arenas.bin.0.size", mib, &miblen);

for (i = 0; i < nbins; i++) {

	size_t bin_size;

	mib[2] = i;

	len = sizeof(bin_size);

	mallctlbymib(mib, miblen, (void *)&bin_size, &len, NULL, 0);

	/* Do something with bin_size... */

}]]></programlisting></para>

      <varlistentry id="malloc_stats_print_opts">

      </varlistentry>

      <para>The <function>malloc_stats_print()</function> function writes

      summary statistics via the <parameter>write_cb</parameter> callback

      function pointer and <parameter>cbopaque</parameter> data passed to

      <parameter>write_cb</parameter>, or <function>malloc_message()</function>

      if <parameter>write_cb</parameter> is <constant>NULL</constant>.  The

      statistics are presented in human-readable form unless <quote>J</quote> is

      specified as a character within the <parameter>opts</parameter> string, in

      which case the statistics are presented in 

      url="http://www.json.org/">JSON format</ulink>.  This function can be

      called repeatedly.  General information that never changes during

      execution can be omitted by specifying <quote>g</quote> as a character

      within the <parameter>opts</parameter> string.  Note that

      <function>malloc_stats_print()</function> uses the

      <function>mallctl*()</function> functions internally, so inconsistent

      statistics can be reported if multiple threads use these functions

      simultaneously.  If <option>--enable-stats</option> is specified during

      configuration, <quote>m</quote>, <quote>d</quote>, and <quote>a</quote>

      can be specified to omit merged arena, destroyed merged arena, and per

      arena statistics, respectively; <quote>b</quote> and <quote>l</quote> can

      be specified to omit per size class statistics for bins and large objects,

      respectively; <quote>x</quote> can be specified to omit all mutex

      statistics; <quote>e</quote> can be used to omit extent statistics.

      Unrecognized characters are silently ignored.  Note that thread caching

      may prevent some statistics from being completely up to date, since extra

      locking would be required to merge counters that track thread cache

      operations.</para>

      <para>The <function>malloc_usable_size()</function> function

      returns the usable size of the allocation pointed to by

      <parameter>ptr</parameter>.  The return value may be larger than the size

      that was requested during allocation.  The

      <function>malloc_usable_size()</function> function is not a

      mechanism for in-place <function>realloc()</function>; rather

      it is provided solely as a tool for introspection purposes.  Any

      discrepancy between the requested allocation size and the size reported

      by <function>malloc_usable_size()</function> should not be

      depended on, since such behavior is entirely implementation-dependent.

      </para>

    </refsect2>

  </refsect1>

  <refsect1 id="tuning">

    <title>TUNING</title>

    <para>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.</para>

    <para>The string specified via <option>--with-malloc-conf</option>, the

    string pointed to by the global variable <varname>malloc_conf</varname>, the

    <quote>name</quote> of the file referenced by the symbolic link named

    <filename class="symlink">/etc/malloc.conf</filename>, and the value of the

    environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in

    that order, from left to right as options.  Note that

    <varname>malloc_conf</varname> may be read before

    <function>main()</function> is entered, so the declaration of

    <varname>malloc_conf</varname> should specify an initializer that contains

    the final value to be read by jemalloc.  <option>--with-malloc-conf</option>

    and <varname>malloc_conf</varname> are compile-time mechanisms, whereas

    <filename class="symlink">/etc/malloc.conf</filename> and

    <envar>MALLOC_CONF</envar> can be safely set any time prior to program

    invocation.</para>

    <para>An options string is a comma-separated list of option:value pairs.

    There is one key corresponding to each 

    linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the 

    linkend="mallctl_namespace" xrefstyle="template:%t"/> section for options

    documentation).  For example, <literal>abort:true,narenas:1</literal> sets

    the <link linkend="opt.abort"><mallctl>opt.abort</mallctl></link> and 

    linkend="opt.narenas"><mallctl>opt.narenas</mallctl></link> 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.</para>

  </refsect1>

  <refsect1 id="implementation_notes">

    <title>IMPLEMENTATION NOTES</title>

    <para>Traditionally, allocators have used

    <citerefentry><refentrytitle>sbrk</refentrytitle>

    <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is

    suboptimal for several reasons, including race conditions, increased

    fragmentation, and artificial limitations on maximum usable memory.  If

    <citerefentry><refentrytitle>sbrk</refentrytitle>

    <manvolnum>2</manvolnum></citerefentry> is supported by the operating

    system, this allocator uses both

    <citerefentry><refentrytitle>mmap</refentrytitle>

    <manvolnum>2</manvolnum></citerefentry> and

    <citerefentry><refentrytitle>sbrk</refentrytitle>

    <manvolnum>2</manvolnum></citerefentry>, in that order of preference;

    otherwise only <citerefentry><refentrytitle>mmap</refentrytitle>

    <manvolnum>2</manvolnum></citerefentry> is used.</para>

    <para>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.</para>

    <para>In addition to multiple arenas, this allocator supports

    thread-specific caching, 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.</para>

    <para>Memory is conceptually broken into extents.  Extents are always

    aligned to multiples of the page size.  This alignment makes it possible to

    find metadata for user objects quickly.  User objects are broken into two

    categories according to size: small and large.  Contiguous small objects

    comprise a slab, which resides within a single extent, whereas large objects

    each have their own extents backing them.</para>

    <para>Small objects are managed in groups by slabs.  Each slab maintains

    a bitmap to track which regions are in use.  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 

    language="C">sizeof(<type>double</type>).  All other object size

    classes are multiples of the quantum, spaced such that there are four size

    classes for each doubling in size, which limits internal fragmentation to

    approximately 20% for all but the smallest size classes.  Small size classes

    are smaller than four times the page size, and large size classes extend

    from four times the page size up to the largest size class that does not

    exceed <constant>PTRDIFF_MAX</constant>.</para>

    <para>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.</para>

    <para>The <function>realloc()</function>,

    <function>rallocx()</function>, and

    <function>xallocx()</function> functions may resize allocations

    without moving them under limited circumstances.  Unlike the

    <function>*allocx()</function> API, the standard API does not

    officially round up the usable size of an allocation to the nearest size

    class, so technically it is necessary to call

    <function>realloc()</function> to grow e.g. a 9-byte allocation to

    16 bytes, or shrink a 16-byte allocation to 9 bytes.  Growth and shrinkage

    trivially succeeds in place as long as the pre-size and post-size both round

    up to the same size class.  No other API guarantees are made regarding

    in-place resizing, but the current implementation also tries to resize large

    allocations in place, as long as the pre-size and post-size are both large.

    For shrinkage to succeed, the extent allocator must support splitting (see

    linkend="arena.i.extent_hooks"><mallctl>arena.<i>.extent_hooks</mallctl></link>).

    Growth only succeeds if the trailing memory is currently available, and the

    extent allocator supports merging.</para>

    <para>Assuming 4 KiB pages and a 16-byte quantum on a 64-bit system, the

    size classes in each category are as shown in 

    xrefstyle="template:Table %n"/>.</para>

      <title>Size classes</title>

      <tgroup cols="3" colsep="1" rowsep="1">

      <colspec colname="c1" align="left"/>

      <colspec colname="c2" align="right"/>

      <colspec colname="c3" align="left"/>

        <row>

          <entry>Category</entry>

          <entry>Spacing</entry>

          <entry>Size</entry>

        </row>

        <row>

          <entry morerows="8">Small</entry>

          <entry>lg</entry>

          <entry>[8]</entry>

        </row>

        <row>

          <entry>16</entry>

          <entry>[16, 32, 48, 64, 80, 96, 112, 128]</entry>

        </row>

        <row>

          <entry>32</entry>

          <entry>[160, 192, 224, 256]</entry>

        </row>

        <row>

          <entry>64</entry>

          <entry>[320, 384, 448, 512]</entry>

        </row>

        <row>

          <entry>128</entry>

          <entry>[640, 768, 896, 1024]</entry>

        </row>

        <row>

          <entry>256</entry>

          <entry>[1280, 1536, 1792, 2048]</entry>

        </row>

        <row>

          <entry>512</entry>

          <entry>[2560, 3072, 3584, 4096]</entry>

        </row>

        <row>

          <entry>1 KiB</entry>

          <entry>[5 KiB, 6 KiB, 7 KiB, 8 KiB]</entry>

        </row>

        <row>

          <entry>2 KiB</entry>

          <entry>[10 KiB, 12 KiB, 14 KiB]</entry>

        </row>

        <row>

          <entry morerows="15">Large</entry>

          <entry>2 KiB</entry>

          <entry>[16 KiB]</entry>

        </row>

        <row>

          <entry>4 KiB</entry>

          <entry>[20 KiB, 24 KiB, 28 KiB, 32 KiB]</entry>

        </row>

        <row>

          <entry>8 KiB</entry>

          <entry>[40 KiB, 48 KiB, 54 KiB, 64 KiB]</entry>

        </row>

        <row>

          <entry>16 KiB</entry>

          <entry>[80 KiB, 96 KiB, 112 KiB, 128 KiB]</entry>

        </row>

        <row>

          <entry>32 KiB</entry>

          <entry>[160 KiB, 192 KiB, 224 KiB, 256 KiB]</entry>

        </row>

        <row>

          <entry>64 KiB</entry>

          <entry>[320 KiB, 384 KiB, 448 KiB, 512 KiB]</entry>

        </row>

        <row>

          <entry>128 KiB</entry>

          <entry>[640 KiB, 768 KiB, 896 KiB, 1 MiB]</entry>

        </row>

        <row>

          <entry>256 KiB</entry>

          <entry>[1280 KiB, 1536 KiB, 1792 KiB, 2 MiB]</entry>

        </row>

        <row>

          <entry>512 KiB</entry>

          <entry>[2560 KiB, 3 MiB, 3584 KiB, 4 MiB]</entry>

        </row>

        <row>

          <entry>1 MiB</entry>

          <entry>[5 MiB, 6 MiB, 7 MiB, 8 MiB]</entry>

        </row>

        <row>

          <entry>2 MiB</entry>

          <entry>[10 MiB, 12 MiB, 14 MiB, 16 MiB]</entry>

        </row>

        <row>

          <entry>4 MiB</entry>

          <entry>[20 MiB, 24 MiB, 28 MiB, 32 MiB]</entry>

        </row>

        <row>

          <entry>8 MiB</entry>

          <entry>[40 MiB, 48 MiB, 56 MiB, 64 MiB]</entry>

        </row>

        <row>

          <entry>...</entry>

          <entry>...</entry>

        </row>

        <row>

          <entry>512 PiB</entry>

          <entry>[2560 PiB, 3 EiB, 3584 PiB, 4 EiB]</entry>

        </row>

        <row>

          <entry>1 EiB</entry>

          <entry>[5 EiB, 6 EiB, 7 EiB]</entry>

        </row>

      </tgroup>

  </refsect1>

  <refsect1 id="mallctl_namespace">

    <title>MALLCTL NAMESPACE</title>

    <para>The following names are defined in the namespace accessible via the

    <function>mallctl*()</function> functions.  Value types are specified in

    parentheses, their readable/writable statuses are encoded as

    <literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or

    <literal>--</literal>, and required build configuration flags follow, if

    any.  A name element encoded as <literal><i></literal> or

    <literal><j></literal> indicates an integer component, where the

    integer varies from 0 to some upper value that must be determined via

    introspection.  In the case of <mallctl>stats.arenas.<i>.*</mallctl>

    and <mallctl>arena.<i>.{initialized,purge,decay,dss}</mallctl>,

    <literal><i></literal> equal to

    <constant>MALLCTL_ARENAS_ALL</constant> can be used to operate on all arenas

    or access the summation of statistics from all arenas; similarly

    <literal><i></literal> equal to

    <constant>MALLCTL_ARENAS_DESTROYED</constant> can be used to access the

    summation of statistics from all destroyed arenas.  These constants can be

    utilized either via <function>mallctlnametomib()</function> followed by

    <function>mallctlbymib()</function>, or via code such as the following:

    <programlisting language="C">

#define STRINGIFY_HELPER(x) #x

#define STRINGIFY(x) STRINGIFY_HELPER(x)

mallctl("arena." STRINGIFY(MALLCTL_ARENAS_ALL) ".decay",

    NULL, NULL, NULL, 0);]]></programlisting>

    Take special note of the 

    linkend="epoch"><mallctl>epoch</mallctl></link> mallctl, which controls

    refreshing of cached dynamic statistics.</para>

    <variablelist>

      <varlistentry id="version">

        <term>

          <mallctl>version</mallctl>

          (<type>const char *</type>)

          <literal>r-</literal>

        </term>

        <listitem><para>Return the jemalloc version string.</para></listitem>

      </varlistentry>

      <varlistentry id="epoch">

        <term>

          <mallctl>epoch</mallctl>

          (<type>uint64_t</type>)

          <literal>rw</literal>

        </term>

        <listitem><para>If a value is passed in, refresh the data from which

        the <function>mallctl*()</function> functions report values,

        and increment the epoch.  Return the current epoch.  This is useful for

        detecting whether another thread caused a refresh.</para></listitem>

      </varlistentry>

      <varlistentry id="background_thread">

        <term>

          <mallctl>background_thread</mallctl>

          (<type>bool</type>)

          <literal>rw</literal>

        </term>

        <listitem><para>Enable/disable internal background worker threads.  When

        set to true, background threads are created on demand (the number of

        background threads will be no more than the number of CPUs or active

        arenas).  Threads run periodically, and handle 

        linkend="arena.i.decay">purging</link> asynchronously.  When switching

        off, background threads are terminated synchronously.  Note that after

        <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>

        function, the state in the child process will be disabled regardless

        the state in parent process. See 

        linkend="stats.background_thread.num_threads"><mallctl>stats.background_thread</mallctl></link>

        for related stats.  

        linkend="opt.background_thread"><mallctl>opt.background_thread</mallctl></link>

        can be used to set the default option.  This option is only available on

        selected pthread-based platforms.</para></listitem>

      </varlistentry>

      <varlistentry id="max_background_threads">

        <term>

          <mallctl>max_background_threads</mallctl>

          (<type>size_t</type>)

          <literal>rw</literal>

        </term>

        <listitem><para>Maximum number of background worker threads that will

        be created.  This value is capped at 

        linkend="opt.max_background_threads"><mallctl>opt.max_background_threads</mallctl></link> at

        startup.</para></listitem>

      </varlistentry>

      <varlistentry id="config.cache_oblivious">

        <term>

          <mallctl>config.cache_oblivious</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--enable-cache-oblivious</option> was specified

        during build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.debug">

        <term>

          <mallctl>config.debug</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--enable-debug</option> was specified during

        build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.fill">

        <term>

          <mallctl>config.fill</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--enable-fill</option> was specified during

        build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.lazy_lock">

        <term>

          <mallctl>config.lazy_lock</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--enable-lazy-lock</option> was specified

        during build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.malloc_conf">

        <term>

          <mallctl>config.malloc_conf</mallctl>

          (<type>const char *</type>)

          <literal>r-</literal>

        </term>

        <listitem><para>Embedded configure-time-specified run-time options

        string, empty unless <option>--with-malloc-conf</option> was specified

        during build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.prof">

        <term>

          <mallctl>config.prof</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--enable-prof</option> was specified during

        build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.prof_libgcc">

        <term>

          <mallctl>config.prof_libgcc</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--disable-prof-libgcc</option> was not

        specified during build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.prof_libunwind">

        <term>

          <mallctl>config.prof_libunwind</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--enable-prof-libunwind</option> was specified

        during build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.stats">

        <term>

          <mallctl>config.stats</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--enable-stats</option> was specified during

        build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.utrace">

        <term>

          <mallctl>config.utrace</mallctl>

          (<type>bool</type>)

          <literal>r-</literal>

        </term>

        <listitem><para><option>--enable-utrace</option> was specified during

        build configuration.</para></listitem>

      </varlistentry>

      <varlistentry id="config.xmalloc">