diff options
| author | Jason Evans <jasone@canonware.com> | 2011-04-01 03:36:17 (GMT) |
|---|---|---|
| committer | Jason Evans <jasone@canonware.com> | 2011-04-01 03:36:17 (GMT) |
| commit | 7427525c28d58c423a68930160e3b0fe577fe953 (patch) | |
| tree | 471519cfe8e156dfaa8e3f6f4f7d92db423b81f3 /doc | |
| parent | 64ba3d7cd9901ed00d690365b1b3da6aa7b9cd59 (diff) | |
| download | jemalloc-7427525c28d58c423a68930160e3b0fe577fe953.zip jemalloc-7427525c28d58c423a68930160e3b0fe577fe953.tar.gz jemalloc-7427525c28d58c423a68930160e3b0fe577fe953.tar.bz2 | |
Move repo contents in jemalloc/ to top level.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/html.xsl.in | 4 | ||||
| -rw-r--r-- | doc/jemalloc.xml.in | 2280 | ||||
| -rw-r--r-- | doc/manpages.xsl.in | 4 | ||||
| -rw-r--r-- | doc/stylesheet.xsl | 7 |
4 files changed, 2295 insertions, 0 deletions
diff --git a/doc/html.xsl.in b/doc/html.xsl.in new file mode 100644 index 0000000..a91d974 --- /dev/null +++ b/doc/html.xsl.in @@ -0,0 +1,4 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:import href="@XSLROOT@/html/docbook.xsl"/> + <xsl:import href="@abs_srcroot@doc/stylesheet.xsl"/> +</xsl:stylesheet> diff --git a/doc/jemalloc.xml.in b/doc/jemalloc.xml.in new file mode 100644 index 0000000..13f3aae --- /dev/null +++ b/doc/jemalloc.xml.in @@ -0,0 +1,2280 @@ +<?xml version='1.0' encoding='UTF-8'?> +<?xml-stylesheet type="text/xsl" + href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "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> + <!-- Each refname causes a man page file to be created. Only if this were + the system malloc(3) implementation would these files be appropriate. + <refname>malloc</refname> + <refname>calloc</refname> + <refname>posix_memalign</refname> + <refname>realloc</refname> + <refname>free</refname> + <refname>malloc_usable_size</refname> + <refname>malloc_stats_print</refname> + <refname>mallctl</refname> + <refname>mallctlnametomib</refname> + <refname>mallctlbymib</refname> + <refname>allocm</refname> + <refname>rallocm</refname> + <refname>sallocm</refname> + <refname>dallocm</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 <ulink + url="http://www.canonware.com/jemalloc/">jemalloc website</ulink>.</para> + </refsect1> + <refsynopsisdiv> + <title>SYNOPSIS</title> + <funcsynopsis> + <funcsynopsisinfo>#include <<filename class="headerfile">stdlib.h</filename>> +#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>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>size_t <function>malloc_usable_size</function></funcdef> + <paramdef>const void *<parameter>ptr</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>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_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> + <refsect2> + <title>Experimental API</title> + <funcprototype> + <funcdef>int <function>allocm</function></funcdef> + <paramdef>void **<parameter>ptr</parameter></paramdef> + <paramdef>size_t *<parameter>rsize</parameter></paramdef> + <paramdef>size_t <parameter>size</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>rallocm</function></funcdef> + <paramdef>void **<parameter>ptr</parameter></paramdef> + <paramdef>size_t *<parameter>rsize</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>int <function>sallocm</function></funcdef> + <paramdef>const void *<parameter>ptr</parameter></paramdef> + <paramdef>size_t *<parameter>rsize</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>dallocm</function></funcdef> + <paramdef>void *<parameter>ptr</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + </refsect2> + </funcsynopsis> + </refsynopsisdiv> + <refsect1 id="description"> + <title>DESCRIPTION</title> + <refsect2> + <title>Standard API</title> + + <para>The <function>malloc<parameter/></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<parameter/></function> function allocates + space for <parameter>number</parameter> objects, each + <parameter>size</parameter> bytes in length. The result is identical to + calling <function>malloc<parameter/></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<parameter/></function> function + allocates <parameter>size</parameter> bytes of memory such that the + allocation's base address is an even 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 <code language="C">sizeof(<type>void *</type>)</code>.</para> + + <para>The <function>realloc<parameter/></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<parameter/></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<parameter/></function> function behaves identically to + <function>malloc<parameter/></function> for the specified size.</para> + + <para>The <function>free<parameter/></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>malloc_usable_size<parameter/></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<parameter/></function> function is not a + mechanism for in-place <function>realloc<parameter/></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<parameter/></function> should not be + depended on, since such behavior is entirely implementation-dependent. + </para> + + <para>The <function>malloc_stats_print<parameter/></function> function + writes human-readable 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<parameter/></function> if + <parameter>write_cb</parameter> is <constant>NULL</constant>. This + function can be called repeatedly. General information that never + changes during execution can be omitted by specifying "g" as a character + within the <parameter>opts</parameter> string. Note that + <function>malloc_message<parameter/></function> uses the + <function>mallctl*<parameter/></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, “m” and “a” can + be specified to omit merged arena and per arena statistics, respectively; + “b” and “l” can be specified to omit per size + class statistics for bins and large objects, respectively. 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>mallctl<parameter/></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 <xref + 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<parameter/></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 “Management Information Base” (MIB) that can be passed + repeatedly to <function>mallctlbymib<parameter/></function>. Upon + successful return from <function>mallctlnametomib<parameter/></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 + <link + 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: <programlisting + language="C"><![CDATA[ +unsigned nbins, i; + +int mib[4]; +size_t len, miblen; + +len = sizeof(nbins); +mallctl("arenas.nbins", &nbins, &len, NULL, 0); + +miblen = 4; +mallnametomib("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, &bin_size, &len, NULL, 0); + /* Do something with bin_size... */ +}]]></programlisting></para> + </refsect2> + <refsect2> + <title>Experimental API</title> + <para>The experimental API is subject to change or removal without regard + for backward compatibility.</para> + + <para>The <function>allocm<parameter/></function>, + <function>rallocm<parameter/></function>, + <function>sallocm<parameter/></function>, and + <function>dallocm<parameter/></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 (<code language="C">|</code>) operations to + specify one or more of the following: + <variablelist> + <varlistentry> + <term><constant>ALLOCM_LG_ALIGN(<parameter>la</parameter>) + </constant></term> + + <listitem><para>Align the memory allocation to start at an address + that is a multiple of <code language="C">(1 << + <parameter>la</parameter>)</code>. This macro does not validate + that <parameter>la</parameter> is within the valid + range.</para></listitem> + </varlistentry> + <varlistentry> + <term><constant>ALLOCM_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> + <term><constant>ALLOCM_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 option is + absent, newly allocated memory is uninitialized.</para></listitem> + </varlistentry> + <varlistentry> + <term><constant>ALLOCM_NO_MOVE</constant></term> + + <listitem><para>For reallocation, fail rather than moving the + object. This constraint can apply to both growth and + shrinkage.</para></listitem> + </varlistentry> + </variablelist> + </para> + + <para>The <function>allocm<parameter/></function> function allocates at + least <parameter>size</parameter> bytes of memory, sets + <parameter>*ptr</parameter> to the base address of the allocation, and + sets <parameter>*rsize</parameter> to the real size of the allocation if + <parameter>rsize</parameter> is not <constant>NULL</constant>.</para> + + <para>The <function>rallocm<parameter/></function> function resizes the + allocation at <parameter>*ptr</parameter> to be at least + <parameter>size</parameter> bytes, sets <parameter>*ptr</parameter> to + the base address of the allocation if it moved, and sets + <parameter>*rsize</parameter> to the real size of the allocation if + <parameter>rsize</parameter> is not <constant>NULL</constant>. If + <parameter>extra</parameter> is non-zero, an attempt is made to resize + the allocation to be at least <code + language="C"><parameter>size</parameter> + + <parameter>extra</parameter>)</code> bytes, though inability to allocate + the extra byte(s) will not by itself result in failure. Behavior is + undefined if <code language="C">(<parameter>size</parameter> + + <parameter>extra</parameter> > + <constant>SIZE_T_MAX</constant>)</code>.</para> + + <para>The <function>sallocm<parameter/></function> function sets + <parameter>*rsize</parameter> to the real size of the allocation.</para> + + <para>The <function>dallocm<parameter/></function> function causes the + memory referenced by <parameter>ptr</parameter> to be made available for + future allocations.</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 pointed to by the global variable + <varname>malloc_conf</varname>, the “name” 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.</para> + + <para>An options string is a comma-separated list of option:value pairs. + There is one key corresponding to each <link + linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the <xref + 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 <link + 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 + <option>--enable-dss</option> is specified during configuration, this + allocator uses both <citerefentry><refentrytitle>sbrk</refentrytitle> + <manvolnum>2</manvolnum></citerefentry> and + <citerefentry><refentrytitle>mmap</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, unless + <option>--disable-tcache</option> 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.</para> + + <para>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.</para> + + <para>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.</para> + + <para>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.</para> + + <para>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 + <option>--disable-tiny</option> 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 <code language="C">sizeof(<type>void *</type>)</code>. + Allocation requests that are more than half the quantum, but no more than + the minimum cacheline-multiple size class (see the <link + linkend="opt.lg_qspace_max"><mallctl>opt.lg_qspace_max</mallctl></link> + 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 <link + linkend="opt.lg_cspace_max"><mallctl>opt.lg_cspace_max</mallctl></link> + 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 <link + linkend="opt.lg_chunk"><mallctl>opt.lg_chunk</mallctl></link> 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.</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>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 <xref + linkend="size_classes" xrefstyle="template:Table %n"/>.</para> + + <table xml:id="size_classes" frame="all"> + <title>Size classes</title> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <colspec colname="c3"/> + <thead> + <row> + <entry>Category</entry> + <entry>Subcategory</entry> + <entry>Size</entry> + </row> + </thead> + <tbody> + <row> + <entry morerows="3">Small</entry> + <entry>Tiny</entry> + <entry>[8]</entry> + </row> + <row> + <entry>Quantum-spaced</entry> + <entry>[16, 32, 48, ..., 128]</entry> + </row> + <row> + <entry>Cacheline-spaced</entry> + <entry>[192, 256, 320, ..., 512]</entry> + </row> + <row> + <entry>Subpage-spaced</entry> + <entry>[768, 1024, 1280, ..., 3840]</entry> + </row> + <row> + <entry namest="c1" nameend="c2">Large</entry> + <entry>[4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB]</entry> + </row> + <row> + <entry namest="c1" nameend="c2">Huge</entry> + <entry>[4 MiB, 8 MiB, 12 MiB, ...]</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + <refsect1 id="mallctl_namespace"> + <title>MALLCTL NAMESPACE</title> + <para>The following names are defined in the namespace accessible via the + <function>mallctl*<parameter/></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>, + <literal><i></literal> equal to <link + linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> can be + used to access the summation of statistics from all arenas. Take special + note of the <link linkend="epoch"><mallctl>epoch</mallctl></link> mallctl, + which controls refreshing of cached dynamic statistics.</para> + + <variablelist> + <varlistentry> + <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*<parameter/></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> + <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> + <term> + <mallctl>config.dss</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para><option>--enable-dss</option> was specified during + build configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>config.dynamic_page_shift</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para><option>--enable-dynamic-page-shift</option> was + specified during build configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <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> + <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> + <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> + <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> + <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> + <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> + <term> + <mallctl>config.swap</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para><option>--enable-swap</option> was specified during + build configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>config.sysv</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para><option>--enable-sysv</option> was specified during + build configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>config.tcache</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para><option>--disable-tcache</option> was not specified + during build configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>config.tiny</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para><option>--disable-tiny</option> was not specified + during build configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>config.tls</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para><option>--disable-tls</option> was not specified during + build configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>config.xmalloc</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para><option>--enable-xmalloc</option> was specified during + build configuration.</para></listitem> + </varlistentry> + + <varlistentry id="opt.abort"> + <term> + <mallctl>opt.abort</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para>Abort-on-warning enabled/disabled. If true, most + warnings are fatal. The process will call + <citerefentry><refentrytitle>abort</refentrytitle> + <manvolnum>3</manvolnum></citerefentry> in these cases. This option is + disabled by default unless <option>--enable-debug</option> is + specified during configuration, in which case it is enabled by default. + </para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_qspace_max"> + <term> + <mallctl>opt.lg_qspace_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Size (log base 2) of the maximum size class that is a + multiple of the quantum (8 or 16 bytes, depending on architecture). + Above this size, cacheline spacing is used for size classes. The + default value is 128 bytes (2^7).</para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_cspace_max"> + <term> + <mallctl>opt.lg_cspace_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Size (log base 2) of the maximum size class that is a + multiple of the cacheline size (64). Above this size, subpage spacing + (256 bytes) is used for size classes. The default value is 512 bytes + (2^9).</para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_chunk"> + <term> + <mallctl>opt.lg_chunk</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Virtual memory chunk size (log base 2). The default + chunk size is 4 MiB (2^22).</para></listitem> + </varlistentry> + + <varlistentry id="opt.narenas"> + <term> + <mallctl>opt.narenas</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Maximum number of arenas to use. The default maximum + number of arenas is four times the number of CPUs, or one if there is a + single CPU.</para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_dirty_mult"> + <term> + <mallctl>opt.lg_dirty_mult</mallctl> + (<type>ssize_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Per-arena minimum ratio (log base 2) of active to dirty + pages. Some dirty unused pages may be allowed to accumulate, within + the limit set by the ratio (or one chunk worth of dirty pages, + whichever is greater), before informing the kernel about some of those + pages via <citerefentry><refentrytitle>madvise</refentrytitle> + <manvolnum>2</manvolnum></citerefentry> or a similar system call. This + provides the kernel with sufficient information to recycle dirty pages + if physical memory becomes scarce and the pages remain unused. The + default minimum ratio is 32:1 (2^5:1); an option value of -1 will + disable dirty page purging.</para></listitem> + </varlistentry> + + <varlistentry id="opt.stats_print"> + <term> + <mallctl>opt.stats_print</mallctl> + (<type>bool</type>) + <literal>r-</literal> + </term> + <listitem><para>Enable/disable statistics printing at exit. If + enabled, the <function>malloc_stats_print<parameter/></function> + function is called at program exit via an + <citerefentry><refentrytitle>atexit</refentrytitle> + <manvolnum>3</manvolnum></citerefentry> function. If + <option>--enable-stats</option> is specified during configuration, this + has the potential to cause deadlock for a multi-threaded process that + exits while one or more threads are executing in the memory allocation + functions. Therefore, this option should only be used with care; it is + primarily intended as a performance tuning aid during application + development. This option is disabled by default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.junk"> + <term> + <mallctl>opt.junk</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-fill</option>] + </term> + <listitem><para>Junk filling enabled/disabled. If enabled, each byte + of uninitialized allocated memory will be initialized to + <literal>0xa5</literal>. All deallocated memory will be initialized to + <literal>0x5a</literal>. This is intended for debugging and will + impact performance negatively. This option is disabled by default + unless <option>--enable-debug</option> is specified during + configuration, in which case it is enabled by default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.zero"> + <term> + <mallctl>opt.zero</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-fill</option>] + </term> + <listitem><para>Zero filling enabled/disabled. If enabled, each byte + of uninitialized allocated memory will be initialized to 0. Note that + this initialization only happens once for each byte, so + <function>realloc<parameter/></function> and + <function>rallocm<parameter/></function> calls do not zero memory that + was previously allocated. This is intended for debugging and will + impact performance negatively. This option is disabled by default. + </para></listitem> + </varlistentry> + + <varlistentry id="opt.sysv"> + <term> + <mallctl>opt.sysv</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-sysv</option>] + </term> + <listitem><para>If enabled, attempting to allocate zero bytes will + return a <constant>NULL</constant> pointer instead of a valid pointer. + (The default behavior is to make a minimal allocation and return a + pointer to it.) This option is provided for System V compatibility. + This option is incompatible with the <link + linkend="opt.xmalloc"><mallctl>opt.xmalloc</mallctl></link> option. + This option is disabled by default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.xmalloc"> + <term> + <mallctl>opt.xmalloc</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-xmalloc</option>] + </term> + <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled, + rather than returning failure for any allocation function, display a + diagnostic message on <constant>STDERR_FILENO</constant> and cause the + program to drop core (using + <citerefentry><refentrytitle>abort</refentrytitle> + <manvolnum>3</manvolnum></citerefentry>). If an application is + designed to depend on this behavior, set the option at compile time by + including the following in the source code: + <programlisting language="C"><![CDATA[ +malloc_conf = "xmalloc:true";]]></programlisting> + This option is disabled by default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.tcache"> + <term> + <mallctl>opt.tcache</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-tcache</option>] + </term> + <listitem><para>Thread-specific caching enabled/disabled. When there + are multiple threads, each thread uses a thread-specific cache for + objects up to a certain size. Thread-specific caching allows many + allocations to be satisfied without performing any thread + synchronization, at the cost of increased memory use. See the + <link + linkend="opt.lg_tcache_gc_sweep"><mallctl>opt.lg_tcache_gc_sweep</mallctl></link> + and <link + linkend="opt.lg_tcache_max"><mallctl>opt.lg_tcache_max</mallctl></link> + options for related tuning information. This option is enabled by + default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_tcache_gc_sweep"> + <term> + <mallctl>opt.lg_tcache_gc_sweep</mallctl> + (<type>ssize_t</type>) + <literal>r-</literal> + [<option>--enable-tcache</option>] + </term> + <listitem><para>Approximate interval (log base 2) between full + thread-specific cache garbage collection sweeps, counted in terms of + thread-specific cache allocation/deallocation events. Garbage + collection is actually performed incrementally, one size class at a + time, in order to avoid large collection pauses. The default sweep + interval is 8192 (2^13); setting this option to -1 will disable garbage + collection.</para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_tcache_max"> + <term> + <mallctl>opt.lg_tcache_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-tcache</option>] + </term> + <listitem><para>Maximum size class (log base 2) to cache in the + thread-specific cache. At a minimum, all small size classes are + cached, and at a maximum all large size classes are cached. The + default maximum is 32 KiB (2^15).</para></listitem> + </varlistentry> + + <varlistentry id="opt.prof"> + <term> + <mallctl>opt.prof</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Memory profiling enabled/disabled. If enabled, profile + memory allocation activity, and use an + <citerefentry><refentrytitle>atexit</refentrytitle> + <manvolnum>3</manvolnum></citerefentry> function to dump final memory + usage to a file named according to the pattern + <filename><prefix>.<pid>.<seq>.f.heap</filename>, + where <literal><prefix></literal> is controlled by the <link + linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> + option. See the <link + linkend="opt.lg_prof_bt_max"><mallctl>opt.lg_prof_bt_max</mallctl></link> + option for backtrace depth control. See the <link + linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> + option for on-the-fly activation/deactivation. See the <link + linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> + option for probabilistic sampling control. See the <link + linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> + option for control of cumulative sample reporting. See the <link + linkend="opt.lg_prof_tcmax"><mallctl>opt.lg_prof_tcmax</mallctl></link> + option for control of per thread backtrace caching. See the <link + linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> + option for information on interval-triggered profile dumping, and the + <link linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link> + option for information on high-water-triggered profile dumping. + Profile output is compatible with the included <command>pprof</command> + Perl script, which originates from the <ulink + url="http://code.google.com/p/google-perftools/">google-perftools + package</ulink>.</para></listitem> + </varlistentry> + + <varlistentry id="opt.prof_prefix"> + <term> + <mallctl>opt.prof_prefix</mallctl> + (<type>const char *</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Filename prefix for profile dumps. If the prefix is + set to the empty string, no automatic dumps will occur; this is + primarily useful for disabling the automatic final heap dump (which + also disables leak reporting, if enabled). The default prefix is + <filename>jeprof</filename>.</para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_prof_bt_max"> + <term> + <mallctl>opt.lg_prof_bt_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Maximum backtrace depth (log base 2) when profiling + memory allocation activity. The default is 128 (2^7).</para></listitem> + </varlistentry> + + <varlistentry id="opt.prof_active"> + <term> + <mallctl>opt.prof_active</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Profiling activated/deactivated. This is a secondary + control mechanism that makes it possible to start the application with + profiling enabled (see the <link + linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but + inactive, then toggle profiling at any time during program execution + with the <link + linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl. + This option is enabled by default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_prof_sample"> + <term> + <mallctl>opt.lg_prof_sample</mallctl> + (<type>ssize_t</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Average interval (log base 2) between allocation + samples, as measured in bytes of allocation activity. Increasing the + sampling interval decreases profile fidelity, but also decreases the + computational overhead. The default sample interval is 1 (2^0) (i.e. + all allocations are sampled).</para></listitem> + </varlistentry> + + <varlistentry id="opt.prof_accum"> + <term> + <mallctl>opt.prof_accum</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Reporting of cumulative object/byte counts in profile + dumps enabled/disabled. If this option is enabled, every unique + backtrace must be stored for the duration of execution. Depending on + the application, this can impose a large memory overhead, and the + cumulative counts are not always of interest. See the + <link + linkend="opt.lg_prof_tcmax"><mallctl>opt.lg_prof_tcmax</mallctl></link> + option for control of per thread backtrace caching, which has important + interactions. This option is enabled by default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_prof_tcmax"> + <term> + <mallctl>opt.lg_prof_tcmax</mallctl> + (<type>ssize_t</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Maximum per thread backtrace cache (log base 2) used + for heap profiling. A backtrace can only be discarded if the + <link linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> + option is disabled, and no thread caches currently refer to the + backtrace. Therefore, a backtrace cache limit should be imposed if the + intention is to limit how much memory is used by backtraces. By + default, no limit is imposed (encoded as -1). + </para></listitem> + </varlistentry> + + <varlistentry id="opt.lg_prof_interval"> + <term> + <mallctl>opt.lg_prof_interval</mallctl> + (<type>ssize_t</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Average interval (log base 2) between memory profile + dumps, as measured in bytes of allocation activity. The actual + interval between dumps may be sporadic because decentralized allocation + counters are used to avoid synchronization bottlenecks. Profiles are + dumped to files named according to the pattern + <filename><prefix>.<pid>.<seq>.i<iseq>.heap</filename>, + where <literal><prefix></literal> is controlled by the + <link + linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> + option. By default, interval-triggered profile dumping is disabled + (encoded as -1). + </para></listitem> + </varlistentry> + + <varlistentry id="opt.prof_gdump"> + <term> + <mallctl>opt.prof_gdump</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Trigger a memory profile dump every time the total + virtual memory exceeds the previous maximum. Profiles are dumped to + files named according to the pattern + <filename><prefix>.<pid>.<seq>.u<useq>.heap</filename>, + where <literal><prefix></literal> is controlled by the <link + linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> + option. This option is disabled by default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.prof_leak"> + <term> + <mallctl>opt.prof_leak</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Leak reporting enabled/disabled. If enabled, use an + <citerefentry><refentrytitle>atexit</refentrytitle> + <manvolnum>3</manvolnum></citerefentry> function to report memory leaks + detected by allocation sampling. See the + <link + linkend="opt.lg_prof_bt_max"><mallctl>opt.lg_prof_bt_max</mallctl></link> + option for backtrace depth control. See the + <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for + information on analyzing heap profile output. This option is disabled + by default.</para></listitem> + </varlistentry> + + <varlistentry id="opt.overcommit"> + <term> + <mallctl>opt.overcommit</mallctl> + (<type>bool</type>) + <literal>r-</literal> + [<option>--enable-swap</option>] + </term> + <listitem><para>Over-commit enabled/disabled. If enabled, over-commit + memory as a side effect of using anonymous + <citerefentry><refentrytitle>mmap</refentrytitle> + <manvolnum>2</manvolnum></citerefentry> or + <citerefentry><refentrytitle>sbrk</refentrytitle> + <manvolnum>2</manvolnum></citerefentry> for virtual memory allocation. + In order for overcommit to be disabled, the <link + linkend="swap.fds"><mallctl>swap.fds</mallctl></link> mallctl must have + been successfully written to. This option is enabled by + default.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>tcache.flush</mallctl> + (<type>void</type>) + <literal>--</literal> + [<option>--enable-tcache</option>] + </term> + <listitem><para>Flush calling thread's tcache. This interface releases + all cached objects and internal data structures associated with the + calling thread's thread-specific cache. Ordinarily, this interface + need not be called, since automatic periodic incremental garbage + collection occurs, and the thread cache is automatically discarded when + a thread exits. However, garbage collection is triggered by allocation + activity, so it is possible for a thread that stops + allocating/deallocating to retain its cache indefinitely, in which case + the developer may find manual flushing useful.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>thread.arena</mallctl> + (<type>unsigned</type>) + <literal>rw</literal> + </term> + <listitem><para>Get or set the arena associated with the calling + thread. The arena index must be less than the maximum number of arenas + (see the <link + linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> + mallctl). If the specified arena was not initialized beforehand (see + the <link + linkend="arenas.initialized"><mallctl>arenas.initialized</mallctl></link> + mallctl), it will be automatically initialized as a side effect of + calling this interface.</para></listitem> + </varlistentry> + + <varlistentry id="thread.allocated"> + <term> + <mallctl>thread.allocated</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Get the total number of bytes ever allocated by the + calling thread. This counter has the potential to wrap around; it is + up to the application to appropriately interpret the counter in such + cases.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>thread.allocatedp</mallctl> + (<type>uint64_t *</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Get a pointer to the the value that is returned by the + <link + linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> + mallctl. This is useful for avoiding the overhead of repeated + <function>mallctl*<parameter/></function> calls.</para></listitem> + </varlistentry> + + <varlistentry id="thread.deallocated"> + <term> + <mallctl>thread.deallocated</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Get the total number of bytes ever deallocated by the + calling thread. This counter has the potential to wrap around; it is + up to the application to appropriately interpret the counter in such + cases.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>thread.deallocatedp</mallctl> + (<type>uint64_t *</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Get a pointer to the the value that is returned by the + <link + linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link> + mallctl. This is useful for avoiding the overhead of repeated + <function>mallctl*<parameter/></function> calls.</para></listitem> + </varlistentry> + + <varlistentry id="arenas.narenas"> + <term> + <mallctl>arenas.narenas</mallctl> + (<type>unsigned</type>) + <literal>r-</literal> + </term> + <listitem><para>Maximum number of arenas.</para></listitem> + </varlistentry> + + <varlistentry id="arenas.initialized"> + <term> + <mallctl>arenas.initialized</mallctl> + (<type>bool *</type>) + <literal>r-</literal> + </term> + <listitem><para>An array of <link + linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> + booleans. Each boolean indicates whether the corresponding arena is + initialized.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.quantum</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Quantum size.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.cacheline</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Assumed cacheline size.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.subpage</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Subpage size class interval.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.pagesize</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Page size.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.chunksize</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Chunk size.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.tspace_min</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Minimum tiny size class. Tiny size classes are powers + of two.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.tspace_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Maximum tiny size class. Tiny size classes are powers + of two.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.qspace_min</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Minimum quantum-spaced size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.qspace_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Maximum quantum-spaced size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.cspace_min</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Minimum cacheline-spaced size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.cspace_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Maximum cacheline-spaced size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.sspace_min</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Minimum subpage-spaced size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.sspace_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Maximum subpage-spaced size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.tcache_max</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-tcache</option>] + </term> + <listitem><para>Maximum thread-cached size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.ntbins</mallctl> + (<type>unsigned</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of tiny bin size classes.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.nqbins</mallctl> + (<type>unsigned</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of quantum-spaced bin size + classes.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.ncbins</mallctl> + (<type>unsigned</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of cacheline-spaced bin size + classes.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.nsbins</mallctl> + (<type>unsigned</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of subpage-spaced bin size + classes.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.nbins</mallctl> + (<type>unsigned</type>) + <literal>r-</literal> + </term> + <listitem><para>Total number of bin size classes.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.nhbins</mallctl> + (<type>unsigned</type>) + <literal>r-</literal> + [<option>--enable-tcache</option>] + </term> + <listitem><para>Total number of thread cache bin size + classes.</para></listitem> + </varlistentry> + + <varlistentry id="arenas.bin.i.size"> + <term> + <mallctl>arenas.bin.<i>.size</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Maximum size supported by size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.bin.<i>.nregs</mallctl> + (<type>uint32_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of regions per page run.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.bin.<i>.run_size</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of bytes per page run.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.nlruns</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Total number of large size classes.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.lrun.<i>.size</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Maximum size supported by this large size + class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>arenas.purge</mallctl> + (<type>unsigned</type>) + <literal>-w</literal> + </term> + <listitem><para>Purge unused dirty pages for the specified arena, or + for all arenas if none is specified.</para></listitem> + </varlistentry> + + <varlistentry id="prof.active"> + <term> + <mallctl>prof.active</mallctl> + (<type>bool</type>) + <literal>rw</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Control whether sampling is currently active. See the + <link + linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> + option for additional information. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>prof.dump</mallctl> + (<type>const char *</type>) + <literal>-w</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Dump a memory profile to the specified file, or if NULL + is specified, to a file according to the pattern + <filename><prefix>.<pid>.<seq>.m<mseq>.heap</filename>, + where <literal><prefix></literal> is controlled by the + <link + linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>prof.interval</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-prof</option>] + </term> + <listitem><para>Average number of bytes allocated between + inverval-based profile dumps. See the + <link + linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> + option for additional information.</para></listitem> + </varlistentry> + + <varlistentry id="stats.cactive"> + <term> + <mallctl>stats.cactive</mallctl> + (<type>size_t *</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Pointer to a counter that contains an approximate count + of the current number of bytes in active pages. The estimate may be + high, but never low, because each arena rounds up to the nearest + multiple of the chunk size when computing its contribution to the + counter. Note that the <link + linkend="epoch"><mallctl>epoch</mallctl></link> mallctl has no bearing + on this counter. Furthermore, counter consistency is maintained via + atomic operations, so it is necessary to use an atomic operation in + order to guarantee a consistent read when dereferencing the pointer. + </para></listitem> + </varlistentry> + + <varlistentry id="stats.allocated"> + <term> + <mallctl>stats.allocated</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Total number of bytes allocated by the + application.</para></listitem> + </varlistentry> + + <varlistentry id="stats.active"> + <term> + <mallctl>stats.active</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Total number of bytes in active pages allocated by the + application. This is a multiple of the page size, and greater than or + equal to <link + linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.mapped</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Total number of bytes in chunks mapped on behalf of the + application. This is a multiple of the chunk size, and is at least as + large as <link + linkend="stats.active"><mallctl>stats.active</mallctl></link>. This + does not include inactive chunks backed by swap files. his does not + include inactive chunks embedded in the DSS.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.chunks.current</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Total number of chunks actively mapped on behalf of the + application. This does not include inactive chunks backed by swap + files. This does not include inactive chunks embedded in the DSS. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.chunks.total</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of chunks allocated.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.chunks.high</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Maximum number of active chunks at any time thus far. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.huge.allocated</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Number of bytes currently allocated by huge objects. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.huge.nmalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of huge allocation requests. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.huge.ndalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of huge deallocation requests. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.nthreads</mallctl> + (<type>unsigned</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of threads currently assigned to + arena.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.pactive</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of pages in active runs.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.pdirty</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + </term> + <listitem><para>Number of pages within unused runs that are potentially + dirty, and for which <function>madvise<parameter>...</parameter> + <parameter><constant>MADV_DONTNEED</constant></parameter></function> or + similar has not been called.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.mapped</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Number of mapped bytes.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.npurge</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Number of dirty page purge sweeps performed. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.nmadvise</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Number of <function>madvise<parameter>...</parameter> + <parameter><constant>MADV_DONTNEED</constant></parameter></function> or + similar calls made to purge dirty pages.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.npurged</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Number of pages purged.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.small.allocated</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Number of bytes currently allocated by small objects. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.small.nmalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of allocation requests served by + small bins.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.small.ndalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of small objects returned to bins. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.small.nrequests</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of small allocation requests. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.large.allocated</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Number of bytes currently allocated by large objects. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.large.nmalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of large allocation requests served + directly by the arena.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.large.ndalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of large deallocation requests served + directly by the arena.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.large.nrequests</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of large allocation requests. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.allocated</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Current number of bytes allocated by + bin.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.nmalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of allocations served by bin. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.ndalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of allocations returned to bin. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.nrequests</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of allocation + requests.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.nfills</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option> <option>--enable-tcache</option>] + </term> + <listitem><para>Cumulative number of tcache fills.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.nflushes</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option> <option>--enable-tcache</option>] + </term> + <listitem><para>Cumulative number of tcache flushes.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.nruns</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of runs created.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.nreruns</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of times the current run from which + to allocate changed.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.highruns</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Maximum number of runs at any time thus far. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.bins.<j>.curruns</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Current number of runs.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.lruns.<j>.nmalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of allocation requests for this size + class served directly by the arena.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.lruns.<j>.ndalloc</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of deallocation requests for this + size class served directly by the arena.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.lruns.<j>.nrequests</mallctl> + (<type>uint64_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Cumulative number of allocation requests for this size + class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.lruns.<j>.highruns</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Maximum number of runs at any time thus far for this + size class.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>stats.arenas.<i>.lruns.<j>.curruns</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats</option>] + </term> + <listitem><para>Current number of runs for this size class. + </para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>swap.avail</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-stats --enable-swap</option>] + </term> + <listitem><para>Number of swap file bytes that are currently not + associated with any chunk (i.e. mapped, but otherwise completely + unmanaged).</para></listitem> + </varlistentry> + + <varlistentry id="swap.prezeroed"> + <term> + <mallctl>swap.prezeroed</mallctl> + (<type>bool</type>) + <literal>rw</literal> + [<option>--enable-swap</option>] + </term> + <listitem><para>If true, the allocator assumes that the swap file(s) + contain nothing but nil bytes. If this assumption is violated, + allocator behavior is undefined. This value becomes read-only after + <link linkend="swap.fds"><mallctl>swap.fds</mallctl></link> is + successfully written to.</para></listitem> + </varlistentry> + + <varlistentry> + <term> + <mallctl>swap.nfds</mallctl> + (<type>size_t</type>) + <literal>r-</literal> + [<option>--enable-swap</option>] + </term> + <listitem><para>Number of file descriptors in use for swap. + </para></listitem> + </varlistentry> + + <varlistentry id="swap.fds"> + <term> + <mallctl>swap.fds</mallctl> + (<type>int *</type>) + <literal>r-</literal> + [<option>--enable-swap</option>] + </term> + <listitem><para>When written to, the files associated with the + specified file descriptors are contiguously mapped via + <citerefentry><refentrytitle>mmap</refentrytitle> + <manvolnum>2</manvolnum></citerefentry>. The resulting virtual memory + region is preferred over anonymous + <citerefentry><refentrytitle>mmap</refentrytitle> + <manvolnum>2</manvolnum></citerefentry> and + <citerefentry><refentrytitle>sbrk</refentrytitle> + <manvolnum>2</manvolnum></citerefentry> 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 + <link linkend="swap.prezeroed"><mallctl>swap.prezeroed</mallctl></link> + mallctl for specifying that the files are pre-zeroed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1 id="debugging_malloc_problems"> + <title>DEBUGGING MALLOC PROBLEMS</title> + <para>When debugging, it is a good idea to configure/build jemalloc with + the <option>--enable-debug</option> and <option>--enable-fill</option> + 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.</para> + + <para>Programs often accidentally depend on “uninitialized” + memory actually being filled with zero bytes. Junk filling + (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> + option) tends to expose such bugs in the form of obviously incorrect + results and/or coredumps. Conversely, zero + filling (see the <link + linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates + the symptoms of such bugs. Between these two options, it is usually + possible to quickly detect, diagnose, and eliminate such bugs.</para> + + <para>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.</para> + </refsect1> + <refsect1 id="diagnostic_messages"> + <title>DIAGNOSTIC MESSAGES</title> + <para>If any of the memory allocation/deallocation functions detect an + error or warning condition, a message will be printed to file descriptor + <constant>STDERR_FILENO</constant>. Errors will result in the process + dumping core. If the <link + linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most + warnings are treated as errors.</para> + + <para>The <varname>malloc_message</varname> variable allows the programmer + to override the function which emits the text strings forming the errors + and warnings if for some reason the <constant>STDERR_FILENO</constant> file + descriptor is not suitable for this. + <function>malloc_message<parameter/></function> takes the + <parameter>cbopaque</parameter> pointer argument that is + <constant>NULL</constant> unless overridden by the arguments in a call to + <function>malloc_stats_print<parameter/></function>, 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.</para> + + <para>All messages are prefixed by + “<computeroutput><jemalloc>: </computeroutput>”.</para> + </refsect1> + <refsect1 id="return_values"> + <title>RETURN VALUES</title> + <refsect2> + <title>Standard API</title> + <para>The <function>malloc<parameter/></function> and + <function>calloc<parameter/></function> functions return a pointer to the + allocated memory if successful; otherwise a <constant>NULL</constant> + pointer is returned and <varname>errno</varname> is set to + <errorname>ENOMEM</errorname>.</para> + + <para>The <function>posix_memalign<parameter/></function> function + returns the value 0 if successful; otherwise it returns an error value. + The <function>posix_memalign<parameter/></function> function will fail + if: + <variablelist> + <varlistentry> + <term><errorname>EINVAL</errorname></term> + + <listitem><para>The <parameter>alignment</parameter> parameter is + not a power of 2 at least as large as + <code language="C">sizeof(<type>void *</type>)</code>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><errorname>ENOMEM</errorname></term> + + <listitem><para>Memory allocation error.</para></listitem> + </varlistentry> + </variablelist> + </para> + + <para>The <function>realloc<parameter/></function> function returns a + pointer, possibly identical to <parameter>ptr</parameter>, to the + allocated memory if successful; otherwise a <constant>NULL</constant> + pointer is returned, and <varname>errno</varname> is set to + <errorname>ENOMEM</errorname> if the error was the result of an + allocation failure. The <function>realloc<parameter/></function> + function always leaves the original buffer intact when an error occurs. + </para> + + <para>The <function>free<parameter/></function> function returns no + value.</para> + </refsect2> + <refsect2> + <title>Non-standard API</title> + <para>The <function>malloc_usable_size<parameter/></function> function + returns the usable size of the allocation pointed to by + <parameter>ptr</parameter>. </para> + + <para>The <function>mallctl<parameter/></function>, + <function>mallctlnametomib<parameter/></function>, and + <function>mallctlbymib<parameter/></function> functions return 0 on + success; otherwise they return an error value. The functions will fail + if: + <variablelist> + <varlistentry> + <term><errorname>EINVAL</errorname></term> + + <listitem><para><parameter>newp</parameter> is not + <constant>NULL</constant>, and <parameter>newlen</parameter> is too + large or too small. Alternatively, <parameter>*oldlenp</parameter> + is too large or too small; in this case as much data as possible + are read despite the error.</para></listitem> + </varlistentry> + <varlistentry> + <term><errorname>ENOMEM</errorname></term> + + <listitem><para><parameter>*oldlenp</parameter> is too short to + hold the requested value.</para></listitem> + </varlistentry> + <varlistentry> + <term><errorname>ENOENT</errorname></term> + + <listitem><para><parameter>name</parameter> or + <parameter>mib</parameter> specifies an unknown/invalid + value.</para></listitem> + </varlistentry> + <varlistentry> + <term><errorname>EPERM</errorname></term> + + <listitem><para>Attempt to read or write void value, or attempt to + write read-only value.</para></listitem> + </varlistentry> + <varlistentry> + <term><errorname>EAGAIN</errorname></term> + + <listitem><para>A memory allocation failure + occurred.</para></listitem> + </varlistentry> + <varlistentry> + <term><errorname>EFAULT</errorname></term> + + <listitem><para>An interface with side effects failed in some way + not directly related to <function>mallctl*<parameter/></function> + read/write processing.</para></listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + <refsect2> + <title>Experimental API</title> + <para>The <function>allocm<parameter/></function>, + <function>rallocm<parameter/></function>, + <function>sallocm<parameter/></function>, and + <function>dallocm<parameter/></function> functions return + <constant>ALLOCM_SUCCESS</constant> on success; otherwise they return an + error value. The <function>allocm<parameter/></function> and + <function>rallocm<parameter/></function> functions will fail if: + <variablelist> + <varlistentry> + <term><errorname>ALLOCM_ERR_OOM</errorname></term> + + <listitem><para>Out of memory. Insufficient contiguous memory was + available to service the allocation request. The + <function>allocm<parameter/></function> function additionally sets + <parameter>*ptr</parameter> to <constant>NULL</constant>, whereas + the <function>rallocm<parameter/></function> function leaves + <constant>*ptr</constant> unmodified.</para></listitem> + </varlistentry> + </variablelist> + The <function>rallocm<parameter/></function> function will also + fail if: + <variablelist> + <varlistentry> + <term><errorname>ALLOCM_ERR_NOT_MOVED</errorname></term> + + <listitem><para><constant>ALLOCM_NO_MOVE</constant> was specified, + but the reallocation request could not be serviced without moving + the object.</para></listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + </refsect1> + <refsect1 id="environment"> + <title>ENVIRONMENT</title> + <para>The following environment variable affects the execution of the + allocation functions: + <variablelist> + <varlistentry> + <term><envar>MALLOC_CONF</envar></term> + + <listitem><para>If the environment variable + <envar>MALLOC_CONF</envar> is set, the characters it contains + will be interpreted as options.</para></listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 id="examples"> + <title>EXAMPLES</title> + <para>To dump core whenever a problem occurs: + <screen>ln -s 'abort:true' /etc/malloc.conf</screen> + </para> + <para>To specify in the source a chunk size that is 16 MiB: + <programlisting language="C"><![CDATA[ +malloc_conf = "lg_chunk:24";]]></programlisting></para> + </refsect1> + <refsect1 id="see_also"> + <title>SEE ALSO</title> + <para><citerefentry><refentrytitle>madvise</refentrytitle> + <manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mmap</refentrytitle> + <manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sbrk</refentrytitle> + <manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>alloca</refentrytitle> + <manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>atexit</refentrytitle> + <manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>getpagesize</refentrytitle> + <manvolnum>3</manvolnum></citerefentry></para> + </refsect1> + <refsect1 id="standards"> + <title>STANDARDS</title> + <para>The <function>malloc<parameter/></function>, + <function>calloc<parameter/></function>, + <function>realloc<parameter/></function>, and + <function>free<parameter/></function> functions conform to ISO/IEC + 9899:1990 (“ISO C90”).</para> + + <para>The <function>posix_memalign<parameter/></function> function conforms + to IEEE Std 1003.1-2001 (“POSIX.1”).</para> + </refsect1> +</refentry> diff --git a/doc/manpages.xsl.in b/doc/manpages.xsl.in new file mode 100644 index 0000000..88b2626 --- /dev/null +++ b/doc/manpages.xsl.in @@ -0,0 +1,4 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:import href="@XSLROOT@/manpages/docbook.xsl"/> + <xsl:import href="@abs_srcroot@doc/stylesheet.xsl"/> +</xsl:stylesheet> diff --git a/doc/stylesheet.xsl b/doc/stylesheet.xsl new file mode 100644 index 0000000..4e334a8 --- /dev/null +++ b/doc/stylesheet.xsl @@ -0,0 +1,7 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:param name="funcsynopsis.style">ansi</xsl:param> + <xsl:param name="function.parens" select="1"/> + <xsl:template match="mallctl"> + "<xsl:call-template name="inline.monoseq"/>" + </xsl:template> +</xsl:stylesheet> |