1<?xml version='1.0' encoding='UTF-8'?> 2<?xml-stylesheet type="text/xsl" 3 href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?> 4<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 5 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ 6]> 7 8<refentry> 9 <refentryinfo> 10 <title>User Manual</title> 11 <productname>jemalloc</productname> 12 <releaseinfo role="version">@jemalloc_version@</releaseinfo> 13 <authorgroup> 14 <author> 15 <firstname>Jason</firstname> 16 <surname>Evans</surname> 17 <personblurb>Author</personblurb> 18 </author> 19 </authorgroup> 20 </refentryinfo> 21 <refmeta> 22 <refentrytitle>JEMALLOC</refentrytitle> 23 <manvolnum>3</manvolnum> 24 </refmeta> 25 <refnamediv> 26 <refdescriptor>jemalloc</refdescriptor> 27 <refname>jemalloc</refname> 28 <!-- Each refname causes a man page file to be created. Only if this were 29 the system malloc(3) implementation would these files be appropriate. 30 <refname>malloc</refname> 31 <refname>calloc</refname> 32 <refname>posix_memalign</refname> 33 <refname>realloc</refname> 34 <refname>free</refname> 35 <refname>malloc_usable_size</refname> 36 <refname>malloc_stats_print</refname> 37 <refname>mallctl</refname> 38 <refname>mallctlnametomib</refname> 39 <refname>mallctlbymib</refname> 40 <refname>allocm</refname> 41 <refname>rallocm</refname> 42 <refname>sallocm</refname> 43 <refname>dallocm</refname> 44 --> 45 <refpurpose>general purpose memory allocation functions</refpurpose> 46 </refnamediv> 47 <refsect1 id="library"> 48 <title>LIBRARY</title> 49 <para>This manual describes jemalloc @jemalloc_version@. More information 50 can be found at the <ulink 51 url="http://www.canonware.com/jemalloc/">jemalloc website</ulink>.</para> 52 </refsect1> 53 <refsynopsisdiv> 54 <title>SYNOPSIS</title> 55 <funcsynopsis> 56 <funcsynopsisinfo>#include <<filename class="headerfile">stdlib.h</filename>> 57#include <<filename class="headerfile">jemalloc/jemalloc.h</filename>></funcsynopsisinfo> 58 <refsect2> 59 <title>Standard API</title> 60 <funcprototype> 61 <funcdef>void *<function>malloc</function></funcdef> 62 <paramdef>size_t <parameter>size</parameter></paramdef> 63 </funcprototype> 64 <funcprototype> 65 <funcdef>void *<function>calloc</function></funcdef> 66 <paramdef>size_t <parameter>number</parameter></paramdef> 67 <paramdef>size_t <parameter>size</parameter></paramdef> 68 </funcprototype> 69 <funcprototype> 70 <funcdef>int <function>posix_memalign</function></funcdef> 71 <paramdef>void **<parameter>ptr</parameter></paramdef> 72 <paramdef>size_t <parameter>alignment</parameter></paramdef> 73 <paramdef>size_t <parameter>size</parameter></paramdef> 74 </funcprototype> 75 <funcprototype> 76 <funcdef>void *<function>realloc</function></funcdef> 77 <paramdef>void *<parameter>ptr</parameter></paramdef> 78 <paramdef>size_t <parameter>size</parameter></paramdef> 79 </funcprototype> 80 <funcprototype> 81 <funcdef>void <function>free</function></funcdef> 82 <paramdef>void *<parameter>ptr</parameter></paramdef> 83 </funcprototype> 84 </refsect2> 85 <refsect2> 86 <title>Non-standard API</title> 87 <funcprototype> 88 <funcdef>size_t <function>malloc_usable_size</function></funcdef> 89 <paramdef>const void *<parameter>ptr</parameter></paramdef> 90 </funcprototype> 91 <funcprototype> 92 <funcdef>void <function>malloc_stats_print</function></funcdef> 93 <paramdef>void <parameter>(*write_cb)</parameter> 94 <funcparams>void *, const char *</funcparams> 95 </paramdef> 96 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 97 <paramdef>const char *<parameter>opts</parameter></paramdef> 98 </funcprototype> 99 <funcprototype> 100 <funcdef>int <function>mallctl</function></funcdef> 101 <paramdef>const char *<parameter>name</parameter></paramdef> 102 <paramdef>void *<parameter>oldp</parameter></paramdef> 103 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 104 <paramdef>void *<parameter>newp</parameter></paramdef> 105 <paramdef>size_t <parameter>newlen</parameter></paramdef> 106 </funcprototype> 107 <funcprototype> 108 <funcdef>int <function>mallctlnametomib</function></funcdef> 109 <paramdef>const char *<parameter>name</parameter></paramdef> 110 <paramdef>size_t *<parameter>mibp</parameter></paramdef> 111 <paramdef>size_t *<parameter>miblenp</parameter></paramdef> 112 </funcprototype> 113 <funcprototype> 114 <funcdef>int <function>mallctlbymib</function></funcdef> 115 <paramdef>const size_t *<parameter>mib</parameter></paramdef> 116 <paramdef>size_t <parameter>miblen</parameter></paramdef> 117 <paramdef>void *<parameter>oldp</parameter></paramdef> 118 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 119 <paramdef>void *<parameter>newp</parameter></paramdef> 120 <paramdef>size_t <parameter>newlen</parameter></paramdef> 121 </funcprototype> 122 <funcprototype> 123 <funcdef>void <function>(*malloc_message)</function></funcdef> 124 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 125 <paramdef>const char *<parameter>s</parameter></paramdef> 126 </funcprototype> 127 <para><type>const char *</type><varname>malloc_conf</varname>;</para> 128 </refsect2> 129 <refsect2> 130 <title>Experimental API</title> 131 <funcprototype> 132 <funcdef>int <function>allocm</function></funcdef> 133 <paramdef>void **<parameter>ptr</parameter></paramdef> 134 <paramdef>size_t *<parameter>rsize</parameter></paramdef> 135 <paramdef>size_t <parameter>size</parameter></paramdef> 136 <paramdef>int <parameter>flags</parameter></paramdef> 137 </funcprototype> 138 <funcprototype> 139 <funcdef>int <function>rallocm</function></funcdef> 140 <paramdef>void **<parameter>ptr</parameter></paramdef> 141 <paramdef>size_t *<parameter>rsize</parameter></paramdef> 142 <paramdef>size_t <parameter>size</parameter></paramdef> 143 <paramdef>size_t <parameter>extra</parameter></paramdef> 144 <paramdef>int <parameter>flags</parameter></paramdef> 145 </funcprototype> 146 <funcprototype> 147 <funcdef>int <function>sallocm</function></funcdef> 148 <paramdef>const void *<parameter>ptr</parameter></paramdef> 149 <paramdef>size_t *<parameter>rsize</parameter></paramdef> 150 <paramdef>int <parameter>flags</parameter></paramdef> 151 </funcprototype> 152 <funcprototype> 153 <funcdef>int <function>dallocm</function></funcdef> 154 <paramdef>void *<parameter>ptr</parameter></paramdef> 155 <paramdef>int <parameter>flags</parameter></paramdef> 156 </funcprototype> 157 </refsect2> 158 </funcsynopsis> 159 </refsynopsisdiv> 160 <refsect1 id="description"> 161 <title>DESCRIPTION</title> 162 <refsect2> 163 <title>Standard API</title> 164 165 <para>The <function>malloc<parameter/></function> function allocates 166 <parameter>size</parameter> bytes of uninitialized memory. The allocated 167 space is suitably aligned (after possible pointer coercion) for storage 168 of any type of object.</para> 169 170 <para>The <function>calloc<parameter/></function> function allocates 171 space for <parameter>number</parameter> objects, each 172 <parameter>size</parameter> bytes in length. The result is identical to 173 calling <function>malloc<parameter/></function> with an argument of 174 <parameter>number</parameter> * <parameter>size</parameter>, with the 175 exception that the allocated memory is explicitly initialized to zero 176 bytes.</para> 177 178 <para>The <function>posix_memalign<parameter/></function> function 179 allocates <parameter>size</parameter> bytes of memory such that the 180 allocation's base address is an even multiple of 181 <parameter>alignment</parameter>, and returns the allocation in the value 182 pointed to by <parameter>ptr</parameter>. The requested 183 <parameter>alignment</parameter> must be a power of 2 at least as large 184 as <code language="C">sizeof(<type>void *</type>)</code>.</para> 185 186 <para>The <function>realloc<parameter/></function> function changes the 187 size of the previously allocated memory referenced by 188 <parameter>ptr</parameter> to <parameter>size</parameter> bytes. The 189 contents of the memory are unchanged up to the lesser of the new and old 190 sizes. If the new size is larger, the contents of the newly allocated 191 portion of the memory are undefined. Upon success, the memory referenced 192 by <parameter>ptr</parameter> is freed and a pointer to the newly 193 allocated memory is returned. Note that 194 <function>realloc<parameter/></function> may move the memory allocation, 195 resulting in a different return value than <parameter>ptr</parameter>. 196 If <parameter>ptr</parameter> is <constant>NULL</constant>, the 197 <function>realloc<parameter/></function> function behaves identically to 198 <function>malloc<parameter/></function> for the specified size.</para> 199 200 <para>The <function>free<parameter/></function> function causes the 201 allocated memory referenced by <parameter>ptr</parameter> to be made 202 available for future allocations. If <parameter>ptr</parameter> is 203 <constant>NULL</constant>, no action occurs.</para> 204 </refsect2> 205 <refsect2> 206 <title>Non-standard API</title> 207 208 <para>The <function>malloc_usable_size<parameter/></function> function 209 returns the usable size of the allocation pointed to by 210 <parameter>ptr</parameter>. The return value may be larger than the size 211 that was requested during allocation. The 212 <function>malloc_usable_size<parameter/></function> function is not a 213 mechanism for in-place <function>realloc<parameter/></function>; rather 214 it is provided solely as a tool for introspection purposes. Any 215 discrepancy between the requested allocation size and the size reported 216 by <function>malloc_usable_size<parameter/></function> should not be 217 depended on, since such behavior is entirely implementation-dependent. 218 </para> 219 220 <para>The <function>malloc_stats_print<parameter/></function> function 221 writes human-readable summary statistics via the 222 <parameter>write_cb</parameter> callback function pointer and 223 <parameter>cbopaque</parameter> data passed to 224 <parameter>write_cb</parameter>, or 225 <function>malloc_message<parameter/></function> if 226 <parameter>write_cb</parameter> is <constant>NULL</constant>. This 227 function can be called repeatedly. General information that never 228 changes during execution can be omitted by specifying "g" as a character 229 within the <parameter>opts</parameter> string. Note that 230 <function>malloc_message<parameter/></function> uses the 231 <function>mallctl*<parameter/></function> functions internally, so 232 inconsistent statistics can be reported if multiple threads use these 233 functions simultaneously. If <option>--enable-stats</option> is 234 specified during configuration, “m” and “a” can 235 be specified to omit merged arena and per arena statistics, respectively; 236 “b” and “l” can be specified to omit per size 237 class statistics for bins and large objects, respectively. Unrecognized 238 characters are silently ignored. Note that thread caching may prevent 239 some statistics from being completely up to date, since extra locking 240 would be required to merge counters that track thread cache operations. 241 </para> 242 243 <para>The <function>mallctl<parameter/></function> function provides a 244 general interface for introspecting the memory allocator, as well as 245 setting modifiable parameters and triggering actions. The 246 period-separated <parameter>name</parameter> argument specifies a 247 location in a tree-structured namespace; see the <xref 248 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for 249 documentation on the tree contents. To read a value, pass a pointer via 250 <parameter>oldp</parameter> to adequate space to contain the value, and a 251 pointer to its length via <parameter>oldlenp</parameter>; otherwise pass 252 <constant>NULL</constant> and <constant>NULL</constant>. Similarly, to 253 write a value, pass a pointer to the value via 254 <parameter>newp</parameter>, and its length via 255 <parameter>newlen</parameter>; otherwise pass <constant>NULL</constant> 256 and <constant>0</constant>.</para> 257 258 <para>The <function>mallctlnametomib<parameter/></function> function 259 provides a way to avoid repeated name lookups for applications that 260 repeatedly query the same portion of the namespace, by translating a name 261 to a “Management Information Base” (MIB) that can be passed 262 repeatedly to <function>mallctlbymib<parameter/></function>. Upon 263 successful return from <function>mallctlnametomib<parameter/></function>, 264 <parameter>mibp</parameter> contains an array of 265 <parameter>*miblenp</parameter> integers, where 266 <parameter>*miblenp</parameter> is the lesser of the number of components 267 in <parameter>name</parameter> and the input value of 268 <parameter>*miblenp</parameter>. Thus it is possible to pass a 269 <parameter>*miblenp</parameter> that is smaller than the number of 270 period-separated name components, which results in a partial MIB that can 271 be used as the basis for constructing a complete MIB. For name 272 components that are integers (e.g. the 2 in 273 <link 274 linkend="arenas.bin.i.size"><mallctl>arenas.bin.2.size</mallctl></link>), 275 the corresponding MIB component will always be that integer. Therefore, 276 it is legitimate to construct code like the following: <programlisting 277 language="C"><![CDATA[ 278unsigned nbins, i; 279 280int mib[4]; 281size_t len, miblen; 282 283len = sizeof(nbins); 284mallctl("arenas.nbins", &nbins, &len, NULL, 0); 285 286miblen = 4; 287mallnametomib("arenas.bin.0.size", mib, &miblen); 288for (i = 0; i < nbins; i++) { 289 size_t bin_size; 290 291 mib[2] = i; 292 len = sizeof(bin_size); 293 mallctlbymib(mib, miblen, &bin_size, &len, NULL, 0); 294 /* Do something with bin_size... */ 295}]]></programlisting></para> 296 </refsect2> 297 <refsect2> 298 <title>Experimental API</title> 299 <para>The experimental API is subject to change or removal without regard 300 for backward compatibility.</para> 301 302 <para>The <function>allocm<parameter/></function>, 303 <function>rallocm<parameter/></function>, 304 <function>sallocm<parameter/></function>, and 305 <function>dallocm<parameter/></function> functions all have a 306 <parameter>flags</parameter> argument that can be used to specify 307 options. The functions only check the options that are contextually 308 relevant. Use bitwise or (<code language="C">|</code>) operations to 309 specify one or more of the following: 310 <variablelist> 311 <varlistentry> 312 <term><constant>ALLOCM_LG_ALIGN(<parameter>la</parameter>) 313 </constant></term> 314 315 <listitem><para>Align the memory allocation to start at an address 316 that is a multiple of <code language="C">(1 << 317 <parameter>la</parameter>)</code>. This macro does not validate 318 that <parameter>la</parameter> is within the valid 319 range.</para></listitem> 320 </varlistentry> 321 <varlistentry> 322 <term><constant>ALLOCM_ALIGN(<parameter>a</parameter>) 323 </constant></term> 324 325 <listitem><para>Align the memory allocation to start at an address 326 that is a multiple of <parameter>a</parameter>, where 327 <parameter>a</parameter> is a power of two. This macro does not 328 validate that <parameter>a</parameter> is a power of 2. 329 </para></listitem> 330 </varlistentry> 331 <varlistentry> 332 <term><constant>ALLOCM_ZERO</constant></term> 333 334 <listitem><para>Initialize newly allocated memory to contain zero 335 bytes. In the growing reallocation case, the real size prior to 336 reallocation defines the boundary between untouched bytes and those 337 that are initialized to contain zero bytes. If this option is 338 absent, newly allocated memory is uninitialized.</para></listitem> 339 </varlistentry> 340 <varlistentry> 341 <term><constant>ALLOCM_NO_MOVE</constant></term> 342 343 <listitem><para>For reallocation, fail rather than moving the 344 object. This constraint can apply to both growth and 345 shrinkage.</para></listitem> 346 </varlistentry> 347 </variablelist> 348 </para> 349 350 <para>The <function>allocm<parameter/></function> function allocates at 351 least <parameter>size</parameter> bytes of memory, sets 352 <parameter>*ptr</parameter> to the base address of the allocation, and 353 sets <parameter>*rsize</parameter> to the real size of the allocation if 354 <parameter>rsize</parameter> is not <constant>NULL</constant>.</para> 355 356 <para>The <function>rallocm<parameter/></function> function resizes the 357 allocation at <parameter>*ptr</parameter> to be at least 358 <parameter>size</parameter> bytes, sets <parameter>*ptr</parameter> to 359 the base address of the allocation if it moved, and sets 360 <parameter>*rsize</parameter> to the real size of the allocation if 361 <parameter>rsize</parameter> is not <constant>NULL</constant>. If 362 <parameter>extra</parameter> is non-zero, an attempt is made to resize 363 the allocation to be at least <code 364 language="C"><parameter>size</parameter> + 365 <parameter>extra</parameter>)</code> bytes, though inability to allocate 366 the extra byte(s) will not by itself result in failure. Behavior is 367 undefined if <code language="C">(<parameter>size</parameter> + 368 <parameter>extra</parameter> > 369 <constant>SIZE_T_MAX</constant>)</code>.</para> 370 371 <para>The <function>sallocm<parameter/></function> function sets 372 <parameter>*rsize</parameter> to the real size of the allocation.</para> 373 374 <para>The <function>dallocm<parameter/></function> function causes the 375 memory referenced by <parameter>ptr</parameter> to be made available for 376 future allocations.</para> 377 </refsect2> 378 </refsect1> 379 <refsect1 id="tuning"> 380 <title>TUNING</title> 381 <para>Once, when the first call is made to one of the memory allocation 382 routines, the allocator initializes its internals based in part on various 383 options that can be specified at compile- or run-time.</para> 384 385 <para>The string pointed to by the global variable 386 <varname>malloc_conf</varname>, the “name” of the file 387 referenced by the symbolic link named <filename 388 class="symlink">/etc/malloc.conf</filename>, and the value of the 389 environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in 390 that order, from left to right as options.</para> 391 392 <para>An options string is a comma-separated list of option:value pairs. 393 There is one key corresponding to each <link 394 linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the <xref 395 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for options 396 documentation). For example, <literal>abort:true,narenas:1</literal> sets 397 the <link linkend="opt.abort"><mallctl>opt.abort</mallctl></link> and <link 398 linkend="opt.narenas"><mallctl>opt.narenas</mallctl></link> options. Some 399 options have boolean values (true/false), others have integer values (base 400 8, 10, or 16, depending on prefix), and yet others have raw string 401 values.</para> 402 </refsect1> 403 <refsect1 id="implementation_notes"> 404 <title>IMPLEMENTATION NOTES</title> 405 <para>Traditionally, allocators have used 406 <citerefentry><refentrytitle>sbrk</refentrytitle> 407 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is 408 suboptimal for several reasons, including race conditions, increased 409 fragmentation, and artificial limitations on maximum usable memory. If 410 <option>--enable-dss</option> is specified during configuration, this 411 allocator uses both <citerefentry><refentrytitle>sbrk</refentrytitle> 412 <manvolnum>2</manvolnum></citerefentry> and 413 <citerefentry><refentrytitle>mmap</refentrytitle> 414 <manvolnum>2</manvolnum></citerefentry>, in that order of preference; 415 otherwise only <citerefentry><refentrytitle>mmap</refentrytitle> 416 <manvolnum>2</manvolnum></citerefentry> is used.</para> 417 418 <para>This allocator uses multiple arenas in order to reduce lock 419 contention for threaded programs on multi-processor systems. This works 420 well with regard to threading scalability, but incurs some costs. There is 421 a small fixed per-arena overhead, and additionally, arenas manage memory 422 completely independently of each other, which means a small fixed increase 423 in overall memory fragmentation. These overheads are not generally an 424 issue, given the number of arenas normally used. Note that using 425 substantially more arenas than the default is not likely to improve 426 performance, mainly due to reduced cache performance. However, it may make 427 sense to reduce the number of arenas if an application does not make much 428 use of the allocation functions.</para> 429 430 <para>In addition to multiple arenas, unless 431 <option>--disable-tcache</option> is specified during configuration, this 432 allocator supports thread-specific caching for small and large objects, in 433 order to make it possible to completely avoid synchronization for most 434 allocation requests. Such caching allows very fast allocation in the 435 common case, but it increases memory usage and fragmentation, since a 436 bounded number of objects can remain allocated in each thread cache.</para> 437 438 <para>Memory is conceptually broken into equal-sized chunks, where the 439 chunk size is a power of two that is greater than the page size. Chunks 440 are always aligned to multiples of the chunk size. This alignment makes it 441 possible to find metadata for user objects very quickly.</para> 442 443 <para>User objects are broken into three categories according to size: 444 small, large, and huge. Small objects are smaller than one page. Large 445 objects are smaller than the chunk size. Huge objects are a multiple of 446 the chunk size. Small and large objects are managed by arenas; huge 447 objects are managed separately in a single data structure that is shared by 448 all threads. Huge objects are used by applications infrequently enough 449 that this single data structure is not a scalability issue.</para> 450 451 <para>Each chunk that is managed by an arena tracks its contents as runs of 452 contiguous pages (unused, backing a set of small objects, or backing one 453 large object). The combination of chunk alignment and chunk page maps 454 makes it possible to determine all metadata regarding small and large 455 allocations in constant time.</para> 456 457 <para>Small objects are managed in groups by page runs. Each run maintains 458 a frontier and free list to track which regions are in use. Unless 459 <option>--disable-tiny</option> is specified during configuration, 460 allocation requests that are no more than half the quantum (8 or 16, 461 depending on architecture) are rounded up to the nearest power of two that 462 is at least <code language="C">sizeof(<type>void *</type>)</code>. 463 Allocation requests that are more than half the quantum, but no more than 464 the minimum cacheline-multiple size class (see the <link 465 linkend="opt.lg_qspace_max"><mallctl>opt.lg_qspace_max</mallctl></link> 466 option) are rounded up to the nearest multiple of the quantum. Allocation 467 requests that are more than the minimum cacheline-multiple size class, but 468 no more than the minimum subpage-multiple size class (see the <link 469 linkend="opt.lg_cspace_max"><mallctl>opt.lg_cspace_max</mallctl></link> 470 option) are rounded up to the nearest multiple of the cacheline size (64). 471 Allocation requests that are more than the minimum subpage-multiple size 472 class, but no more than the maximum subpage-multiple size class are rounded 473 up to the nearest multiple of the subpage size (256). Allocation requests 474 that are more than the maximum subpage-multiple size class, but small 475 enough to fit in an arena-managed chunk (see the <link 476 linkend="opt.lg_chunk"><mallctl>opt.lg_chunk</mallctl></link> option), are 477 rounded up to the nearest run size. Allocation requests that are too large 478 to fit in an arena-managed chunk are rounded up to the nearest multiple of 479 the chunk size.</para> 480 481 <para>Allocations are packed tightly together, which can be an issue for 482 multi-threaded applications. If you need to assure that allocations do not 483 suffer from cacheline sharing, round your allocation requests up to the 484 nearest multiple of the cacheline size, or specify cacheline alignment when 485 allocating.</para> 486 487 <para>Assuming 4 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 64-bit 488 system, the size classes in each category are as shown in <xref 489 linkend="size_classes" xrefstyle="template:Table %n"/>.</para> 490 491 <table xml:id="size_classes" frame="all"> 492 <title>Size classes</title> 493 <tgroup cols="3" align="left" colsep="1" rowsep="1"> 494 <colspec colname="c1"/> 495 <colspec colname="c2"/> 496 <colspec colname="c3"/> 497 <thead> 498 <row> 499 <entry>Category</entry> 500 <entry>Subcategory</entry> 501 <entry>Size</entry> 502 </row> 503 </thead> 504 <tbody> 505 <row> 506 <entry morerows="3">Small</entry> 507 <entry>Tiny</entry> 508 <entry>[8]</entry> 509 </row> 510 <row> 511 <entry>Quantum-spaced</entry> 512 <entry>[16, 32, 48, ..., 128]</entry> 513 </row> 514 <row> 515 <entry>Cacheline-spaced</entry> 516 <entry>[192, 256, 320, ..., 512]</entry> 517 </row> 518 <row> 519 <entry>Subpage-spaced</entry> 520 <entry>[768, 1024, 1280, ..., 3840]</entry> 521 </row> 522 <row> 523 <entry namest="c1" nameend="c2">Large</entry> 524 <entry>[4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB]</entry> 525 </row> 526 <row> 527 <entry namest="c1" nameend="c2">Huge</entry> 528 <entry>[4 MiB, 8 MiB, 12 MiB, ...]</entry> 529 </row> 530 </tbody> 531 </tgroup> 532 </table> 533 </refsect1> 534 <refsect1 id="mallctl_namespace"> 535 <title>MALLCTL NAMESPACE</title> 536 <para>The following names are defined in the namespace accessible via the 537 <function>mallctl*<parameter/></function> functions. Value types are 538 specified in parentheses, their readable/writable statuses are encoded as 539 <literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or 540 <literal>--</literal>, and required build configuration flags follow, if 541 any. A name element encoded as <literal><i></literal> or 542 <literal><j></literal> indicates an integer component, where the 543 integer varies from 0 to some upper value that must be determined via 544 introspection. In the case of <mallctl>stats.arenas.<i>.*</mallctl>, 545 <literal><i></literal> equal to <link 546 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> can be 547 used to access the summation of statistics from all arenas. Take special 548 note of the <link linkend="epoch"><mallctl>epoch</mallctl></link> mallctl, 549 which controls refreshing of cached dynamic statistics.</para> 550 551 <variablelist> 552 <varlistentry> 553 <term> 554 <mallctl>version</mallctl> 555 (<type>const char *</type>) 556 <literal>r-</literal> 557 </term> 558 <listitem><para>Return the jemalloc version string.</para></listitem> 559 </varlistentry> 560 561 <varlistentry id="epoch"> 562 <term> 563 <mallctl>epoch</mallctl> 564 (<type>uint64_t</type>) 565 <literal>rw</literal> 566 </term> 567 <listitem><para>If a value is passed in, refresh the data from which 568 the <function>mallctl*<parameter/></function> functions report values, 569 and increment the epoch. Return the current epoch. This is useful for 570 detecting whether another thread caused a refresh.</para></listitem> 571 </varlistentry> 572 573 <varlistentry> 574 <term> 575 <mallctl>config.debug</mallctl> 576 (<type>bool</type>) 577 <literal>r-</literal> 578 </term> 579 <listitem><para><option>--enable-debug</option> was specified during 580 build configuration.</para></listitem> 581 </varlistentry> 582 583 <varlistentry> 584 <term> 585 <mallctl>config.dss</mallctl> 586 (<type>bool</type>) 587 <literal>r-</literal> 588 </term> 589 <listitem><para><option>--enable-dss</option> was specified during 590 build configuration.</para></listitem> 591 </varlistentry> 592 593 <varlistentry> 594 <term> 595 <mallctl>config.dynamic_page_shift</mallctl> 596 (<type>bool</type>) 597 <literal>r-</literal> 598 </term> 599 <listitem><para><option>--enable-dynamic-page-shift</option> was 600 specified during build configuration.</para></listitem> 601 </varlistentry> 602 603 <varlistentry> 604 <term> 605 <mallctl>config.fill</mallctl> 606 (<type>bool</type>) 607 <literal>r-</literal> 608 </term> 609 <listitem><para><option>--enable-fill</option> was specified during 610 build configuration.</para></listitem> 611 </varlistentry> 612 613 <varlistentry> 614 <term> 615 <mallctl>config.lazy_lock</mallctl> 616 (<type>bool</type>) 617 <literal>r-</literal> 618 </term> 619 <listitem><para><option>--enable-lazy-lock</option> was specified 620 during build configuration.</para></listitem> 621 </varlistentry> 622 623 <varlistentry> 624 <term> 625 <mallctl>config.prof</mallctl> 626 (<type>bool</type>) 627 <literal>r-</literal> 628 </term> 629 <listitem><para><option>--enable-prof</option> was specified during 630 build configuration.</para></listitem> 631 </varlistentry> 632 633 <varlistentry> 634 <term> 635 <mallctl>config.prof_libgcc</mallctl> 636 (<type>bool</type>) 637 <literal>r-</literal> 638 </term> 639 <listitem><para><option>--disable-prof-libgcc</option> was not 640 specified during build configuration.</para></listitem> 641 </varlistentry> 642 643 <varlistentry> 644 <term> 645 <mallctl>config.prof_libunwind</mallctl> 646 (<type>bool</type>) 647 <literal>r-</literal> 648 </term> 649 <listitem><para><option>--enable-prof-libunwind</option> was specified 650 during build configuration.</para></listitem> 651 </varlistentry> 652 653 <varlistentry> 654 <term> 655 <mallctl>config.stats</mallctl> 656 (<type>bool</type>) 657 <literal>r-</literal> 658 </term> 659 <listitem><para><option>--enable-stats</option> was specified during 660 build configuration.</para></listitem> 661 </varlistentry> 662 663 <varlistentry> 664 <term> 665 <mallctl>config.swap</mallctl> 666 (<type>bool</type>) 667 <literal>r-</literal> 668 </term> 669 <listitem><para><option>--enable-swap</option> was specified during 670 build configuration.</para></listitem> 671 </varlistentry> 672 673 <varlistentry> 674 <term> 675 <mallctl>config.sysv</mallctl> 676 (<type>bool</type>) 677 <literal>r-</literal> 678 </term> 679 <listitem><para><option>--enable-sysv</option> was specified during 680 build configuration.</para></listitem> 681 </varlistentry> 682 683 <varlistentry> 684 <term> 685 <mallctl>config.tcache</mallctl> 686 (<type>bool</type>) 687 <literal>r-</literal> 688 </term> 689 <listitem><para><option>--disable-tcache</option> was not specified 690 during build configuration.</para></listitem> 691 </varlistentry> 692 693 <varlistentry> 694 <term> 695 <mallctl>config.tiny</mallctl> 696 (<type>bool</type>) 697 <literal>r-</literal> 698 </term> 699 <listitem><para><option>--disable-tiny</option> was not specified 700 during build configuration.</para></listitem> 701 </varlistentry> 702 703 <varlistentry> 704 <term> 705 <mallctl>config.tls</mallctl> 706 (<type>bool</type>) 707 <literal>r-</literal> 708 </term> 709 <listitem><para><option>--disable-tls</option> was not specified during 710 build configuration.</para></listitem> 711 </varlistentry> 712 713 <varlistentry> 714 <term> 715 <mallctl>config.xmalloc</mallctl> 716 (<type>bool</type>) 717 <literal>r-</literal> 718 </term> 719 <listitem><para><option>--enable-xmalloc</option> was specified during 720 build configuration.</para></listitem> 721 </varlistentry> 722 723 <varlistentry id="opt.abort"> 724 <term> 725 <mallctl>opt.abort</mallctl> 726 (<type>bool</type>) 727 <literal>r-</literal> 728 </term> 729 <listitem><para>Abort-on-warning enabled/disabled. If true, most 730 warnings are fatal. The process will call 731 <citerefentry><refentrytitle>abort</refentrytitle> 732 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 733 disabled by default unless <option>--enable-debug</option> is 734 specified during configuration, in which case it is enabled by default. 735 </para></listitem> 736 </varlistentry> 737 738 <varlistentry id="opt.lg_qspace_max"> 739 <term> 740 <mallctl>opt.lg_qspace_max</mallctl> 741 (<type>size_t</type>) 742 <literal>r-</literal> 743 </term> 744 <listitem><para>Size (log base 2) of the maximum size class that is a 745 multiple of the quantum (8 or 16 bytes, depending on architecture). 746 Above this size, cacheline spacing is used for size classes. The 747 default value is 128 bytes (2^7).</para></listitem> 748 </varlistentry> 749 750 <varlistentry id="opt.lg_cspace_max"> 751 <term> 752 <mallctl>opt.lg_cspace_max</mallctl> 753 (<type>size_t</type>) 754 <literal>r-</literal> 755 </term> 756 <listitem><para>Size (log base 2) of the maximum size class that is a 757 multiple of the cacheline size (64). Above this size, subpage spacing 758 (256 bytes) is used for size classes. The default value is 512 bytes 759 (2^9).</para></listitem> 760 </varlistentry> 761 762 <varlistentry id="opt.lg_chunk"> 763 <term> 764 <mallctl>opt.lg_chunk</mallctl> 765 (<type>size_t</type>) 766 <literal>r-</literal> 767 </term> 768 <listitem><para>Virtual memory chunk size (log base 2). The default 769 chunk size is 4 MiB (2^22).</para></listitem> 770 </varlistentry> 771 772 <varlistentry id="opt.narenas"> 773 <term> 774 <mallctl>opt.narenas</mallctl> 775 (<type>size_t</type>) 776 <literal>r-</literal> 777 </term> 778 <listitem><para>Maximum number of arenas to use. The default maximum 779 number of arenas is four times the number of CPUs, or one if there is a 780 single CPU.</para></listitem> 781 </varlistentry> 782 783 <varlistentry id="opt.lg_dirty_mult"> 784 <term> 785 <mallctl>opt.lg_dirty_mult</mallctl> 786 (<type>ssize_t</type>) 787 <literal>r-</literal> 788 </term> 789 <listitem><para>Per-arena minimum ratio (log base 2) of active to dirty 790 pages. Some dirty unused pages may be allowed to accumulate, within 791 the limit set by the ratio (or one chunk worth of dirty pages, 792 whichever is greater), before informing the kernel about some of those 793 pages via <citerefentry><refentrytitle>madvise</refentrytitle> 794 <manvolnum>2</manvolnum></citerefentry> or a similar system call. This 795 provides the kernel with sufficient information to recycle dirty pages 796 if physical memory becomes scarce and the pages remain unused. The 797 default minimum ratio is 32:1 (2^5:1); an option value of -1 will 798 disable dirty page purging.</para></listitem> 799 </varlistentry> 800 801 <varlistentry id="opt.stats_print"> 802 <term> 803 <mallctl>opt.stats_print</mallctl> 804 (<type>bool</type>) 805 <literal>r-</literal> 806 </term> 807 <listitem><para>Enable/disable statistics printing at exit. If 808 enabled, the <function>malloc_stats_print<parameter/></function> 809 function is called at program exit via an 810 <citerefentry><refentrytitle>atexit</refentrytitle> 811 <manvolnum>3</manvolnum></citerefentry> function. If 812 <option>--enable-stats</option> is specified during configuration, this 813 has the potential to cause deadlock for a multi-threaded process that 814 exits while one or more threads are executing in the memory allocation 815 functions. Therefore, this option should only be used with care; it is 816 primarily intended as a performance tuning aid during application 817 development. This option is disabled by default.</para></listitem> 818 </varlistentry> 819 820 <varlistentry id="opt.junk"> 821 <term> 822 <mallctl>opt.junk</mallctl> 823 (<type>bool</type>) 824 <literal>r-</literal> 825 [<option>--enable-fill</option>] 826 </term> 827 <listitem><para>Junk filling enabled/disabled. If enabled, each byte 828 of uninitialized allocated memory will be initialized to 829 <literal>0xa5</literal>. All deallocated memory will be initialized to 830 <literal>0x5a</literal>. This is intended for debugging and will 831 impact performance negatively. This option is disabled by default 832 unless <option>--enable-debug</option> is specified during 833 configuration, in which case it is enabled by default.</para></listitem> 834 </varlistentry> 835 836 <varlistentry id="opt.zero"> 837 <term> 838 <mallctl>opt.zero</mallctl> 839 (<type>bool</type>) 840 <literal>r-</literal> 841 [<option>--enable-fill</option>] 842 </term> 843 <listitem><para>Zero filling enabled/disabled. If enabled, each byte 844 of uninitialized allocated memory will be initialized to 0. Note that 845 this initialization only happens once for each byte, so 846 <function>realloc<parameter/></function> and 847 <function>rallocm<parameter/></function> calls do not zero memory that 848 was previously allocated. This is intended for debugging and will 849 impact performance negatively. This option is disabled by default. 850 </para></listitem> 851 </varlistentry> 852 853 <varlistentry id="opt.sysv"> 854 <term> 855 <mallctl>opt.sysv</mallctl> 856 (<type>bool</type>) 857 <literal>r-</literal> 858 [<option>--enable-sysv</option>] 859 </term> 860 <listitem><para>If enabled, attempting to allocate zero bytes will 861 return a <constant>NULL</constant> pointer instead of a valid pointer. 862 (The default behavior is to make a minimal allocation and return a 863 pointer to it.) This option is provided for System V compatibility. 864 This option is incompatible with the <link 865 linkend="opt.xmalloc"><mallctl>opt.xmalloc</mallctl></link> option. 866 This option is disabled by default.</para></listitem> 867 </varlistentry> 868 869 <varlistentry id="opt.xmalloc"> 870 <term> 871 <mallctl>opt.xmalloc</mallctl> 872 (<type>bool</type>) 873 <literal>r-</literal> 874 [<option>--enable-xmalloc</option>] 875 </term> 876 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled, 877 rather than returning failure for any allocation function, display a 878 diagnostic message on <constant>STDERR_FILENO</constant> and cause the 879 program to drop core (using 880 <citerefentry><refentrytitle>abort</refentrytitle> 881 <manvolnum>3</manvolnum></citerefentry>). If an application is 882 designed to depend on this behavior, set the option at compile time by 883 including the following in the source code: 884 <programlisting language="C"><![CDATA[ 885malloc_conf = "xmalloc:true";]]></programlisting> 886 This option is disabled by default.</para></listitem> 887 </varlistentry> 888 889 <varlistentry id="opt.tcache"> 890 <term> 891 <mallctl>opt.tcache</mallctl> 892 (<type>bool</type>) 893 <literal>r-</literal> 894 [<option>--enable-tcache</option>] 895 </term> 896 <listitem><para>Thread-specific caching enabled/disabled. When there 897 are multiple threads, each thread uses a thread-specific cache for 898 objects up to a certain size. Thread-specific caching allows many 899 allocations to be satisfied without performing any thread 900 synchronization, at the cost of increased memory use. See the 901 <link 902 linkend="opt.lg_tcache_gc_sweep"><mallctl>opt.lg_tcache_gc_sweep</mallctl></link> 903 and <link 904 linkend="opt.lg_tcache_max"><mallctl>opt.lg_tcache_max</mallctl></link> 905 options for related tuning information. This option is enabled by 906 default.</para></listitem> 907 </varlistentry> 908 909 <varlistentry id="opt.lg_tcache_gc_sweep"> 910 <term> 911 <mallctl>opt.lg_tcache_gc_sweep</mallctl> 912 (<type>ssize_t</type>) 913 <literal>r-</literal> 914 [<option>--enable-tcache</option>] 915 </term> 916 <listitem><para>Approximate interval (log base 2) between full 917 thread-specific cache garbage collection sweeps, counted in terms of 918 thread-specific cache allocation/deallocation events. Garbage 919 collection is actually performed incrementally, one size class at a 920 time, in order to avoid large collection pauses. The default sweep 921 interval is 8192 (2^13); setting this option to -1 will disable garbage 922 collection.</para></listitem> 923 </varlistentry> 924 925 <varlistentry id="opt.lg_tcache_max"> 926 <term> 927 <mallctl>opt.lg_tcache_max</mallctl> 928 (<type>size_t</type>) 929 <literal>r-</literal> 930 [<option>--enable-tcache</option>] 931 </term> 932 <listitem><para>Maximum size class (log base 2) to cache in the 933 thread-specific cache. At a minimum, all small size classes are 934 cached, and at a maximum all large size classes are cached. The 935 default maximum is 32 KiB (2^15).</para></listitem> 936 </varlistentry> 937 938 <varlistentry id="opt.prof"> 939 <term> 940 <mallctl>opt.prof</mallctl> 941 (<type>bool</type>) 942 <literal>r-</literal> 943 [<option>--enable-prof</option>] 944 </term> 945 <listitem><para>Memory profiling enabled/disabled. If enabled, profile 946 memory allocation activity, and use an 947 <citerefentry><refentrytitle>atexit</refentrytitle> 948 <manvolnum>3</manvolnum></citerefentry> function to dump final memory 949 usage to a file named according to the pattern 950 <filename><prefix>.<pid>.<seq>.f.heap</filename>, 951 where <literal><prefix></literal> is controlled by the <link 952 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 953 option. See the <link 954 linkend="opt.lg_prof_bt_max"><mallctl>opt.lg_prof_bt_max</mallctl></link> 955 option for backtrace depth control. See the <link 956 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 957 option for on-the-fly activation/deactivation. See the <link 958 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 959 option for probabilistic sampling control. See the <link 960 linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> 961 option for control of cumulative sample reporting. See the <link 962 linkend="opt.lg_prof_tcmax"><mallctl>opt.lg_prof_tcmax</mallctl></link> 963 option for control of per thread backtrace caching. See the <link 964 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 965 option for information on interval-triggered profile dumping, and the 966 <link linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link> 967 option for information on high-water-triggered profile dumping. 968 Profile output is compatible with the included <command>pprof</command> 969 Perl script, which originates from the <ulink 970 url="http://code.google.com/p/google-perftools/">google-perftools 971 package</ulink>.</para></listitem> 972 </varlistentry> 973 974 <varlistentry id="opt.prof_prefix"> 975 <term> 976 <mallctl>opt.prof_prefix</mallctl> 977 (<type>const char *</type>) 978 <literal>r-</literal> 979 [<option>--enable-prof</option>] 980 </term> 981 <listitem><para>Filename prefix for profile dumps. If the prefix is 982 set to the empty string, no automatic dumps will occur; this is 983 primarily useful for disabling the automatic final heap dump (which 984 also disables leak reporting, if enabled). The default prefix is 985 <filename>jeprof</filename>.</para></listitem> 986 </varlistentry> 987 988 <varlistentry id="opt.lg_prof_bt_max"> 989 <term> 990 <mallctl>opt.lg_prof_bt_max</mallctl> 991 (<type>size_t</type>) 992 <literal>r-</literal> 993 [<option>--enable-prof</option>] 994 </term> 995 <listitem><para>Maximum backtrace depth (log base 2) when profiling 996 memory allocation activity. The default is 128 (2^7).</para></listitem> 997 </varlistentry> 998 999 <varlistentry id="opt.prof_active"> 1000 <term> 1001 <mallctl>opt.prof_active</mallctl> 1002 (<type>bool</type>) 1003 <literal>r-</literal> 1004 [<option>--enable-prof</option>] 1005 </term> 1006 <listitem><para>Profiling activated/deactivated. This is a secondary 1007 control mechanism that makes it possible to start the application with 1008 profiling enabled (see the <link 1009 linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but 1010 inactive, then toggle profiling at any time during program execution 1011 with the <link 1012 linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl. 1013 This option is enabled by default.</para></listitem> 1014 </varlistentry> 1015 1016 <varlistentry id="opt.lg_prof_sample"> 1017 <term> 1018 <mallctl>opt.lg_prof_sample</mallctl> 1019 (<type>ssize_t</type>) 1020 <literal>r-</literal> 1021 [<option>--enable-prof</option>] 1022 </term> 1023 <listitem><para>Average interval (log base 2) between allocation 1024 samples, as measured in bytes of allocation activity. Increasing the 1025 sampling interval decreases profile fidelity, but also decreases the 1026 computational overhead. The default sample interval is 1 (2^0) (i.e. 1027 all allocations are sampled).</para></listitem> 1028 </varlistentry> 1029 1030 <varlistentry id="opt.prof_accum"> 1031 <term> 1032 <mallctl>opt.prof_accum</mallctl> 1033 (<type>bool</type>) 1034 <literal>r-</literal> 1035 [<option>--enable-prof</option>] 1036 </term> 1037 <listitem><para>Reporting of cumulative object/byte counts in profile 1038 dumps enabled/disabled. If this option is enabled, every unique 1039 backtrace must be stored for the duration of execution. Depending on 1040 the application, this can impose a large memory overhead, and the 1041 cumulative counts are not always of interest. See the 1042 <link 1043 linkend="opt.lg_prof_tcmax"><mallctl>opt.lg_prof_tcmax</mallctl></link> 1044 option for control of per thread backtrace caching, which has important 1045 interactions. This option is enabled by default.</para></listitem> 1046 </varlistentry> 1047 1048 <varlistentry id="opt.lg_prof_tcmax"> 1049 <term> 1050 <mallctl>opt.lg_prof_tcmax</mallctl> 1051 (<type>ssize_t</type>) 1052 <literal>r-</literal> 1053 [<option>--enable-prof</option>] 1054 </term> 1055 <listitem><para>Maximum per thread backtrace cache (log base 2) used 1056 for heap profiling. A backtrace can only be discarded if the 1057 <link linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> 1058 option is disabled, and no thread caches currently refer to the 1059 backtrace. Therefore, a backtrace cache limit should be imposed if the 1060 intention is to limit how much memory is used by backtraces. By 1061 default, no limit is imposed (encoded as -1). 1062 </para></listitem> 1063 </varlistentry> 1064 1065 <varlistentry id="opt.lg_prof_interval"> 1066 <term> 1067 <mallctl>opt.lg_prof_interval</mallctl> 1068 (<type>ssize_t</type>) 1069 <literal>r-</literal> 1070 [<option>--enable-prof</option>] 1071 </term> 1072 <listitem><para>Average interval (log base 2) between memory profile 1073 dumps, as measured in bytes of allocation activity. The actual 1074 interval between dumps may be sporadic because decentralized allocation 1075 counters are used to avoid synchronization bottlenecks. Profiles are 1076 dumped to files named according to the pattern 1077 <filename><prefix>.<pid>.<seq>.i<iseq>.heap</filename>, 1078 where <literal><prefix></literal> is controlled by the 1079 <link 1080 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1081 option. By default, interval-triggered profile dumping is disabled 1082 (encoded as -1). 1083 </para></listitem> 1084 </varlistentry> 1085 1086 <varlistentry id="opt.prof_gdump"> 1087 <term> 1088 <mallctl>opt.prof_gdump</mallctl> 1089 (<type>bool</type>) 1090 <literal>r-</literal> 1091 [<option>--enable-prof</option>] 1092 </term> 1093 <listitem><para>Trigger a memory profile dump every time the total 1094 virtual memory exceeds the previous maximum. Profiles are dumped to 1095 files named according to the pattern 1096 <filename><prefix>.<pid>.<seq>.u<useq>.heap</filename>, 1097 where <literal><prefix></literal> is controlled by the <link 1098 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1099 option. This option is disabled by default.</para></listitem> 1100 </varlistentry> 1101 1102 <varlistentry id="opt.prof_leak"> 1103 <term> 1104 <mallctl>opt.prof_leak</mallctl> 1105 (<type>bool</type>) 1106 <literal>r-</literal> 1107 [<option>--enable-prof</option>] 1108 </term> 1109 <listitem><para>Leak reporting enabled/disabled. If enabled, use an 1110 <citerefentry><refentrytitle>atexit</refentrytitle> 1111 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks 1112 detected by allocation sampling. See the 1113 <link 1114 linkend="opt.lg_prof_bt_max"><mallctl>opt.lg_prof_bt_max</mallctl></link> 1115 option for backtrace depth control. See the 1116 <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for 1117 information on analyzing heap profile output. This option is disabled 1118 by default.</para></listitem> 1119 </varlistentry> 1120 1121 <varlistentry id="opt.overcommit"> 1122 <term> 1123 <mallctl>opt.overcommit</mallctl> 1124 (<type>bool</type>) 1125 <literal>r-</literal> 1126 [<option>--enable-swap</option>] 1127 </term> 1128 <listitem><para>Over-commit enabled/disabled. If enabled, over-commit 1129 memory as a side effect of using anonymous 1130 <citerefentry><refentrytitle>mmap</refentrytitle> 1131 <manvolnum>2</manvolnum></citerefentry> or 1132 <citerefentry><refentrytitle>sbrk</refentrytitle> 1133 <manvolnum>2</manvolnum></citerefentry> for virtual memory allocation. 1134 In order for overcommit to be disabled, the <link 1135 linkend="swap.fds"><mallctl>swap.fds</mallctl></link> mallctl must have 1136 been successfully written to. This option is enabled by 1137 default.</para></listitem> 1138 </varlistentry> 1139 1140 <varlistentry> 1141 <term> 1142 <mallctl>tcache.flush</mallctl> 1143 (<type>void</type>) 1144 <literal>--</literal> 1145 [<option>--enable-tcache</option>] 1146 </term> 1147 <listitem><para>Flush calling thread's tcache. This interface releases 1148 all cached objects and internal data structures associated with the 1149 calling thread's thread-specific cache. Ordinarily, this interface 1150 need not be called, since automatic periodic incremental garbage 1151 collection occurs, and the thread cache is automatically discarded when 1152 a thread exits. However, garbage collection is triggered by allocation 1153 activity, so it is possible for a thread that stops 1154 allocating/deallocating to retain its cache indefinitely, in which case 1155 the developer may find manual flushing useful.</para></listitem> 1156 </varlistentry> 1157 1158 <varlistentry> 1159 <term> 1160 <mallctl>thread.arena</mallctl> 1161 (<type>unsigned</type>) 1162 <literal>rw</literal> 1163 </term> 1164 <listitem><para>Get or set the arena associated with the calling 1165 thread. The arena index must be less than the maximum number of arenas 1166 (see the <link 1167 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> 1168 mallctl). If the specified arena was not initialized beforehand (see 1169 the <link 1170 linkend="arenas.initialized"><mallctl>arenas.initialized</mallctl></link> 1171 mallctl), it will be automatically initialized as a side effect of 1172 calling this interface.</para></listitem> 1173 </varlistentry> 1174 1175 <varlistentry id="thread.allocated"> 1176 <term> 1177 <mallctl>thread.allocated</mallctl> 1178 (<type>uint64_t</type>) 1179 <literal>r-</literal> 1180 [<option>--enable-stats</option>] 1181 </term> 1182 <listitem><para>Get the total number of bytes ever allocated by the 1183 calling thread. This counter has the potential to wrap around; it is 1184 up to the application to appropriately interpret the counter in such 1185 cases.</para></listitem> 1186 </varlistentry> 1187 1188 <varlistentry> 1189 <term> 1190 <mallctl>thread.allocatedp</mallctl> 1191 (<type>uint64_t *</type>) 1192 <literal>r-</literal> 1193 [<option>--enable-stats</option>] 1194 </term> 1195 <listitem><para>Get a pointer to the the value that is returned by the 1196 <link 1197 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 1198 mallctl. This is useful for avoiding the overhead of repeated 1199 <function>mallctl*<parameter/></function> calls.</para></listitem> 1200 </varlistentry> 1201 1202 <varlistentry id="thread.deallocated"> 1203 <term> 1204 <mallctl>thread.deallocated</mallctl> 1205 (<type>uint64_t</type>) 1206 <literal>r-</literal> 1207 [<option>--enable-stats</option>] 1208 </term> 1209 <listitem><para>Get the total number of bytes ever deallocated by the 1210 calling thread. This counter has the potential to wrap around; it is 1211 up to the application to appropriately interpret the counter in such 1212 cases.</para></listitem> 1213 </varlistentry> 1214 1215 <varlistentry> 1216 <term> 1217 <mallctl>thread.deallocatedp</mallctl> 1218 (<type>uint64_t *</type>) 1219 <literal>r-</literal> 1220 [<option>--enable-stats</option>] 1221 </term> 1222 <listitem><para>Get a pointer to the the value that is returned by the 1223 <link 1224 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link> 1225 mallctl. This is useful for avoiding the overhead of repeated 1226 <function>mallctl*<parameter/></function> calls.</para></listitem> 1227 </varlistentry> 1228 1229 <varlistentry id="arenas.narenas"> 1230 <term> 1231 <mallctl>arenas.narenas</mallctl> 1232 (<type>unsigned</type>) 1233 <literal>r-</literal> 1234 </term> 1235 <listitem><para>Maximum number of arenas.</para></listitem> 1236 </varlistentry> 1237 1238 <varlistentry id="arenas.initialized"> 1239 <term> 1240 <mallctl>arenas.initialized</mallctl> 1241 (<type>bool *</type>) 1242 <literal>r-</literal> 1243 </term> 1244 <listitem><para>An array of <link 1245 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> 1246 booleans. Each boolean indicates whether the corresponding arena is 1247 initialized.</para></listitem> 1248 </varlistentry> 1249 1250 <varlistentry> 1251 <term> 1252 <mallctl>arenas.quantum</mallctl> 1253 (<type>size_t</type>) 1254 <literal>r-</literal> 1255 </term> 1256 <listitem><para>Quantum size.</para></listitem> 1257 </varlistentry> 1258 1259 <varlistentry> 1260 <term> 1261 <mallctl>arenas.cacheline</mallctl> 1262 (<type>size_t</type>) 1263 <literal>r-</literal> 1264 </term> 1265 <listitem><para>Assumed cacheline size.</para></listitem> 1266 </varlistentry> 1267 1268 <varlistentry> 1269 <term> 1270 <mallctl>arenas.subpage</mallctl> 1271 (<type>size_t</type>) 1272 <literal>r-</literal> 1273 </term> 1274 <listitem><para>Subpage size class interval.</para></listitem> 1275 </varlistentry> 1276 1277 <varlistentry> 1278 <term> 1279 <mallctl>arenas.pagesize</mallctl> 1280 (<type>size_t</type>) 1281 <literal>r-</literal> 1282 </term> 1283 <listitem><para>Page size.</para></listitem> 1284 </varlistentry> 1285 1286 <varlistentry> 1287 <term> 1288 <mallctl>arenas.chunksize</mallctl> 1289 (<type>size_t</type>) 1290 <literal>r-</literal> 1291 </term> 1292 <listitem><para>Chunk size.</para></listitem> 1293 </varlistentry> 1294 1295 <varlistentry> 1296 <term> 1297 <mallctl>arenas.tspace_min</mallctl> 1298 (<type>size_t</type>) 1299 <literal>r-</literal> 1300 </term> 1301 <listitem><para>Minimum tiny size class. Tiny size classes are powers 1302 of two.</para></listitem> 1303 </varlistentry> 1304 1305 <varlistentry> 1306 <term> 1307 <mallctl>arenas.tspace_max</mallctl> 1308 (<type>size_t</type>) 1309 <literal>r-</literal> 1310 </term> 1311 <listitem><para>Maximum tiny size class. Tiny size classes are powers 1312 of two.</para></listitem> 1313 </varlistentry> 1314 1315 <varlistentry> 1316 <term> 1317 <mallctl>arenas.qspace_min</mallctl> 1318 (<type>size_t</type>) 1319 <literal>r-</literal> 1320 </term> 1321 <listitem><para>Minimum quantum-spaced size class.</para></listitem> 1322 </varlistentry> 1323 1324 <varlistentry> 1325 <term> 1326 <mallctl>arenas.qspace_max</mallctl> 1327 (<type>size_t</type>) 1328 <literal>r-</literal> 1329 </term> 1330 <listitem><para>Maximum quantum-spaced size class.</para></listitem> 1331 </varlistentry> 1332 1333 <varlistentry> 1334 <term> 1335 <mallctl>arenas.cspace_min</mallctl> 1336 (<type>size_t</type>) 1337 <literal>r-</literal> 1338 </term> 1339 <listitem><para>Minimum cacheline-spaced size class.</para></listitem> 1340 </varlistentry> 1341 1342 <varlistentry> 1343 <term> 1344 <mallctl>arenas.cspace_max</mallctl> 1345 (<type>size_t</type>) 1346 <literal>r-</literal> 1347 </term> 1348 <listitem><para>Maximum cacheline-spaced size class.</para></listitem> 1349 </varlistentry> 1350 1351 <varlistentry> 1352 <term> 1353 <mallctl>arenas.sspace_min</mallctl> 1354 (<type>size_t</type>) 1355 <literal>r-</literal> 1356 </term> 1357 <listitem><para>Minimum subpage-spaced size class.</para></listitem> 1358 </varlistentry> 1359 1360 <varlistentry> 1361 <term> 1362 <mallctl>arenas.sspace_max</mallctl> 1363 (<type>size_t</type>) 1364 <literal>r-</literal> 1365 </term> 1366 <listitem><para>Maximum subpage-spaced size class.</para></listitem> 1367 </varlistentry> 1368 1369 <varlistentry> 1370 <term> 1371 <mallctl>arenas.tcache_max</mallctl> 1372 (<type>size_t</type>) 1373 <literal>r-</literal> 1374 [<option>--enable-tcache</option>] 1375 </term> 1376 <listitem><para>Maximum thread-cached size class.</para></listitem> 1377 </varlistentry> 1378 1379 <varlistentry> 1380 <term> 1381 <mallctl>arenas.ntbins</mallctl> 1382 (<type>unsigned</type>) 1383 <literal>r-</literal> 1384 </term> 1385 <listitem><para>Number of tiny bin size classes.</para></listitem> 1386 </varlistentry> 1387 1388 <varlistentry> 1389 <term> 1390 <mallctl>arenas.nqbins</mallctl> 1391 (<type>unsigned</type>) 1392 <literal>r-</literal> 1393 </term> 1394 <listitem><para>Number of quantum-spaced bin size 1395 classes.</para></listitem> 1396 </varlistentry> 1397 1398 <varlistentry> 1399 <term> 1400 <mallctl>arenas.ncbins</mallctl> 1401 (<type>unsigned</type>) 1402 <literal>r-</literal> 1403 </term> 1404 <listitem><para>Number of cacheline-spaced bin size 1405 classes.</para></listitem> 1406 </varlistentry> 1407 1408 <varlistentry> 1409 <term> 1410 <mallctl>arenas.nsbins</mallctl> 1411 (<type>unsigned</type>) 1412 <literal>r-</literal> 1413 </term> 1414 <listitem><para>Number of subpage-spaced bin size 1415 classes.</para></listitem> 1416 </varlistentry> 1417 1418 <varlistentry> 1419 <term> 1420 <mallctl>arenas.nbins</mallctl> 1421 (<type>unsigned</type>) 1422 <literal>r-</literal> 1423 </term> 1424 <listitem><para>Total number of bin size classes.</para></listitem> 1425 </varlistentry> 1426 1427 <varlistentry> 1428 <term> 1429 <mallctl>arenas.nhbins</mallctl> 1430 (<type>unsigned</type>) 1431 <literal>r-</literal> 1432 [<option>--enable-tcache</option>] 1433 </term> 1434 <listitem><para>Total number of thread cache bin size 1435 classes.</para></listitem> 1436 </varlistentry> 1437 1438 <varlistentry id="arenas.bin.i.size"> 1439 <term> 1440 <mallctl>arenas.bin.<i>.size</mallctl> 1441 (<type>size_t</type>) 1442 <literal>r-</literal> 1443 </term> 1444 <listitem><para>Maximum size supported by size class.</para></listitem> 1445 </varlistentry> 1446 1447 <varlistentry> 1448 <term> 1449 <mallctl>arenas.bin.<i>.nregs</mallctl> 1450 (<type>uint32_t</type>) 1451 <literal>r-</literal> 1452 </term> 1453 <listitem><para>Number of regions per page run.</para></listitem> 1454 </varlistentry> 1455 1456 <varlistentry> 1457 <term> 1458 <mallctl>arenas.bin.<i>.run_size</mallctl> 1459 (<type>size_t</type>) 1460 <literal>r-</literal> 1461 </term> 1462 <listitem><para>Number of bytes per page run.</para></listitem> 1463 </varlistentry> 1464 1465 <varlistentry> 1466 <term> 1467 <mallctl>arenas.nlruns</mallctl> 1468 (<type>size_t</type>) 1469 <literal>r-</literal> 1470 </term> 1471 <listitem><para>Total number of large size classes.</para></listitem> 1472 </varlistentry> 1473 1474 <varlistentry> 1475 <term> 1476 <mallctl>arenas.lrun.<i>.size</mallctl> 1477 (<type>size_t</type>) 1478 <literal>r-</literal> 1479 </term> 1480 <listitem><para>Maximum size supported by this large size 1481 class.</para></listitem> 1482 </varlistentry> 1483 1484 <varlistentry> 1485 <term> 1486 <mallctl>arenas.purge</mallctl> 1487 (<type>unsigned</type>) 1488 <literal>-w</literal> 1489 </term> 1490 <listitem><para>Purge unused dirty pages for the specified arena, or 1491 for all arenas if none is specified.</para></listitem> 1492 </varlistentry> 1493 1494 <varlistentry id="prof.active"> 1495 <term> 1496 <mallctl>prof.active</mallctl> 1497 (<type>bool</type>) 1498 <literal>rw</literal> 1499 [<option>--enable-prof</option>] 1500 </term> 1501 <listitem><para>Control whether sampling is currently active. See the 1502 <link 1503 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 1504 option for additional information. 1505 </para></listitem> 1506 </varlistentry> 1507 1508 <varlistentry> 1509 <term> 1510 <mallctl>prof.dump</mallctl> 1511 (<type>const char *</type>) 1512 <literal>-w</literal> 1513 [<option>--enable-prof</option>] 1514 </term> 1515 <listitem><para>Dump a memory profile to the specified file, or if NULL 1516 is specified, to a file according to the pattern 1517 <filename><prefix>.<pid>.<seq>.m<mseq>.heap</filename>, 1518 where <literal><prefix></literal> is controlled by the 1519 <link 1520 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1521 option.</para></listitem> 1522 </varlistentry> 1523 1524 <varlistentry> 1525 <term> 1526 <mallctl>prof.interval</mallctl> 1527 (<type>uint64_t</type>) 1528 <literal>r-</literal> 1529 [<option>--enable-prof</option>] 1530 </term> 1531 <listitem><para>Average number of bytes allocated between 1532 inverval-based profile dumps. See the 1533 <link 1534 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 1535 option for additional information.</para></listitem> 1536 </varlistentry> 1537 1538 <varlistentry id="stats.cactive"> 1539 <term> 1540 <mallctl>stats.cactive</mallctl> 1541 (<type>size_t *</type>) 1542 <literal>r-</literal> 1543 [<option>--enable-stats</option>] 1544 </term> 1545 <listitem><para>Pointer to a counter that contains an approximate count 1546 of the current number of bytes in active pages. The estimate may be 1547 high, but never low, because each arena rounds up to the nearest 1548 multiple of the chunk size when computing its contribution to the 1549 counter. Note that the <link 1550 linkend="epoch"><mallctl>epoch</mallctl></link> mallctl has no bearing 1551 on this counter. Furthermore, counter consistency is maintained via 1552 atomic operations, so it is necessary to use an atomic operation in 1553 order to guarantee a consistent read when dereferencing the pointer. 1554 </para></listitem> 1555 </varlistentry> 1556 1557 <varlistentry id="stats.allocated"> 1558 <term> 1559 <mallctl>stats.allocated</mallctl> 1560 (<type>size_t</type>) 1561 <literal>r-</literal> 1562 [<option>--enable-stats</option>] 1563 </term> 1564 <listitem><para>Total number of bytes allocated by the 1565 application.</para></listitem> 1566 </varlistentry> 1567 1568 <varlistentry id="stats.active"> 1569 <term> 1570 <mallctl>stats.active</mallctl> 1571 (<type>size_t</type>) 1572 <literal>r-</literal> 1573 [<option>--enable-stats</option>] 1574 </term> 1575 <listitem><para>Total number of bytes in active pages allocated by the 1576 application. This is a multiple of the page size, and greater than or 1577 equal to <link 1578 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>. 1579 </para></listitem> 1580 </varlistentry> 1581 1582 <varlistentry> 1583 <term> 1584 <mallctl>stats.mapped</mallctl> 1585 (<type>size_t</type>) 1586 <literal>r-</literal> 1587 [<option>--enable-stats</option>] 1588 </term> 1589 <listitem><para>Total number of bytes in chunks mapped on behalf of the 1590 application. This is a multiple of the chunk size, and is at least as 1591 large as <link 1592 linkend="stats.active"><mallctl>stats.active</mallctl></link>. This 1593 does not include inactive chunks backed by swap files. his does not 1594 include inactive chunks embedded in the DSS.</para></listitem> 1595 </varlistentry> 1596 1597 <varlistentry> 1598 <term> 1599 <mallctl>stats.chunks.current</mallctl> 1600 (<type>size_t</type>) 1601 <literal>r-</literal> 1602 [<option>--enable-stats</option>] 1603 </term> 1604 <listitem><para>Total number of chunks actively mapped on behalf of the 1605 application. This does not include inactive chunks backed by swap 1606 files. This does not include inactive chunks embedded in the DSS. 1607 </para></listitem> 1608 </varlistentry> 1609 1610 <varlistentry> 1611 <term> 1612 <mallctl>stats.chunks.total</mallctl> 1613 (<type>uint64_t</type>) 1614 <literal>r-</literal> 1615 [<option>--enable-stats</option>] 1616 </term> 1617 <listitem><para>Cumulative number of chunks allocated.</para></listitem> 1618 </varlistentry> 1619 1620 <varlistentry> 1621 <term> 1622 <mallctl>stats.chunks.high</mallctl> 1623 (<type>size_t</type>) 1624 <literal>r-</literal> 1625 [<option>--enable-stats</option>] 1626 </term> 1627 <listitem><para>Maximum number of active chunks at any time thus far. 1628 </para></listitem> 1629 </varlistentry> 1630 1631 <varlistentry> 1632 <term> 1633 <mallctl>stats.huge.allocated</mallctl> 1634 (<type>size_t</type>) 1635 <literal>r-</literal> 1636 [<option>--enable-stats</option>] 1637 </term> 1638 <listitem><para>Number of bytes currently allocated by huge objects. 1639 </para></listitem> 1640 </varlistentry> 1641 1642 <varlistentry> 1643 <term> 1644 <mallctl>stats.huge.nmalloc</mallctl> 1645 (<type>uint64_t</type>) 1646 <literal>r-</literal> 1647 [<option>--enable-stats</option>] 1648 </term> 1649 <listitem><para>Cumulative number of huge allocation requests. 1650 </para></listitem> 1651 </varlistentry> 1652 1653 <varlistentry> 1654 <term> 1655 <mallctl>stats.huge.ndalloc</mallctl> 1656 (<type>uint64_t</type>) 1657 <literal>r-</literal> 1658 [<option>--enable-stats</option>] 1659 </term> 1660 <listitem><para>Cumulative number of huge deallocation requests. 1661 </para></listitem> 1662 </varlistentry> 1663 1664 <varlistentry> 1665 <term> 1666 <mallctl>stats.arenas.<i>.nthreads</mallctl> 1667 (<type>unsigned</type>) 1668 <literal>r-</literal> 1669 </term> 1670 <listitem><para>Number of threads currently assigned to 1671 arena.</para></listitem> 1672 </varlistentry> 1673 1674 <varlistentry> 1675 <term> 1676 <mallctl>stats.arenas.<i>.pactive</mallctl> 1677 (<type>size_t</type>) 1678 <literal>r-</literal> 1679 </term> 1680 <listitem><para>Number of pages in active runs.</para></listitem> 1681 </varlistentry> 1682 1683 <varlistentry> 1684 <term> 1685 <mallctl>stats.arenas.<i>.pdirty</mallctl> 1686 (<type>size_t</type>) 1687 <literal>r-</literal> 1688 </term> 1689 <listitem><para>Number of pages within unused runs that are potentially 1690 dirty, and for which <function>madvise<parameter>...</parameter> 1691 <parameter><constant>MADV_DONTNEED</constant></parameter></function> or 1692 similar has not been called.</para></listitem> 1693 </varlistentry> 1694 1695 <varlistentry> 1696 <term> 1697 <mallctl>stats.arenas.<i>.mapped</mallctl> 1698 (<type>size_t</type>) 1699 <literal>r-</literal> 1700 [<option>--enable-stats</option>] 1701 </term> 1702 <listitem><para>Number of mapped bytes.</para></listitem> 1703 </varlistentry> 1704 1705 <varlistentry> 1706 <term> 1707 <mallctl>stats.arenas.<i>.npurge</mallctl> 1708 (<type>uint64_t</type>) 1709 <literal>r-</literal> 1710 [<option>--enable-stats</option>] 1711 </term> 1712 <listitem><para>Number of dirty page purge sweeps performed. 1713 </para></listitem> 1714 </varlistentry> 1715 1716 <varlistentry> 1717 <term> 1718 <mallctl>stats.arenas.<i>.nmadvise</mallctl> 1719 (<type>uint64_t</type>) 1720 <literal>r-</literal> 1721 [<option>--enable-stats</option>] 1722 </term> 1723 <listitem><para>Number of <function>madvise<parameter>...</parameter> 1724 <parameter><constant>MADV_DONTNEED</constant></parameter></function> or 1725 similar calls made to purge dirty pages.</para></listitem> 1726 </varlistentry> 1727 1728 <varlistentry> 1729 <term> 1730 <mallctl>stats.arenas.<i>.npurged</mallctl> 1731 (<type>uint64_t</type>) 1732 <literal>r-</literal> 1733 [<option>--enable-stats</option>] 1734 </term> 1735 <listitem><para>Number of pages purged.</para></listitem> 1736 </varlistentry> 1737 1738 <varlistentry> 1739 <term> 1740 <mallctl>stats.arenas.<i>.small.allocated</mallctl> 1741 (<type>size_t</type>) 1742 <literal>r-</literal> 1743 [<option>--enable-stats</option>] 1744 </term> 1745 <listitem><para>Number of bytes currently allocated by small objects. 1746 </para></listitem> 1747 </varlistentry> 1748 1749 <varlistentry> 1750 <term> 1751 <mallctl>stats.arenas.<i>.small.nmalloc</mallctl> 1752 (<type>uint64_t</type>) 1753 <literal>r-</literal> 1754 [<option>--enable-stats</option>] 1755 </term> 1756 <listitem><para>Cumulative number of allocation requests served by 1757 small bins.</para></listitem> 1758 </varlistentry> 1759 1760 <varlistentry> 1761 <term> 1762 <mallctl>stats.arenas.<i>.small.ndalloc</mallctl> 1763 (<type>uint64_t</type>) 1764 <literal>r-</literal> 1765 [<option>--enable-stats</option>] 1766 </term> 1767 <listitem><para>Cumulative number of small objects returned to bins. 1768 </para></listitem> 1769 </varlistentry> 1770 1771 <varlistentry> 1772 <term> 1773 <mallctl>stats.arenas.<i>.small.nrequests</mallctl> 1774 (<type>uint64_t</type>) 1775 <literal>r-</literal> 1776 [<option>--enable-stats</option>] 1777 </term> 1778 <listitem><para>Cumulative number of small allocation requests. 1779 </para></listitem> 1780 </varlistentry> 1781 1782 <varlistentry> 1783 <term> 1784 <mallctl>stats.arenas.<i>.large.allocated</mallctl> 1785 (<type>size_t</type>) 1786 <literal>r-</literal> 1787 [<option>--enable-stats</option>] 1788 </term> 1789 <listitem><para>Number of bytes currently allocated by large objects. 1790 </para></listitem> 1791 </varlistentry> 1792 1793 <varlistentry> 1794 <term> 1795 <mallctl>stats.arenas.<i>.large.nmalloc</mallctl> 1796 (<type>uint64_t</type>) 1797 <literal>r-</literal> 1798 [<option>--enable-stats</option>] 1799 </term> 1800 <listitem><para>Cumulative number of large allocation requests served 1801 directly by the arena.</para></listitem> 1802 </varlistentry> 1803 1804 <varlistentry> 1805 <term> 1806 <mallctl>stats.arenas.<i>.large.ndalloc</mallctl> 1807 (<type>uint64_t</type>) 1808 <literal>r-</literal> 1809 [<option>--enable-stats</option>] 1810 </term> 1811 <listitem><para>Cumulative number of large deallocation requests served 1812 directly by the arena.</para></listitem> 1813 </varlistentry> 1814 1815 <varlistentry> 1816 <term> 1817 <mallctl>stats.arenas.<i>.large.nrequests</mallctl> 1818 (<type>uint64_t</type>) 1819 <literal>r-</literal> 1820 [<option>--enable-stats</option>] 1821 </term> 1822 <listitem><para>Cumulative number of large allocation requests. 1823 </para></listitem> 1824 </varlistentry> 1825 1826 <varlistentry> 1827 <term> 1828 <mallctl>stats.arenas.<i>.bins.<j>.allocated</mallctl> 1829 (<type>size_t</type>) 1830 <literal>r-</literal> 1831 [<option>--enable-stats</option>] 1832 </term> 1833 <listitem><para>Current number of bytes allocated by 1834 bin.</para></listitem> 1835 </varlistentry> 1836 1837 <varlistentry> 1838 <term> 1839 <mallctl>stats.arenas.<i>.bins.<j>.nmalloc</mallctl> 1840 (<type>uint64_t</type>) 1841 <literal>r-</literal> 1842 [<option>--enable-stats</option>] 1843 </term> 1844 <listitem><para>Cumulative number of allocations served by bin. 1845 </para></listitem> 1846 </varlistentry> 1847 1848 <varlistentry> 1849 <term> 1850 <mallctl>stats.arenas.<i>.bins.<j>.ndalloc</mallctl> 1851 (<type>uint64_t</type>) 1852 <literal>r-</literal> 1853 [<option>--enable-stats</option>] 1854 </term> 1855 <listitem><para>Cumulative number of allocations returned to bin. 1856 </para></listitem> 1857 </varlistentry> 1858 1859 <varlistentry> 1860 <term> 1861 <mallctl>stats.arenas.<i>.bins.<j>.nrequests</mallctl> 1862 (<type>uint64_t</type>) 1863 <literal>r-</literal> 1864 [<option>--enable-stats</option>] 1865 </term> 1866 <listitem><para>Cumulative number of allocation 1867 requests.</para></listitem> 1868 </varlistentry> 1869 1870 <varlistentry> 1871 <term> 1872 <mallctl>stats.arenas.<i>.bins.<j>.nfills</mallctl> 1873 (<type>uint64_t</type>) 1874 <literal>r-</literal> 1875 [<option>--enable-stats</option> <option>--enable-tcache</option>] 1876 </term> 1877 <listitem><para>Cumulative number of tcache fills.</para></listitem> 1878 </varlistentry> 1879 1880 <varlistentry> 1881 <term> 1882 <mallctl>stats.arenas.<i>.bins.<j>.nflushes</mallctl> 1883 (<type>uint64_t</type>) 1884 <literal>r-</literal> 1885 [<option>--enable-stats</option> <option>--enable-tcache</option>] 1886 </term> 1887 <listitem><para>Cumulative number of tcache flushes.</para></listitem> 1888 </varlistentry> 1889 1890 <varlistentry> 1891 <term> 1892 <mallctl>stats.arenas.<i>.bins.<j>.nruns</mallctl> 1893 (<type>uint64_t</type>) 1894 <literal>r-</literal> 1895 [<option>--enable-stats</option>] 1896 </term> 1897 <listitem><para>Cumulative number of runs created.</para></listitem> 1898 </varlistentry> 1899 1900 <varlistentry> 1901 <term> 1902 <mallctl>stats.arenas.<i>.bins.<j>.nreruns</mallctl> 1903 (<type>uint64_t</type>) 1904 <literal>r-</literal> 1905 [<option>--enable-stats</option>] 1906 </term> 1907 <listitem><para>Cumulative number of times the current run from which 1908 to allocate changed.</para></listitem> 1909 </varlistentry> 1910 1911 <varlistentry> 1912 <term> 1913 <mallctl>stats.arenas.<i>.bins.<j>.highruns</mallctl> 1914 (<type>size_t</type>) 1915 <literal>r-</literal> 1916 [<option>--enable-stats</option>] 1917 </term> 1918 <listitem><para>Maximum number of runs at any time thus far. 1919 </para></listitem> 1920 </varlistentry> 1921 1922 <varlistentry> 1923 <term> 1924 <mallctl>stats.arenas.<i>.bins.<j>.curruns</mallctl> 1925 (<type>size_t</type>) 1926 <literal>r-</literal> 1927 [<option>--enable-stats</option>] 1928 </term> 1929 <listitem><para>Current number of runs.</para></listitem> 1930 </varlistentry> 1931 1932 <varlistentry> 1933 <term> 1934 <mallctl>stats.arenas.<i>.lruns.<j>.nmalloc</mallctl> 1935 (<type>uint64_t</type>) 1936 <literal>r-</literal> 1937 [<option>--enable-stats</option>] 1938 </term> 1939 <listitem><para>Cumulative number of allocation requests for this size 1940 class served directly by the arena.</para></listitem> 1941 </varlistentry> 1942 1943 <varlistentry> 1944 <term> 1945 <mallctl>stats.arenas.<i>.lruns.<j>.ndalloc</mallctl> 1946 (<type>uint64_t</type>) 1947 <literal>r-</literal> 1948 [<option>--enable-stats</option>] 1949 </term> 1950 <listitem><para>Cumulative number of deallocation requests for this 1951 size class served directly by the arena.</para></listitem> 1952 </varlistentry> 1953 1954 <varlistentry> 1955 <term> 1956 <mallctl>stats.arenas.<i>.lruns.<j>.nrequests</mallctl> 1957 (<type>uint64_t</type>) 1958 <literal>r-</literal> 1959 [<option>--enable-stats</option>] 1960 </term> 1961 <listitem><para>Cumulative number of allocation requests for this size 1962 class.</para></listitem> 1963 </varlistentry> 1964 1965 <varlistentry> 1966 <term> 1967 <mallctl>stats.arenas.<i>.lruns.<j>.highruns</mallctl> 1968 (<type>size_t</type>) 1969 <literal>r-</literal> 1970 [<option>--enable-stats</option>] 1971 </term> 1972 <listitem><para>Maximum number of runs at any time thus far for this 1973 size class.</para></listitem> 1974 </varlistentry> 1975 1976 <varlistentry> 1977 <term> 1978 <mallctl>stats.arenas.<i>.lruns.<j>.curruns</mallctl> 1979 (<type>size_t</type>) 1980 <literal>r-</literal> 1981 [<option>--enable-stats</option>] 1982 </term> 1983 <listitem><para>Current number of runs for this size class. 1984 </para></listitem> 1985 </varlistentry> 1986 1987 <varlistentry> 1988 <term> 1989 <mallctl>swap.avail</mallctl> 1990 (<type>size_t</type>) 1991 <literal>r-</literal> 1992 [<option>--enable-stats --enable-swap</option>] 1993 </term> 1994 <listitem><para>Number of swap file bytes that are currently not 1995 associated with any chunk (i.e. mapped, but otherwise completely 1996 unmanaged).</para></listitem> 1997 </varlistentry> 1998 1999 <varlistentry id="swap.prezeroed"> 2000 <term> 2001 <mallctl>swap.prezeroed</mallctl> 2002 (<type>bool</type>) 2003 <literal>rw</literal> 2004 [<option>--enable-swap</option>] 2005 </term> 2006 <listitem><para>If true, the allocator assumes that the swap file(s) 2007 contain nothing but nil bytes. If this assumption is violated, 2008 allocator behavior is undefined. This value becomes read-only after 2009 <link linkend="swap.fds"><mallctl>swap.fds</mallctl></link> is 2010 successfully written to.</para></listitem> 2011 </varlistentry> 2012 2013 <varlistentry> 2014 <term> 2015 <mallctl>swap.nfds</mallctl> 2016 (<type>size_t</type>) 2017 <literal>r-</literal> 2018 [<option>--enable-swap</option>] 2019 </term> 2020 <listitem><para>Number of file descriptors in use for swap. 2021 </para></listitem> 2022 </varlistentry> 2023 2024 <varlistentry id="swap.fds"> 2025 <term> 2026 <mallctl>swap.fds</mallctl> 2027 (<type>int *</type>) 2028 <literal>r-</literal> 2029 [<option>--enable-swap</option>] 2030 </term> 2031 <listitem><para>When written to, the files associated with the 2032 specified file descriptors are contiguously mapped via 2033 <citerefentry><refentrytitle>mmap</refentrytitle> 2034 <manvolnum>2</manvolnum></citerefentry>. The resulting virtual memory 2035 region is preferred over anonymous 2036 <citerefentry><refentrytitle>mmap</refentrytitle> 2037 <manvolnum>2</manvolnum></citerefentry> and 2038 <citerefentry><refentrytitle>sbrk</refentrytitle> 2039 <manvolnum>2</manvolnum></citerefentry> memory. Note that if a file's 2040 size is not a multiple of the page size, it is automatically truncated 2041 to the nearest page size multiple. See the 2042 <link linkend="swap.prezeroed"><mallctl>swap.prezeroed</mallctl></link> 2043 mallctl for specifying that the files are pre-zeroed.</para></listitem> 2044 </varlistentry> 2045 </variablelist> 2046 </refsect1> 2047 <refsect1 id="debugging_malloc_problems"> 2048 <title>DEBUGGING MALLOC PROBLEMS</title> 2049 <para>When debugging, it is a good idea to configure/build jemalloc with 2050 the <option>--enable-debug</option> and <option>--enable-fill</option> 2051 options, and recompile the program with suitable options and symbols for 2052 debugger support. When so configured, jemalloc incorporates a wide variety 2053 of run-time assertions that catch application errors such as double-free, 2054 write-after-free, etc.</para> 2055 2056 <para>Programs often accidentally depend on “uninitialized” 2057 memory actually being filled with zero bytes. Junk filling 2058 (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> 2059 option) tends to expose such bugs in the form of obviously incorrect 2060 results and/or coredumps. Conversely, zero 2061 filling (see the <link 2062 linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates 2063 the symptoms of such bugs. Between these two options, it is usually 2064 possible to quickly detect, diagnose, and eliminate such bugs.</para> 2065 2066 <para>This implementation does not provide much detail about the problems 2067 it detects, because the performance impact for storing such information 2068 would be prohibitive. There are a number of allocator implementations 2069 available on the Internet which focus on detecting and pinpointing problems 2070 by trading performance for extra sanity checks and detailed 2071 diagnostics.</para> 2072 </refsect1> 2073 <refsect1 id="diagnostic_messages"> 2074 <title>DIAGNOSTIC MESSAGES</title> 2075 <para>If any of the memory allocation/deallocation functions detect an 2076 error or warning condition, a message will be printed to file descriptor 2077 <constant>STDERR_FILENO</constant>. Errors will result in the process 2078 dumping core. If the <link 2079 linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most 2080 warnings are treated as errors.</para> 2081 2082 <para>The <varname>malloc_message</varname> variable allows the programmer 2083 to override the function which emits the text strings forming the errors 2084 and warnings if for some reason the <constant>STDERR_FILENO</constant> file 2085 descriptor is not suitable for this. 2086 <function>malloc_message<parameter/></function> takes the 2087 <parameter>cbopaque</parameter> pointer argument that is 2088 <constant>NULL</constant> unless overridden by the arguments in a call to 2089 <function>malloc_stats_print<parameter/></function>, followed by a string 2090 pointer. Please note that doing anything which tries to allocate memory in 2091 this function is likely to result in a crash or deadlock.</para> 2092 2093 <para>All messages are prefixed by 2094 “<computeroutput><jemalloc>: </computeroutput>”.</para> 2095 </refsect1> 2096 <refsect1 id="return_values"> 2097 <title>RETURN VALUES</title> 2098 <refsect2> 2099 <title>Standard API</title> 2100 <para>The <function>malloc<parameter/></function> and 2101 <function>calloc<parameter/></function> functions return a pointer to the 2102 allocated memory if successful; otherwise a <constant>NULL</constant> 2103 pointer is returned and <varname>errno</varname> is set to 2104 <errorname>ENOMEM</errorname>.</para> 2105 2106 <para>The <function>posix_memalign<parameter/></function> function 2107 returns the value 0 if successful; otherwise it returns an error value. 2108 The <function>posix_memalign<parameter/></function> function will fail 2109 if: 2110 <variablelist> 2111 <varlistentry> 2112 <term><errorname>EINVAL</errorname></term> 2113 2114 <listitem><para>The <parameter>alignment</parameter> parameter is 2115 not a power of 2 at least as large as 2116 <code language="C">sizeof(<type>void *</type>)</code>. 2117 </para></listitem> 2118 </varlistentry> 2119 <varlistentry> 2120 <term><errorname>ENOMEM</errorname></term> 2121 2122 <listitem><para>Memory allocation error.</para></listitem> 2123 </varlistentry> 2124 </variablelist> 2125 </para> 2126 2127 <para>The <function>realloc<parameter/></function> function returns a 2128 pointer, possibly identical to <parameter>ptr</parameter>, to the 2129 allocated memory if successful; otherwise a <constant>NULL</constant> 2130 pointer is returned, and <varname>errno</varname> is set to 2131 <errorname>ENOMEM</errorname> if the error was the result of an 2132 allocation failure. The <function>realloc<parameter/></function> 2133 function always leaves the original buffer intact when an error occurs. 2134 </para> 2135 2136 <para>The <function>free<parameter/></function> function returns no 2137 value.</para> 2138 </refsect2> 2139 <refsect2> 2140 <title>Non-standard API</title> 2141 <para>The <function>malloc_usable_size<parameter/></function> function 2142 returns the usable size of the allocation pointed to by 2143 <parameter>ptr</parameter>. </para> 2144 2145 <para>The <function>mallctl<parameter/></function>, 2146 <function>mallctlnametomib<parameter/></function>, and 2147 <function>mallctlbymib<parameter/></function> functions return 0 on 2148 success; otherwise they return an error value. The functions will fail 2149 if: 2150 <variablelist> 2151 <varlistentry> 2152 <term><errorname>EINVAL</errorname></term> 2153 2154 <listitem><para><parameter>newp</parameter> is not 2155 <constant>NULL</constant>, and <parameter>newlen</parameter> is too 2156 large or too small. Alternatively, <parameter>*oldlenp</parameter> 2157 is too large or too small; in this case as much data as possible 2158 are read despite the error.</para></listitem> 2159 </varlistentry> 2160 <varlistentry> 2161 <term><errorname>ENOMEM</errorname></term> 2162 2163 <listitem><para><parameter>*oldlenp</parameter> is too short to 2164 hold the requested value.</para></listitem> 2165 </varlistentry> 2166 <varlistentry> 2167 <term><errorname>ENOENT</errorname></term> 2168 2169 <listitem><para><parameter>name</parameter> or 2170 <parameter>mib</parameter> specifies an unknown/invalid 2171 value.</para></listitem> 2172 </varlistentry> 2173 <varlistentry> 2174 <term><errorname>EPERM</errorname></term> 2175 2176 <listitem><para>Attempt to read or write void value, or attempt to 2177 write read-only value.</para></listitem> 2178 </varlistentry> 2179 <varlistentry> 2180 <term><errorname>EAGAIN</errorname></term> 2181 2182 <listitem><para>A memory allocation failure 2183 occurred.</para></listitem> 2184 </varlistentry> 2185 <varlistentry> 2186 <term><errorname>EFAULT</errorname></term> 2187 2188 <listitem><para>An interface with side effects failed in some way 2189 not directly related to <function>mallctl*<parameter/></function> 2190 read/write processing.</para></listitem> 2191 </varlistentry> 2192 </variablelist> 2193 </para> 2194 </refsect2> 2195 <refsect2> 2196 <title>Experimental API</title> 2197 <para>The <function>allocm<parameter/></function>, 2198 <function>rallocm<parameter/></function>, 2199 <function>sallocm<parameter/></function>, and 2200 <function>dallocm<parameter/></function> functions return 2201 <constant>ALLOCM_SUCCESS</constant> on success; otherwise they return an 2202 error value. The <function>allocm<parameter/></function> and 2203 <function>rallocm<parameter/></function> functions will fail if: 2204 <variablelist> 2205 <varlistentry> 2206 <term><errorname>ALLOCM_ERR_OOM</errorname></term> 2207 2208 <listitem><para>Out of memory. Insufficient contiguous memory was 2209 available to service the allocation request. The 2210 <function>allocm<parameter/></function> function additionally sets 2211 <parameter>*ptr</parameter> to <constant>NULL</constant>, whereas 2212 the <function>rallocm<parameter/></function> function leaves 2213 <constant>*ptr</constant> unmodified.</para></listitem> 2214 </varlistentry> 2215 </variablelist> 2216 The <function>rallocm<parameter/></function> function will also 2217 fail if: 2218 <variablelist> 2219 <varlistentry> 2220 <term><errorname>ALLOCM_ERR_NOT_MOVED</errorname></term> 2221 2222 <listitem><para><constant>ALLOCM_NO_MOVE</constant> was specified, 2223 but the reallocation request could not be serviced without moving 2224 the object.</para></listitem> 2225 </varlistentry> 2226 </variablelist> 2227 </para> 2228 </refsect2> 2229 </refsect1> 2230 <refsect1 id="environment"> 2231 <title>ENVIRONMENT</title> 2232 <para>The following environment variable affects the execution of the 2233 allocation functions: 2234 <variablelist> 2235 <varlistentry> 2236 <term><envar>MALLOC_CONF</envar></term> 2237 2238 <listitem><para>If the environment variable 2239 <envar>MALLOC_CONF</envar> is set, the characters it contains 2240 will be interpreted as options.</para></listitem> 2241 </varlistentry> 2242 </variablelist> 2243 </para> 2244 </refsect1> 2245 <refsect1 id="examples"> 2246 <title>EXAMPLES</title> 2247 <para>To dump core whenever a problem occurs: 2248 <screen>ln -s 'abort:true' /etc/malloc.conf</screen> 2249 </para> 2250 <para>To specify in the source a chunk size that is 16 MiB: 2251 <programlisting language="C"><![CDATA[ 2252malloc_conf = "lg_chunk:24";]]></programlisting></para> 2253 </refsect1> 2254 <refsect1 id="see_also"> 2255 <title>SEE ALSO</title> 2256 <para><citerefentry><refentrytitle>madvise</refentrytitle> 2257 <manvolnum>2</manvolnum></citerefentry>, 2258 <citerefentry><refentrytitle>mmap</refentrytitle> 2259 <manvolnum>2</manvolnum></citerefentry>, 2260 <citerefentry><refentrytitle>sbrk</refentrytitle> 2261 <manvolnum>2</manvolnum></citerefentry>, 2262 <citerefentry><refentrytitle>alloca</refentrytitle> 2263 <manvolnum>3</manvolnum></citerefentry>, 2264 <citerefentry><refentrytitle>atexit</refentrytitle> 2265 <manvolnum>3</manvolnum></citerefentry>, 2266 <citerefentry><refentrytitle>getpagesize</refentrytitle> 2267 <manvolnum>3</manvolnum></citerefentry></para> 2268 </refsect1> 2269 <refsect1 id="standards"> 2270 <title>STANDARDS</title> 2271 <para>The <function>malloc<parameter/></function>, 2272 <function>calloc<parameter/></function>, 2273 <function>realloc<parameter/></function>, and 2274 <function>free<parameter/></function> functions conform to ISO/IEC 2275 9899:1990 (“ISO C90”).</para> 2276 2277 <para>The <function>posix_memalign<parameter/></function> function conforms 2278 to IEEE Std 1003.1-2001 (“POSIX.1”).</para> 2279 </refsect1> 2280</refentry> 2281