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