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