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>sdallocx</refname> 42 <refname>nallocx</refname> 43 <refname>mallctl</refname> 44 <refname>mallctlnametomib</refname> 45 <refname>mallctlbymib</refname> 46 <refname>malloc_stats_print</refname> 47 <refname>malloc_usable_size</refname> 48 --> 49 <refpurpose>general purpose memory allocation functions</refpurpose> 50 </refnamediv> 51 <refsect1 id="library"> 52 <title>LIBRARY</title> 53 <para>This manual describes jemalloc @jemalloc_version@. More information 54 can be found at the <ulink 55 url="http://jemalloc.net/">jemalloc website</ulink>.</para> 56 </refsect1> 57 <refsynopsisdiv> 58 <title>SYNOPSIS</title> 59 <funcsynopsis> 60 <funcsynopsisinfo>#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>void <function>sdallocx</function></funcdef> 125 <paramdef>void *<parameter>ptr</parameter></paramdef> 126 <paramdef>size_t <parameter>size</parameter></paramdef> 127 <paramdef>int <parameter>flags</parameter></paramdef> 128 </funcprototype> 129 <funcprototype> 130 <funcdef>size_t <function>nallocx</function></funcdef> 131 <paramdef>size_t <parameter>size</parameter></paramdef> 132 <paramdef>int <parameter>flags</parameter></paramdef> 133 </funcprototype> 134 <funcprototype> 135 <funcdef>int <function>mallctl</function></funcdef> 136 <paramdef>const char *<parameter>name</parameter></paramdef> 137 <paramdef>void *<parameter>oldp</parameter></paramdef> 138 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 139 <paramdef>void *<parameter>newp</parameter></paramdef> 140 <paramdef>size_t <parameter>newlen</parameter></paramdef> 141 </funcprototype> 142 <funcprototype> 143 <funcdef>int <function>mallctlnametomib</function></funcdef> 144 <paramdef>const char *<parameter>name</parameter></paramdef> 145 <paramdef>size_t *<parameter>mibp</parameter></paramdef> 146 <paramdef>size_t *<parameter>miblenp</parameter></paramdef> 147 </funcprototype> 148 <funcprototype> 149 <funcdef>int <function>mallctlbymib</function></funcdef> 150 <paramdef>const size_t *<parameter>mib</parameter></paramdef> 151 <paramdef>size_t <parameter>miblen</parameter></paramdef> 152 <paramdef>void *<parameter>oldp</parameter></paramdef> 153 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 154 <paramdef>void *<parameter>newp</parameter></paramdef> 155 <paramdef>size_t <parameter>newlen</parameter></paramdef> 156 </funcprototype> 157 <funcprototype> 158 <funcdef>void <function>malloc_stats_print</function></funcdef> 159 <paramdef>void <parameter>(*write_cb)</parameter> 160 <funcparams>void *, const char *</funcparams> 161 </paramdef> 162 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 163 <paramdef>const char *<parameter>opts</parameter></paramdef> 164 </funcprototype> 165 <funcprototype> 166 <funcdef>size_t <function>malloc_usable_size</function></funcdef> 167 <paramdef>const void *<parameter>ptr</parameter></paramdef> 168 </funcprototype> 169 <funcprototype> 170 <funcdef>void <function>(*malloc_message)</function></funcdef> 171 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 172 <paramdef>const char *<parameter>s</parameter></paramdef> 173 </funcprototype> 174 <para><type>const char *</type><varname>malloc_conf</varname>;</para> 175 </refsect2> 176 </funcsynopsis> 177 </refsynopsisdiv> 178 <refsect1 id="description"> 179 <title>DESCRIPTION</title> 180 <refsect2> 181 <title>Standard API</title> 182 183 <para>The <function>malloc()</function> function allocates 184 <parameter>size</parameter> bytes of uninitialized memory. The allocated 185 space is suitably aligned (after possible pointer coercion) for storage 186 of any type of object.</para> 187 188 <para>The <function>calloc()</function> function allocates 189 space for <parameter>number</parameter> objects, each 190 <parameter>size</parameter> bytes in length. The result is identical to 191 calling <function>malloc()</function> with an argument of 192 <parameter>number</parameter> * <parameter>size</parameter>, with the 193 exception that the allocated memory is explicitly initialized to zero 194 bytes.</para> 195 196 <para>The <function>posix_memalign()</function> function 197 allocates <parameter>size</parameter> bytes of memory such that the 198 allocation's base address is a multiple of 199 <parameter>alignment</parameter>, and returns the allocation in the value 200 pointed to by <parameter>ptr</parameter>. The requested 201 <parameter>alignment</parameter> must be a power of 2 at least as large as 202 <code language="C">sizeof(<type>void *</type>)</code>.</para> 203 204 <para>The <function>aligned_alloc()</function> function 205 allocates <parameter>size</parameter> bytes of memory such that the 206 allocation's base address is a multiple of 207 <parameter>alignment</parameter>. The requested 208 <parameter>alignment</parameter> must be a power of 2. Behavior is 209 undefined if <parameter>size</parameter> is not an integral multiple of 210 <parameter>alignment</parameter>.</para> 211 212 <para>The <function>realloc()</function> function changes the 213 size of the previously allocated memory referenced by 214 <parameter>ptr</parameter> to <parameter>size</parameter> bytes. The 215 contents of the memory are unchanged up to the lesser of the new and old 216 sizes. If the new size is larger, the contents of the newly allocated 217 portion of the memory are undefined. Upon success, the memory referenced 218 by <parameter>ptr</parameter> is freed and a pointer to the newly 219 allocated memory is returned. Note that 220 <function>realloc()</function> may move the memory allocation, 221 resulting in a different return value than <parameter>ptr</parameter>. 222 If <parameter>ptr</parameter> is <constant>NULL</constant>, the 223 <function>realloc()</function> function behaves identically to 224 <function>malloc()</function> for the specified size.</para> 225 226 <para>The <function>free()</function> function causes the 227 allocated memory referenced by <parameter>ptr</parameter> to be made 228 available for future allocations. If <parameter>ptr</parameter> is 229 <constant>NULL</constant>, no action occurs.</para> 230 </refsect2> 231 <refsect2> 232 <title>Non-standard API</title> 233 <para>The <function>mallocx()</function>, 234 <function>rallocx()</function>, 235 <function>xallocx()</function>, 236 <function>sallocx()</function>, 237 <function>dallocx()</function>, 238 <function>sdallocx()</function>, and 239 <function>nallocx()</function> functions all have a 240 <parameter>flags</parameter> argument that can be used to specify 241 options. The functions only check the options that are contextually 242 relevant. Use bitwise or (<code language="C">|</code>) operations to 243 specify one or more of the following: 244 <variablelist> 245 <varlistentry id="MALLOCX_LG_ALIGN"> 246 <term><constant>MALLOCX_LG_ALIGN(<parameter>la</parameter>) 247 </constant></term> 248 249 <listitem><para>Align the memory allocation to start at an address 250 that is a multiple of <code language="C">(1 << 251 <parameter>la</parameter>)</code>. This macro does not validate 252 that <parameter>la</parameter> is within the valid 253 range.</para></listitem> 254 </varlistentry> 255 <varlistentry id="MALLOCX_ALIGN"> 256 <term><constant>MALLOCX_ALIGN(<parameter>a</parameter>) 257 </constant></term> 258 259 <listitem><para>Align the memory allocation to start at an address 260 that is a multiple of <parameter>a</parameter>, where 261 <parameter>a</parameter> is a power of two. This macro does not 262 validate that <parameter>a</parameter> is a power of 2. 263 </para></listitem> 264 </varlistentry> 265 <varlistentry id="MALLOCX_ZERO"> 266 <term><constant>MALLOCX_ZERO</constant></term> 267 268 <listitem><para>Initialize newly allocated memory to contain zero 269 bytes. In the growing reallocation case, the real size prior to 270 reallocation defines the boundary between untouched bytes and those 271 that are initialized to contain zero bytes. If this macro is 272 absent, newly allocated memory is uninitialized.</para></listitem> 273 </varlistentry> 274 <varlistentry id="MALLOCX_TCACHE"> 275 <term><constant>MALLOCX_TCACHE(<parameter>tc</parameter>) 276 </constant></term> 277 278 <listitem><para>Use the thread-specific cache (tcache) specified by 279 the identifier <parameter>tc</parameter>, which must have been 280 acquired via the <link 281 linkend="tcache.create"><mallctl>tcache.create</mallctl></link> 282 mallctl. This macro does not validate that 283 <parameter>tc</parameter> specifies a valid 284 identifier.</para></listitem> 285 </varlistentry> 286 <varlistentry id="MALLOC_TCACHE_NONE"> 287 <term><constant>MALLOCX_TCACHE_NONE</constant></term> 288 289 <listitem><para>Do not use a thread-specific cache (tcache). Unless 290 <constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant> or 291 <constant>MALLOCX_TCACHE_NONE</constant> is specified, an 292 automatically managed tcache will be used under many circumstances. 293 This macro cannot be used in the same <parameter>flags</parameter> 294 argument as 295 <constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant>.</para></listitem> 296 </varlistentry> 297 <varlistentry id="MALLOCX_ARENA"> 298 <term><constant>MALLOCX_ARENA(<parameter>a</parameter>) 299 </constant></term> 300 301 <listitem><para>Use the arena specified by the index 302 <parameter>a</parameter>. This macro has no effect for regions that 303 were allocated via an arena other than the one specified. This 304 macro does not validate that <parameter>a</parameter> specifies an 305 arena index in the valid range.</para></listitem> 306 </varlistentry> 307 </variablelist> 308 </para> 309 310 <para>The <function>mallocx()</function> function allocates at 311 least <parameter>size</parameter> bytes of memory, and returns a pointer 312 to the base address of the allocation. Behavior is undefined if 313 <parameter>size</parameter> is <constant>0</constant>.</para> 314 315 <para>The <function>rallocx()</function> function resizes the 316 allocation at <parameter>ptr</parameter> to be at least 317 <parameter>size</parameter> bytes, and returns a pointer to the base 318 address of the resulting allocation, which may or may not have moved from 319 its original location. Behavior is undefined if 320 <parameter>size</parameter> is <constant>0</constant>.</para> 321 322 <para>The <function>xallocx()</function> function resizes the 323 allocation at <parameter>ptr</parameter> in place to be at least 324 <parameter>size</parameter> bytes, and returns the real size of the 325 allocation. If <parameter>extra</parameter> is non-zero, an attempt is 326 made to resize the allocation to be at least <code 327 language="C">(<parameter>size</parameter> + 328 <parameter>extra</parameter>)</code> bytes, though inability to allocate 329 the extra byte(s) will not by itself result in failure to resize. 330 Behavior is undefined if <parameter>size</parameter> is 331 <constant>0</constant>, or if <code 332 language="C">(<parameter>size</parameter> + <parameter>extra</parameter> 333 > <constant>SIZE_T_MAX</constant>)</code>.</para> 334 335 <para>The <function>sallocx()</function> function returns the 336 real size of the allocation at <parameter>ptr</parameter>.</para> 337 338 <para>The <function>dallocx()</function> function causes the 339 memory referenced by <parameter>ptr</parameter> to be made available for 340 future allocations.</para> 341 342 <para>The <function>sdallocx()</function> function is an 343 extension of <function>dallocx()</function> with a 344 <parameter>size</parameter> parameter to allow the caller to pass in the 345 allocation size as an optimization. The minimum valid input size is the 346 original requested size of the allocation, and the maximum valid input 347 size is the corresponding value returned by 348 <function>nallocx()</function> or 349 <function>sallocx()</function>.</para> 350 351 <para>The <function>nallocx()</function> function allocates no 352 memory, but it performs the same size computation as the 353 <function>mallocx()</function> function, and returns the real 354 size of the allocation that would result from the equivalent 355 <function>mallocx()</function> function call, or 356 <constant>0</constant> if the inputs exceed the maximum supported size 357 class and/or alignment. Behavior is undefined if 358 <parameter>size</parameter> is <constant>0</constant>.</para> 359 360 <para>The <function>mallctl()</function> function provides a 361 general interface for introspecting the memory allocator, as well as 362 setting modifiable parameters and triggering actions. The 363 period-separated <parameter>name</parameter> argument specifies a 364 location in a tree-structured namespace; see the <xref 365 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for 366 documentation on the tree contents. To read a value, pass a pointer via 367 <parameter>oldp</parameter> to adequate space to contain the value, and a 368 pointer to its length via <parameter>oldlenp</parameter>; otherwise pass 369 <constant>NULL</constant> and <constant>NULL</constant>. Similarly, to 370 write a value, pass a pointer to the value via 371 <parameter>newp</parameter>, and its length via 372 <parameter>newlen</parameter>; otherwise pass <constant>NULL</constant> 373 and <constant>0</constant>.</para> 374 375 <para>The <function>mallctlnametomib()</function> function 376 provides a way to avoid repeated name lookups for applications that 377 repeatedly query the same portion of the namespace, by translating a name 378 to a <quote>Management Information Base</quote> (MIB) that can be passed 379 repeatedly to <function>mallctlbymib()</function>. Upon 380 successful return from <function>mallctlnametomib()</function>, 381 <parameter>mibp</parameter> contains an array of 382 <parameter>*miblenp</parameter> integers, where 383 <parameter>*miblenp</parameter> is the lesser of the number of components 384 in <parameter>name</parameter> and the input value of 385 <parameter>*miblenp</parameter>. Thus it is possible to pass a 386 <parameter>*miblenp</parameter> that is smaller than the number of 387 period-separated name components, which results in a partial MIB that can 388 be used as the basis for constructing a complete MIB. For name 389 components that are integers (e.g. the 2 in 390 <link 391 linkend="arenas.bin.i.size"><mallctl>arenas.bin.2.size</mallctl></link>), 392 the corresponding MIB component will always be that integer. Therefore, 393 it is legitimate to construct code like the following: <programlisting 394 language="C"><![CDATA[ 395 unsigned nbins, i; 396 size_t mib[4]; 397 size_t len, miblen; 398 399 len = sizeof(nbins); 400 mallctl("arenas.nbins", &nbins, &len, NULL, 0); 401 402 miblen = 4; 403 mallctlnametomib("arenas.bin.0.size", mib, &miblen); 404 for (i = 0; i < nbins; i++) { 405 size_t bin_size; 406 407 mib[2] = i; 408 len = sizeof(bin_size); 409 mallctlbymib(mib, miblen, (void *)&bin_size, &len, NULL, 0); 410 /* Do something with bin_size... */ 411 }]]></programlisting></para> 412 413 <para>The <function>malloc_stats_print()</function> function writes 414 summary statistics via the <parameter>write_cb</parameter> callback 415 function pointer and <parameter>cbopaque</parameter> data passed to 416 <parameter>write_cb</parameter>, or <function>malloc_message()</function> 417 if <parameter>write_cb</parameter> is <constant>NULL</constant>. The 418 statistics are presented in human-readable form unless <quote>J</quote> is 419 specified as a character within the <parameter>opts</parameter> string, in 420 which case the statistics are presented in <ulink 421 url="http://www.json.org/">JSON format</ulink>. This function can be 422 called repeatedly. General information that never changes during 423 execution can be omitted by specifying <quote>g</quote> as a character 424 within the <parameter>opts</parameter> string. Note that 425 <function>malloc_message()</function> uses the 426 <function>mallctl*()</function> functions internally, so inconsistent 427 statistics can be reported if multiple threads use these functions 428 simultaneously. If <option>--enable-stats</option> is specified during 429 configuration, <quote>m</quote> and <quote>a</quote> can be specified to 430 omit merged arena and per arena statistics, respectively; 431 <quote>b</quote>, <quote>l</quote>, and <quote>h</quote> can be specified 432 to omit per size class statistics for bins, large objects, and huge 433 objects, respectively. Unrecognized characters are silently ignored. 434 Note that thread caching may prevent some statistics from being completely 435 up to date, since extra locking would be required to merge counters that 436 track thread cache operations.</para> 437 438 <para>The <function>malloc_usable_size()</function> function 439 returns the usable size of the allocation pointed to by 440 <parameter>ptr</parameter>. The return value may be larger than the size 441 that was requested during allocation. The 442 <function>malloc_usable_size()</function> function is not a 443 mechanism for in-place <function>realloc()</function>; rather 444 it is provided solely as a tool for introspection purposes. Any 445 discrepancy between the requested allocation size and the size reported 446 by <function>malloc_usable_size()</function> should not be 447 depended on, since such behavior is entirely implementation-dependent. 448 </para> 449 </refsect2> 450 </refsect1> 451 <refsect1 id="tuning"> 452 <title>TUNING</title> 453 <para>Once, when the first call is made to one of the memory allocation 454 routines, the allocator initializes its internals based in part on various 455 options that can be specified at compile- or run-time.</para> 456 457 <para>The string specified via <option>--with-malloc-conf</option>, the 458 string pointed to by the global variable <varname>malloc_conf</varname>, the 459 <quote>name</quote> of the file referenced by the symbolic link named 460 <filename class="symlink">/etc/malloc.conf</filename>, and the value of the 461 environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in 462 that order, from left to right as options. Note that 463 <varname>malloc_conf</varname> may be read before 464 <function>main()</function> is entered, so the declaration of 465 <varname>malloc_conf</varname> should specify an initializer that contains 466 the final value to be read by jemalloc. <option>--with-malloc-conf</option> 467 and <varname>malloc_conf</varname> are compile-time mechanisms, whereas 468 <filename class="symlink">/etc/malloc.conf</filename> and 469 <envar>MALLOC_CONF</envar> can be safely set any time prior to program 470 invocation.</para> 471 472 <para>An options string is a comma-separated list of option:value pairs. 473 There is one key corresponding to each <link 474 linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the <xref 475 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for options 476 documentation). For example, <literal>abort:true,narenas:1</literal> sets 477 the <link linkend="opt.abort"><mallctl>opt.abort</mallctl></link> and <link 478 linkend="opt.narenas"><mallctl>opt.narenas</mallctl></link> options. Some 479 options have boolean values (true/false), others have integer values (base 480 8, 10, or 16, depending on prefix), and yet others have raw string 481 values.</para> 482 </refsect1> 483 <refsect1 id="implementation_notes"> 484 <title>IMPLEMENTATION NOTES</title> 485 <para>Traditionally, allocators have used 486 <citerefentry><refentrytitle>sbrk</refentrytitle> 487 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is 488 suboptimal for several reasons, including race conditions, increased 489 fragmentation, and artificial limitations on maximum usable memory. If 490 <citerefentry><refentrytitle>sbrk</refentrytitle> 491 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 492 system, this allocator uses both 493 <citerefentry><refentrytitle>mmap</refentrytitle> 494 <manvolnum>2</manvolnum></citerefentry> and 495 <citerefentry><refentrytitle>sbrk</refentrytitle> 496 <manvolnum>2</manvolnum></citerefentry>, in that order of preference; 497 otherwise only <citerefentry><refentrytitle>mmap</refentrytitle> 498 <manvolnum>2</manvolnum></citerefentry> is used.</para> 499 500 <para>This allocator uses multiple arenas in order to reduce lock 501 contention for threaded programs on multi-processor systems. This works 502 well with regard to threading scalability, but incurs some costs. There is 503 a small fixed per-arena overhead, and additionally, arenas manage memory 504 completely independently of each other, which means a small fixed increase 505 in overall memory fragmentation. These overheads are not generally an 506 issue, given the number of arenas normally used. Note that using 507 substantially more arenas than the default is not likely to improve 508 performance, mainly due to reduced cache performance. However, it may make 509 sense to reduce the number of arenas if an application does not make much 510 use of the allocation functions.</para> 511 512 <para>In addition to multiple arenas, unless 513 <option>--disable-tcache</option> is specified during configuration, this 514 allocator supports thread-specific caching for small and large objects, in 515 order to make it possible to completely avoid synchronization for most 516 allocation requests. Such caching allows very fast allocation in the 517 common case, but it increases memory usage and fragmentation, since a 518 bounded number of objects can remain allocated in each thread cache.</para> 519 520 <para>Memory is conceptually broken into equal-sized chunks, where the chunk 521 size is a power of two that is greater than the page size. Chunks are 522 always aligned to multiples of the chunk size. This alignment makes it 523 possible to find metadata for user objects very quickly. User objects are 524 broken into three categories according to size: small, large, and huge. 525 Multiple small and large objects can reside within a single chunk, whereas 526 huge objects each have one or more chunks backing them. Each chunk that 527 contains small and/or large objects tracks its contents as runs of 528 contiguous pages (unused, backing a set of small objects, or backing one 529 large object). The combination of chunk alignment and chunk page maps makes 530 it possible to determine all metadata regarding small and large allocations 531 in constant time.</para> 532 533 <para>Small objects are managed in groups by page runs. Each run maintains 534 a bitmap to track which regions are in use. Allocation requests that are no 535 more than half the quantum (8 or 16, depending on architecture) are rounded 536 up to the nearest power of two that is at least <code 537 language="C">sizeof(<type>double</type>)</code>. All other object size 538 classes are multiples of the quantum, spaced such that there are four size 539 classes for each doubling in size, which limits internal fragmentation to 540 approximately 20% for all but the smallest size classes. Small size classes 541 are smaller than four times the page size, large size classes are smaller 542 than the chunk size (see the <link 543 linkend="opt.lg_chunk"><mallctl>opt.lg_chunk</mallctl></link> option), and 544 huge size classes extend from the chunk size up to the largest size class 545 that does not exceed <constant>PTRDIFF_MAX</constant>.</para> 546 547 <para>Allocations are packed tightly together, which can be an issue for 548 multi-threaded applications. If you need to assure that allocations do not 549 suffer from cacheline sharing, round your allocation requests up to the 550 nearest multiple of the cacheline size, or specify cacheline alignment when 551 allocating.</para> 552 553 <para>The <function>realloc()</function>, 554 <function>rallocx()</function>, and 555 <function>xallocx()</function> functions may resize allocations 556 without moving them under limited circumstances. Unlike the 557 <function>*allocx()</function> API, the standard API does not 558 officially round up the usable size of an allocation to the nearest size 559 class, so technically it is necessary to call 560 <function>realloc()</function> to grow e.g. a 9-byte allocation to 561 16 bytes, or shrink a 16-byte allocation to 9 bytes. Growth and shrinkage 562 trivially succeeds in place as long as the pre-size and post-size both round 563 up to the same size class. No other API guarantees are made regarding 564 in-place resizing, but the current implementation also tries to resize large 565 and huge allocations in place, as long as the pre-size and post-size are 566 both large or both huge. In such cases shrinkage always succeeds for large 567 size classes, but for huge size classes the chunk allocator must support 568 splitting (see <link 569 linkend="arena.i.chunk_hooks"><mallctl>arena.<i>.chunk_hooks</mallctl></link>). 570 Growth only succeeds if the trailing memory is currently available, and 571 additionally for huge size classes the chunk allocator must support 572 merging.</para> 573 574 <para>Assuming 2 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 575 64-bit system, the size classes in each category are as shown in <xref 576 linkend="size_classes" xrefstyle="template:Table %n"/>.</para> 577 578 <table xml:id="size_classes" frame="all"> 579 <title>Size classes</title> 580 <tgroup cols="3" colsep="1" rowsep="1"> 581 <colspec colname="c1" align="left"/> 582 <colspec colname="c2" align="right"/> 583 <colspec colname="c3" align="left"/> 584 <thead> 585 <row> 586 <entry>Category</entry> 587 <entry>Spacing</entry> 588 <entry>Size</entry> 589 </row> 590 </thead> 591 <tbody> 592 <row> 593 <entry morerows="8">Small</entry> 594 <entry>lg</entry> 595 <entry>[8]</entry> 596 </row> 597 <row> 598 <entry>16</entry> 599 <entry>[16, 32, 48, 64, 80, 96, 112, 128]</entry> 600 </row> 601 <row> 602 <entry>32</entry> 603 <entry>[160, 192, 224, 256]</entry> 604 </row> 605 <row> 606 <entry>64</entry> 607 <entry>[320, 384, 448, 512]</entry> 608 </row> 609 <row> 610 <entry>128</entry> 611 <entry>[640, 768, 896, 1024]</entry> 612 </row> 613 <row> 614 <entry>256</entry> 615 <entry>[1280, 1536, 1792, 2048]</entry> 616 </row> 617 <row> 618 <entry>512</entry> 619 <entry>[2560, 3072, 3584, 4096]</entry> 620 </row> 621 <row> 622 <entry>1 KiB</entry> 623 <entry>[5 KiB, 6 KiB, 7 KiB, 8 KiB]</entry> 624 </row> 625 <row> 626 <entry>2 KiB</entry> 627 <entry>[10 KiB, 12 KiB, 14 KiB]</entry> 628 </row> 629 <row> 630 <entry morerows="7">Large</entry> 631 <entry>2 KiB</entry> 632 <entry>[16 KiB]</entry> 633 </row> 634 <row> 635 <entry>4 KiB</entry> 636 <entry>[20 KiB, 24 KiB, 28 KiB, 32 KiB]</entry> 637 </row> 638 <row> 639 <entry>8 KiB</entry> 640 <entry>[40 KiB, 48 KiB, 54 KiB, 64 KiB]</entry> 641 </row> 642 <row> 643 <entry>16 KiB</entry> 644 <entry>[80 KiB, 96 KiB, 112 KiB, 128 KiB]</entry> 645 </row> 646 <row> 647 <entry>32 KiB</entry> 648 <entry>[160 KiB, 192 KiB, 224 KiB, 256 KiB]</entry> 649 </row> 650 <row> 651 <entry>64 KiB</entry> 652 <entry>[320 KiB, 384 KiB, 448 KiB, 512 KiB]</entry> 653 </row> 654 <row> 655 <entry>128 KiB</entry> 656 <entry>[640 KiB, 768 KiB, 896 KiB, 1 MiB]</entry> 657 </row> 658 <row> 659 <entry>256 KiB</entry> 660 <entry>[1280 KiB, 1536 KiB, 1792 KiB]</entry> 661 </row> 662 <row> 663 <entry morerows="8">Huge</entry> 664 <entry>256 KiB</entry> 665 <entry>[2 MiB]</entry> 666 </row> 667 <row> 668 <entry>512 KiB</entry> 669 <entry>[2560 KiB, 3 MiB, 3584 KiB, 4 MiB]</entry> 670 </row> 671 <row> 672 <entry>1 MiB</entry> 673 <entry>[5 MiB, 6 MiB, 7 MiB, 8 MiB]</entry> 674 </row> 675 <row> 676 <entry>2 MiB</entry> 677 <entry>[10 MiB, 12 MiB, 14 MiB, 16 MiB]</entry> 678 </row> 679 <row> 680 <entry>4 MiB</entry> 681 <entry>[20 MiB, 24 MiB, 28 MiB, 32 MiB]</entry> 682 </row> 683 <row> 684 <entry>8 MiB</entry> 685 <entry>[40 MiB, 48 MiB, 56 MiB, 64 MiB]</entry> 686 </row> 687 <row> 688 <entry>...</entry> 689 <entry>...</entry> 690 </row> 691 <row> 692 <entry>512 PiB</entry> 693 <entry>[2560 PiB, 3 EiB, 3584 PiB, 4 EiB]</entry> 694 </row> 695 <row> 696 <entry>1 EiB</entry> 697 <entry>[5 EiB, 6 EiB, 7 EiB]</entry> 698 </row> 699 </tbody> 700 </tgroup> 701 </table> 702 </refsect1> 703 <refsect1 id="mallctl_namespace"> 704 <title>MALLCTL NAMESPACE</title> 705 <para>The following names are defined in the namespace accessible via the 706 <function>mallctl*()</function> functions. Value types are 707 specified in parentheses, their readable/writable statuses are encoded as 708 <literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or 709 <literal>--</literal>, and required build configuration flags follow, if 710 any. A name element encoded as <literal><i></literal> or 711 <literal><j></literal> indicates an integer component, where the 712 integer varies from 0 to some upper value that must be determined via 713 introspection. In the case of <mallctl>stats.arenas.<i>.*</mallctl>, 714 <literal><i></literal> equal to <link 715 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> can be 716 used to access the summation of statistics from all arenas. Take special 717 note of the <link linkend="epoch"><mallctl>epoch</mallctl></link> mallctl, 718 which controls refreshing of cached dynamic statistics.</para> 719 720 <variablelist> 721 <varlistentry id="version"> 722 <term> 723 <mallctl>version</mallctl> 724 (<type>const char *</type>) 725 <literal>r-</literal> 726 </term> 727 <listitem><para>Return the jemalloc version string.</para></listitem> 728 </varlistentry> 729 730 <varlistentry id="epoch"> 731 <term> 732 <mallctl>epoch</mallctl> 733 (<type>uint64_t</type>) 734 <literal>rw</literal> 735 </term> 736 <listitem><para>If a value is passed in, refresh the data from which 737 the <function>mallctl*()</function> functions report values, 738 and increment the epoch. Return the current epoch. This is useful for 739 detecting whether another thread caused a refresh.</para></listitem> 740 </varlistentry> 741 742 <varlistentry id="config.cache_oblivious"> 743 <term> 744 <mallctl>config.cache_oblivious</mallctl> 745 (<type>bool</type>) 746 <literal>r-</literal> 747 </term> 748 <listitem><para><option>--enable-cache-oblivious</option> was specified 749 during build configuration.</para></listitem> 750 </varlistentry> 751 752 <varlistentry id="config.debug"> 753 <term> 754 <mallctl>config.debug</mallctl> 755 (<type>bool</type>) 756 <literal>r-</literal> 757 </term> 758 <listitem><para><option>--enable-debug</option> was specified during 759 build configuration.</para></listitem> 760 </varlistentry> 761 762 <varlistentry id="config.fill"> 763 <term> 764 <mallctl>config.fill</mallctl> 765 (<type>bool</type>) 766 <literal>r-</literal> 767 </term> 768 <listitem><para><option>--enable-fill</option> was specified during 769 build configuration.</para></listitem> 770 </varlistentry> 771 772 <varlistentry id="config.lazy_lock"> 773 <term> 774 <mallctl>config.lazy_lock</mallctl> 775 (<type>bool</type>) 776 <literal>r-</literal> 777 </term> 778 <listitem><para><option>--enable-lazy-lock</option> was specified 779 during build configuration.</para></listitem> 780 </varlistentry> 781 782 <varlistentry id="config.malloc_conf"> 783 <term> 784 <mallctl>config.malloc_conf</mallctl> 785 (<type>const char *</type>) 786 <literal>r-</literal> 787 </term> 788 <listitem><para>Embedded configure-time-specified run-time options 789 string, empty unless <option>--with-malloc-conf</option> was specified 790 during build configuration.</para></listitem> 791 </varlistentry> 792 793 <varlistentry id="config.munmap"> 794 <term> 795 <mallctl>config.munmap</mallctl> 796 (<type>bool</type>) 797 <literal>r-</literal> 798 </term> 799 <listitem><para><option>--enable-munmap</option> was specified during 800 build configuration.</para></listitem> 801 </varlistentry> 802 803 <varlistentry id="config.prof"> 804 <term> 805 <mallctl>config.prof</mallctl> 806 (<type>bool</type>) 807 <literal>r-</literal> 808 </term> 809 <listitem><para><option>--enable-prof</option> was specified during 810 build configuration.</para></listitem> 811 </varlistentry> 812 813 <varlistentry id="config.prof_libgcc"> 814 <term> 815 <mallctl>config.prof_libgcc</mallctl> 816 (<type>bool</type>) 817 <literal>r-</literal> 818 </term> 819 <listitem><para><option>--disable-prof-libgcc</option> was not 820 specified during build configuration.</para></listitem> 821 </varlistentry> 822 823 <varlistentry id="config.prof_libunwind"> 824 <term> 825 <mallctl>config.prof_libunwind</mallctl> 826 (<type>bool</type>) 827 <literal>r-</literal> 828 </term> 829 <listitem><para><option>--enable-prof-libunwind</option> was specified 830 during build configuration.</para></listitem> 831 </varlistentry> 832 833 <varlistentry id="config.stats"> 834 <term> 835 <mallctl>config.stats</mallctl> 836 (<type>bool</type>) 837 <literal>r-</literal> 838 </term> 839 <listitem><para><option>--enable-stats</option> was specified during 840 build configuration.</para></listitem> 841 </varlistentry> 842 843 <varlistentry id="config.tcache"> 844 <term> 845 <mallctl>config.tcache</mallctl> 846 (<type>bool</type>) 847 <literal>r-</literal> 848 </term> 849 <listitem><para><option>--disable-tcache</option> was not specified 850 during build configuration.</para></listitem> 851 </varlistentry> 852 853 <varlistentry id="config.tls"> 854 <term> 855 <mallctl>config.tls</mallctl> 856 (<type>bool</type>) 857 <literal>r-</literal> 858 </term> 859 <listitem><para><option>--disable-tls</option> was not specified during 860 build configuration.</para></listitem> 861 </varlistentry> 862 863 <varlistentry id="config.utrace"> 864 <term> 865 <mallctl>config.utrace</mallctl> 866 (<type>bool</type>) 867 <literal>r-</literal> 868 </term> 869 <listitem><para><option>--enable-utrace</option> was specified during 870 build configuration.</para></listitem> 871 </varlistentry> 872 873 <varlistentry id="config.valgrind"> 874 <term> 875 <mallctl>config.valgrind</mallctl> 876 (<type>bool</type>) 877 <literal>r-</literal> 878 </term> 879 <listitem><para><option>--enable-valgrind</option> was specified during 880 build configuration.</para></listitem> 881 </varlistentry> 882 883 <varlistentry id="config.xmalloc"> 884 <term> 885 <mallctl>config.xmalloc</mallctl> 886 (<type>bool</type>) 887 <literal>r-</literal> 888 </term> 889 <listitem><para><option>--enable-xmalloc</option> was specified during 890 build configuration.</para></listitem> 891 </varlistentry> 892 893 <varlistentry id="opt.abort"> 894 <term> 895 <mallctl>opt.abort</mallctl> 896 (<type>bool</type>) 897 <literal>r-</literal> 898 </term> 899 <listitem><para>Abort-on-warning enabled/disabled. If true, most 900 warnings are fatal. The process will call 901 <citerefentry><refentrytitle>abort</refentrytitle> 902 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 903 disabled by default unless <option>--enable-debug</option> is 904 specified during configuration, in which case it is enabled by default. 905 </para></listitem> 906 </varlistentry> 907 908 <varlistentry id="opt.dss"> 909 <term> 910 <mallctl>opt.dss</mallctl> 911 (<type>const char *</type>) 912 <literal>r-</literal> 913 </term> 914 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 915 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 916 related to <citerefentry><refentrytitle>mmap</refentrytitle> 917 <manvolnum>2</manvolnum></citerefentry> allocation. The following 918 settings are supported if 919 <citerefentry><refentrytitle>sbrk</refentrytitle> 920 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 921 system: <quote>disabled</quote>, <quote>primary</quote>, and 922 <quote>secondary</quote>; otherwise only <quote>disabled</quote> is 923 supported. The default is <quote>secondary</quote> if 924 <citerefentry><refentrytitle>sbrk</refentrytitle> 925 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 926 system; <quote>disabled</quote> otherwise. 927 </para></listitem> 928 </varlistentry> 929 930 <varlistentry id="opt.lg_chunk"> 931 <term> 932 <mallctl>opt.lg_chunk</mallctl> 933 (<type>size_t</type>) 934 <literal>r-</literal> 935 </term> 936 <listitem><para>Virtual memory chunk size (log base 2). If a chunk 937 size outside the supported size range is specified, the size is 938 silently clipped to the minimum/maximum supported size. The default 939 chunk size is 2 MiB (2^21). 940 </para></listitem> 941 </varlistentry> 942 943 <varlistentry id="opt.narenas"> 944 <term> 945 <mallctl>opt.narenas</mallctl> 946 (<type>unsigned</type>) 947 <literal>r-</literal> 948 </term> 949 <listitem><para>Maximum number of arenas to use for automatic 950 multiplexing of threads and arenas. The default is four times the 951 number of CPUs, or one if there is a single CPU.</para></listitem> 952 </varlistentry> 953 954 <varlistentry id="opt.purge"> 955 <term> 956 <mallctl>opt.purge</mallctl> 957 (<type>const char *</type>) 958 <literal>r-</literal> 959 </term> 960 <listitem><para>Purge mode is “ratio” (default) or 961 “decay”. See <link 962 linkend="opt.lg_dirty_mult"><mallctl>opt.lg_dirty_mult</mallctl></link> 963 for details of the ratio mode. See <link 964 linkend="opt.decay_time"><mallctl>opt.decay_time</mallctl></link> for 965 details of the decay mode.</para></listitem> 966 </varlistentry> 967 968 <varlistentry id="opt.lg_dirty_mult"> 969 <term> 970 <mallctl>opt.lg_dirty_mult</mallctl> 971 (<type>ssize_t</type>) 972 <literal>r-</literal> 973 </term> 974 <listitem><para>Per-arena minimum ratio (log base 2) of active to dirty 975 pages. Some dirty unused pages may be allowed to accumulate, within 976 the limit set by the ratio (or one chunk worth of dirty pages, 977 whichever is greater), before informing the kernel about some of those 978 pages via <citerefentry><refentrytitle>madvise</refentrytitle> 979 <manvolnum>2</manvolnum></citerefentry> or a similar system call. This 980 provides the kernel with sufficient information to recycle dirty pages 981 if physical memory becomes scarce and the pages remain unused. The 982 default minimum ratio is 8:1 (2^3:1); an option value of -1 will 983 disable dirty page purging. See <link 984 linkend="arenas.lg_dirty_mult"><mallctl>arenas.lg_dirty_mult</mallctl></link> 985 and <link 986 linkend="arena.i.lg_dirty_mult"><mallctl>arena.<i>.lg_dirty_mult</mallctl></link> 987 for related dynamic control options.</para></listitem> 988 </varlistentry> 989 990 <varlistentry id="opt.decay_time"> 991 <term> 992 <mallctl>opt.decay_time</mallctl> 993 (<type>ssize_t</type>) 994 <literal>r-</literal> 995 </term> 996 <listitem><para>Approximate time in seconds from the creation of a set 997 of unused dirty pages until an equivalent set of unused dirty pages is 998 purged and/or reused. The pages are incrementally purged according to a 999 sigmoidal decay curve that starts and ends with zero purge rate. A 1000 decay time of 0 causes all unused dirty pages to be purged immediately 1001 upon creation. A decay time of -1 disables purging. The default decay 1002 time is 10 seconds. See <link 1003 linkend="arenas.decay_time"><mallctl>arenas.decay_time</mallctl></link> 1004 and <link 1005 linkend="arena.i.decay_time"><mallctl>arena.<i>.decay_time</mallctl></link> 1006 for related dynamic control options. 1007 </para></listitem> 1008 </varlistentry> 1009 1010 <varlistentry id="opt.stats_print"> 1011 <term> 1012 <mallctl>opt.stats_print</mallctl> 1013 (<type>bool</type>) 1014 <literal>r-</literal> 1015 </term> 1016 <listitem><para>Enable/disable statistics printing at exit. If 1017 enabled, the <function>malloc_stats_print()</function> 1018 function is called at program exit via an 1019 <citerefentry><refentrytitle>atexit</refentrytitle> 1020 <manvolnum>3</manvolnum></citerefentry> function. If 1021 <option>--enable-stats</option> is specified during configuration, this 1022 has the potential to cause deadlock for a multi-threaded process that 1023 exits while one or more threads are executing in the memory allocation 1024 functions. Furthermore, <function>atexit()</function> may 1025 allocate memory during application initialization and then deadlock 1026 internally when jemalloc in turn calls 1027 <function>atexit()</function>, so this option is not 1028 universally usable (though the application can register its own 1029 <function>atexit()</function> function with equivalent 1030 functionality). Therefore, this option should only be used with care; 1031 it is primarily intended as a performance tuning aid during application 1032 development. This option is disabled by default.</para></listitem> 1033 </varlistentry> 1034 1035 <varlistentry id="opt.junk"> 1036 <term> 1037 <mallctl>opt.junk</mallctl> 1038 (<type>const char *</type>) 1039 <literal>r-</literal> 1040 [<option>--enable-fill</option>] 1041 </term> 1042 <listitem><para>Junk filling. If set to <quote>alloc</quote>, each byte 1043 of uninitialized allocated memory will be initialized to 1044 <literal>0xa5</literal>. If set to <quote>free</quote>, all deallocated 1045 memory will be initialized to <literal>0x5a</literal>. If set to 1046 <quote>true</quote>, both allocated and deallocated memory will be 1047 initialized, and if set to <quote>false</quote>, junk filling be 1048 disabled entirely. This is intended for debugging and will impact 1049 performance negatively. This option is <quote>false</quote> by default 1050 unless <option>--enable-debug</option> is specified during 1051 configuration, in which case it is <quote>true</quote> by default unless 1052 running inside <ulink 1053 url="http://valgrind.org/">Valgrind</ulink>.</para></listitem> 1054 </varlistentry> 1055 1056 <varlistentry id="opt.quarantine"> 1057 <term> 1058 <mallctl>opt.quarantine</mallctl> 1059 (<type>size_t</type>) 1060 <literal>r-</literal> 1061 [<option>--enable-fill</option>] 1062 </term> 1063 <listitem><para>Per thread quarantine size in bytes. If non-zero, each 1064 thread maintains a FIFO object quarantine that stores up to the 1065 specified number of bytes of memory. The quarantined memory is not 1066 freed until it is released from quarantine, though it is immediately 1067 junk-filled if the <link 1068 linkend="opt.junk"><mallctl>opt.junk</mallctl></link> option is 1069 enabled. This feature is of particular use in combination with <ulink 1070 url="http://valgrind.org/">Valgrind</ulink>, which can detect attempts 1071 to access quarantined objects. This is intended for debugging and will 1072 impact performance negatively. The default quarantine size is 0 unless 1073 running inside Valgrind, in which case the default is 16 1074 MiB.</para></listitem> 1075 </varlistentry> 1076 1077 <varlistentry id="opt.redzone"> 1078 <term> 1079 <mallctl>opt.redzone</mallctl> 1080 (<type>bool</type>) 1081 <literal>r-</literal> 1082 [<option>--enable-fill</option>] 1083 </term> 1084 <listitem><para>Redzones enabled/disabled. If enabled, small 1085 allocations have redzones before and after them. Furthermore, if the 1086 <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> option is 1087 enabled, the redzones are checked for corruption during deallocation. 1088 However, the primary intended purpose of this feature is to be used in 1089 combination with <ulink url="http://valgrind.org/">Valgrind</ulink>, 1090 which needs redzones in order to do effective buffer overflow/underflow 1091 detection. This option is intended for debugging and will impact 1092 performance negatively. This option is disabled by 1093 default unless running inside Valgrind.</para></listitem> 1094 </varlistentry> 1095 1096 <varlistentry id="opt.zero"> 1097 <term> 1098 <mallctl>opt.zero</mallctl> 1099 (<type>bool</type>) 1100 <literal>r-</literal> 1101 [<option>--enable-fill</option>] 1102 </term> 1103 <listitem><para>Zero filling enabled/disabled. If enabled, each byte 1104 of uninitialized allocated memory will be initialized to 0. Note that 1105 this initialization only happens once for each byte, so 1106 <function>realloc()</function> and 1107 <function>rallocx()</function> calls do not zero memory that 1108 was previously allocated. This is intended for debugging and will 1109 impact performance negatively. This option is disabled by default. 1110 </para></listitem> 1111 </varlistentry> 1112 1113 <varlistentry id="opt.utrace"> 1114 <term> 1115 <mallctl>opt.utrace</mallctl> 1116 (<type>bool</type>) 1117 <literal>r-</literal> 1118 [<option>--enable-utrace</option>] 1119 </term> 1120 <listitem><para>Allocation tracing based on 1121 <citerefentry><refentrytitle>utrace</refentrytitle> 1122 <manvolnum>2</manvolnum></citerefentry> enabled/disabled. This option 1123 is disabled by default.</para></listitem> 1124 </varlistentry> 1125 1126 <varlistentry id="opt.xmalloc"> 1127 <term> 1128 <mallctl>opt.xmalloc</mallctl> 1129 (<type>bool</type>) 1130 <literal>r-</literal> 1131 [<option>--enable-xmalloc</option>] 1132 </term> 1133 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled, 1134 rather than returning failure for any allocation function, display a 1135 diagnostic message on <constant>STDERR_FILENO</constant> and cause the 1136 program to drop core (using 1137 <citerefentry><refentrytitle>abort</refentrytitle> 1138 <manvolnum>3</manvolnum></citerefentry>). If an application is 1139 designed to depend on this behavior, set the option at compile time by 1140 including the following in the source code: 1141 <programlisting language="C"><![CDATA[ 1142 malloc_conf = "xmalloc:true";]]></programlisting> 1143 This option is disabled by default.</para></listitem> 1144 </varlistentry> 1145 1146 <varlistentry id="opt.tcache"> 1147 <term> 1148 <mallctl>opt.tcache</mallctl> 1149 (<type>bool</type>) 1150 <literal>r-</literal> 1151 [<option>--enable-tcache</option>] 1152 </term> 1153 <listitem><para>Thread-specific caching (tcache) enabled/disabled. When 1154 there are multiple threads, each thread uses a tcache for objects up to 1155 a certain size. Thread-specific caching allows many allocations to be 1156 satisfied without performing any thread synchronization, at the cost of 1157 increased memory use. See the <link 1158 linkend="opt.lg_tcache_max"><mallctl>opt.lg_tcache_max</mallctl></link> 1159 option for related tuning information. This option is enabled by 1160 default unless running inside <ulink 1161 url="http://valgrind.org/">Valgrind</ulink>, in which case it is 1162 forcefully disabled.</para></listitem> 1163 </varlistentry> 1164 1165 <varlistentry id="opt.lg_tcache_max"> 1166 <term> 1167 <mallctl>opt.lg_tcache_max</mallctl> 1168 (<type>size_t</type>) 1169 <literal>r-</literal> 1170 [<option>--enable-tcache</option>] 1171 </term> 1172 <listitem><para>Maximum size class (log base 2) to cache in the 1173 thread-specific cache (tcache). At a minimum, all small size classes 1174 are cached, and at a maximum all large size classes are cached. The 1175 default maximum is 32 KiB (2^15).</para></listitem> 1176 </varlistentry> 1177 1178 <varlistentry id="opt.prof"> 1179 <term> 1180 <mallctl>opt.prof</mallctl> 1181 (<type>bool</type>) 1182 <literal>r-</literal> 1183 [<option>--enable-prof</option>] 1184 </term> 1185 <listitem><para>Memory profiling enabled/disabled. If enabled, profile 1186 memory allocation activity. See the <link 1187 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 1188 option for on-the-fly activation/deactivation. See the <link 1189 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 1190 option for probabilistic sampling control. See the <link 1191 linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> 1192 option for control of cumulative sample reporting. See the <link 1193 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 1194 option for information on interval-triggered profile dumping, the <link 1195 linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link> 1196 option for information on high-water-triggered profile dumping, and the 1197 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link> 1198 option for final profile dumping. Profile output is compatible with 1199 the <command>jeprof</command> command, which is based on the 1200 <command>pprof</command> that is developed as part of the <ulink 1201 url="http://code.google.com/p/gperftools/">gperftools 1202 package</ulink>. See <link linkend="heap_profile_format">HEAP PROFILE 1203 FORMAT</link> for heap profile format documentation.</para></listitem> 1204 </varlistentry> 1205 1206 <varlistentry id="opt.prof_prefix"> 1207 <term> 1208 <mallctl>opt.prof_prefix</mallctl> 1209 (<type>const char *</type>) 1210 <literal>r-</literal> 1211 [<option>--enable-prof</option>] 1212 </term> 1213 <listitem><para>Filename prefix for profile dumps. If the prefix is 1214 set to the empty string, no automatic dumps will occur; this is 1215 primarily useful for disabling the automatic final heap dump (which 1216 also disables leak reporting, if enabled). The default prefix is 1217 <filename>jeprof</filename>.</para></listitem> 1218 </varlistentry> 1219 1220 <varlistentry id="opt.prof_active"> 1221 <term> 1222 <mallctl>opt.prof_active</mallctl> 1223 (<type>bool</type>) 1224 <literal>r-</literal> 1225 [<option>--enable-prof</option>] 1226 </term> 1227 <listitem><para>Profiling activated/deactivated. This is a secondary 1228 control mechanism that makes it possible to start the application with 1229 profiling enabled (see the <link 1230 linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but 1231 inactive, then toggle profiling at any time during program execution 1232 with the <link 1233 linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl. 1234 This option is enabled by default.</para></listitem> 1235 </varlistentry> 1236 1237 <varlistentry id="opt.prof_thread_active_init"> 1238 <term> 1239 <mallctl>opt.prof_thread_active_init</mallctl> 1240 (<type>bool</type>) 1241 <literal>r-</literal> 1242 [<option>--enable-prof</option>] 1243 </term> 1244 <listitem><para>Initial setting for <link 1245 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 1246 in newly created threads. The initial setting for newly created threads 1247 can also be changed during execution via the <link 1248 linkend="prof.thread_active_init"><mallctl>prof.thread_active_init</mallctl></link> 1249 mallctl. This option is enabled by default.</para></listitem> 1250 </varlistentry> 1251 1252 <varlistentry id="opt.lg_prof_sample"> 1253 <term> 1254 <mallctl>opt.lg_prof_sample</mallctl> 1255 (<type>size_t</type>) 1256 <literal>r-</literal> 1257 [<option>--enable-prof</option>] 1258 </term> 1259 <listitem><para>Average interval (log base 2) between allocation 1260 samples, as measured in bytes of allocation activity. Increasing the 1261 sampling interval decreases profile fidelity, but also decreases the 1262 computational overhead. The default sample interval is 512 KiB (2^19 1263 B).</para></listitem> 1264 </varlistentry> 1265 1266 <varlistentry id="opt.prof_accum"> 1267 <term> 1268 <mallctl>opt.prof_accum</mallctl> 1269 (<type>bool</type>) 1270 <literal>r-</literal> 1271 [<option>--enable-prof</option>] 1272 </term> 1273 <listitem><para>Reporting of cumulative object/byte counts in profile 1274 dumps enabled/disabled. If this option is enabled, every unique 1275 backtrace must be stored for the duration of execution. Depending on 1276 the application, this can impose a large memory overhead, and the 1277 cumulative counts are not always of interest. This option is disabled 1278 by default.</para></listitem> 1279 </varlistentry> 1280 1281 <varlistentry id="opt.lg_prof_interval"> 1282 <term> 1283 <mallctl>opt.lg_prof_interval</mallctl> 1284 (<type>ssize_t</type>) 1285 <literal>r-</literal> 1286 [<option>--enable-prof</option>] 1287 </term> 1288 <listitem><para>Average interval (log base 2) between memory profile 1289 dumps, as measured in bytes of allocation activity. The actual 1290 interval between dumps may be sporadic because decentralized allocation 1291 counters are used to avoid synchronization bottlenecks. Profiles are 1292 dumped to files named according to the pattern 1293 <filename><prefix>.<pid>.<seq>.i<iseq>.heap</filename>, 1294 where <literal><prefix></literal> is controlled by the 1295 <link 1296 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1297 option. By default, interval-triggered profile dumping is disabled 1298 (encoded as -1). 1299 </para></listitem> 1300 </varlistentry> 1301 1302 <varlistentry id="opt.prof_gdump"> 1303 <term> 1304 <mallctl>opt.prof_gdump</mallctl> 1305 (<type>bool</type>) 1306 <literal>r-</literal> 1307 [<option>--enable-prof</option>] 1308 </term> 1309 <listitem><para>Set the initial state of <link 1310 linkend="prof.gdump"><mallctl>prof.gdump</mallctl></link>, which when 1311 enabled triggers a memory profile dump every time the total virtual 1312 memory exceeds the previous maximum. This option is disabled by 1313 default.</para></listitem> 1314 </varlistentry> 1315 1316 <varlistentry id="opt.prof_final"> 1317 <term> 1318 <mallctl>opt.prof_final</mallctl> 1319 (<type>bool</type>) 1320 <literal>r-</literal> 1321 [<option>--enable-prof</option>] 1322 </term> 1323 <listitem><para>Use an 1324 <citerefentry><refentrytitle>atexit</refentrytitle> 1325 <manvolnum>3</manvolnum></citerefentry> function to dump final memory 1326 usage to a file named according to the pattern 1327 <filename><prefix>.<pid>.<seq>.f.heap</filename>, 1328 where <literal><prefix></literal> is controlled by the <link 1329 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1330 option. Note that <function>atexit()</function> may allocate 1331 memory during application initialization and then deadlock internally 1332 when jemalloc in turn calls <function>atexit()</function>, so 1333 this option is not universally usable (though the application can 1334 register its own <function>atexit()</function> function with 1335 equivalent functionality). This option is disabled by 1336 default.</para></listitem> 1337 </varlistentry> 1338 1339 <varlistentry id="opt.prof_leak"> 1340 <term> 1341 <mallctl>opt.prof_leak</mallctl> 1342 (<type>bool</type>) 1343 <literal>r-</literal> 1344 [<option>--enable-prof</option>] 1345 </term> 1346 <listitem><para>Leak reporting enabled/disabled. If enabled, use an 1347 <citerefentry><refentrytitle>atexit</refentrytitle> 1348 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks 1349 detected by allocation sampling. See the 1350 <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for 1351 information on analyzing heap profile output. This option is disabled 1352 by default.</para></listitem> 1353 </varlistentry> 1354 1355 <varlistentry id="thread.arena"> 1356 <term> 1357 <mallctl>thread.arena</mallctl> 1358 (<type>unsigned</type>) 1359 <literal>rw</literal> 1360 </term> 1361 <listitem><para>Get or set the arena associated with the calling 1362 thread. If the specified arena was not initialized beforehand (see the 1363 <link 1364 linkend="arenas.initialized"><mallctl>arenas.initialized</mallctl></link> 1365 mallctl), it will be automatically initialized as a side effect of 1366 calling this interface.</para></listitem> 1367 </varlistentry> 1368 1369 <varlistentry id="thread.allocated"> 1370 <term> 1371 <mallctl>thread.allocated</mallctl> 1372 (<type>uint64_t</type>) 1373 <literal>r-</literal> 1374 [<option>--enable-stats</option>] 1375 </term> 1376 <listitem><para>Get the total number of bytes ever allocated by the 1377 calling thread. This counter has the potential to wrap around; it is 1378 up to the application to appropriately interpret the counter in such 1379 cases.</para></listitem> 1380 </varlistentry> 1381 1382 <varlistentry id="thread.allocatedp"> 1383 <term> 1384 <mallctl>thread.allocatedp</mallctl> 1385 (<type>uint64_t *</type>) 1386 <literal>r-</literal> 1387 [<option>--enable-stats</option>] 1388 </term> 1389 <listitem><para>Get a pointer to the the value that is returned by the 1390 <link 1391 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 1392 mallctl. This is useful for avoiding the overhead of repeated 1393 <function>mallctl*()</function> calls.</para></listitem> 1394 </varlistentry> 1395 1396 <varlistentry id="thread.deallocated"> 1397 <term> 1398 <mallctl>thread.deallocated</mallctl> 1399 (<type>uint64_t</type>) 1400 <literal>r-</literal> 1401 [<option>--enable-stats</option>] 1402 </term> 1403 <listitem><para>Get the total number of bytes ever deallocated by the 1404 calling thread. This counter has the potential to wrap around; it is 1405 up to the application to appropriately interpret the counter in such 1406 cases.</para></listitem> 1407 </varlistentry> 1408 1409 <varlistentry id="thread.deallocatedp"> 1410 <term> 1411 <mallctl>thread.deallocatedp</mallctl> 1412 (<type>uint64_t *</type>) 1413 <literal>r-</literal> 1414 [<option>--enable-stats</option>] 1415 </term> 1416 <listitem><para>Get a pointer to the the value that is returned by the 1417 <link 1418 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link> 1419 mallctl. This is useful for avoiding the overhead of repeated 1420 <function>mallctl*()</function> calls.</para></listitem> 1421 </varlistentry> 1422 1423 <varlistentry id="thread.tcache.enabled"> 1424 <term> 1425 <mallctl>thread.tcache.enabled</mallctl> 1426 (<type>bool</type>) 1427 <literal>rw</literal> 1428 [<option>--enable-tcache</option>] 1429 </term> 1430 <listitem><para>Enable/disable calling thread's tcache. The tcache is 1431 implicitly flushed as a side effect of becoming 1432 disabled (see <link 1433 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>). 1434 </para></listitem> 1435 </varlistentry> 1436 1437 <varlistentry id="thread.tcache.flush"> 1438 <term> 1439 <mallctl>thread.tcache.flush</mallctl> 1440 (<type>void</type>) 1441 <literal>--</literal> 1442 [<option>--enable-tcache</option>] 1443 </term> 1444 <listitem><para>Flush calling thread's thread-specific cache (tcache). 1445 This interface releases all cached objects and internal data structures 1446 associated with the calling thread's tcache. Ordinarily, this interface 1447 need not be called, since automatic periodic incremental garbage 1448 collection occurs, and the thread cache is automatically discarded when 1449 a thread exits. However, garbage collection is triggered by allocation 1450 activity, so it is possible for a thread that stops 1451 allocating/deallocating to retain its cache indefinitely, in which case 1452 the developer may find manual flushing useful.</para></listitem> 1453 </varlistentry> 1454 1455 <varlistentry id="thread.prof.name"> 1456 <term> 1457 <mallctl>thread.prof.name</mallctl> 1458 (<type>const char *</type>) 1459 <literal>r-</literal> or 1460 <literal>-w</literal> 1461 [<option>--enable-prof</option>] 1462 </term> 1463 <listitem><para>Get/set the descriptive name associated with the calling 1464 thread in memory profile dumps. An internal copy of the name string is 1465 created, so the input string need not be maintained after this interface 1466 completes execution. The output string of this interface should be 1467 copied for non-ephemeral uses, because multiple implementation details 1468 can cause asynchronous string deallocation. Furthermore, each 1469 invocation of this interface can only read or write; simultaneous 1470 read/write is not supported due to string lifetime limitations. The 1471 name string must be nil-terminated and comprised only of characters in 1472 the sets recognized 1473 by <citerefentry><refentrytitle>isgraph</refentrytitle> 1474 <manvolnum>3</manvolnum></citerefentry> and 1475 <citerefentry><refentrytitle>isblank</refentrytitle> 1476 <manvolnum>3</manvolnum></citerefentry>.</para></listitem> 1477 </varlistentry> 1478 1479 <varlistentry id="thread.prof.active"> 1480 <term> 1481 <mallctl>thread.prof.active</mallctl> 1482 (<type>bool</type>) 1483 <literal>rw</literal> 1484 [<option>--enable-prof</option>] 1485 </term> 1486 <listitem><para>Control whether sampling is currently active for the 1487 calling thread. This is an activation mechanism in addition to <link 1488 linkend="prof.active"><mallctl>prof.active</mallctl></link>; both must 1489 be active for the calling thread to sample. This flag is enabled by 1490 default.</para></listitem> 1491 </varlistentry> 1492 1493 <varlistentry id="tcache.create"> 1494 <term> 1495 <mallctl>tcache.create</mallctl> 1496 (<type>unsigned</type>) 1497 <literal>r-</literal> 1498 [<option>--enable-tcache</option>] 1499 </term> 1500 <listitem><para>Create an explicit thread-specific cache (tcache) and 1501 return an identifier that can be passed to the <link 1502 linkend="MALLOCX_TCACHE"><constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant></link> 1503 macro to explicitly use the specified cache rather than the 1504 automatically managed one that is used by default. Each explicit cache 1505 can be used by only one thread at a time; the application must assure 1506 that this constraint holds. 1507 </para></listitem> 1508 </varlistentry> 1509 1510 <varlistentry id="tcache.flush"> 1511 <term> 1512 <mallctl>tcache.flush</mallctl> 1513 (<type>unsigned</type>) 1514 <literal>-w</literal> 1515 [<option>--enable-tcache</option>] 1516 </term> 1517 <listitem><para>Flush the specified thread-specific cache (tcache). The 1518 same considerations apply to this interface as to <link 1519 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>, 1520 except that the tcache will never be automatically discarded. 1521 </para></listitem> 1522 </varlistentry> 1523 1524 <varlistentry id="tcache.destroy"> 1525 <term> 1526 <mallctl>tcache.destroy</mallctl> 1527 (<type>unsigned</type>) 1528 <literal>-w</literal> 1529 [<option>--enable-tcache</option>] 1530 </term> 1531 <listitem><para>Flush the specified thread-specific cache (tcache) and 1532 make the identifier available for use during a future tcache creation. 1533 </para></listitem> 1534 </varlistentry> 1535 1536 <varlistentry id="arena.i.purge"> 1537 <term> 1538 <mallctl>arena.<i>.purge</mallctl> 1539 (<type>void</type>) 1540 <literal>--</literal> 1541 </term> 1542 <listitem><para>Purge all unused dirty pages for arena <i>, or for 1543 all arenas if <i> equals <link 1544 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link>. 1545 </para></listitem> 1546 </varlistentry> 1547 1548 <varlistentry id="arena.i.decay"> 1549 <term> 1550 <mallctl>arena.<i>.decay</mallctl> 1551 (<type>void</type>) 1552 <literal>--</literal> 1553 </term> 1554 <listitem><para>Trigger decay-based purging of unused dirty pages for 1555 arena <i>, or for all arenas if <i> equals <link 1556 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link>. 1557 The proportion of unused dirty pages to be purged depends on the current 1558 time; see <link 1559 linkend="opt.decay_time"><mallctl>opt.decay_time</mallctl></link> for 1560 details.</para></listitem> 1561 </varlistentry> 1562 1563 <varlistentry id="arena.i.reset"> 1564 <term> 1565 <mallctl>arena.<i>.reset</mallctl> 1566 (<type>void</type>) 1567 <literal>--</literal> 1568 </term> 1569 <listitem><para>Discard all of the arena's extant allocations. This 1570 interface can only be used with arenas created via <link 1571 linkend="arenas.extend"><mallctl>arenas.extend</mallctl></link>. None 1572 of the arena's discarded/cached allocations may accessed afterward. As 1573 part of this requirement, all thread caches which were used to 1574 allocate/deallocate in conjunction with the arena must be flushed 1575 beforehand. This interface cannot be used if running inside Valgrind, 1576 nor if the <link linkend="opt.quarantine">quarantine</link> size is 1577 non-zero.</para></listitem> 1578 </varlistentry> 1579 1580 <varlistentry id="arena.i.dss"> 1581 <term> 1582 <mallctl>arena.<i>.dss</mallctl> 1583 (<type>const char *</type>) 1584 <literal>rw</literal> 1585 </term> 1586 <listitem><para>Set the precedence of dss allocation as related to mmap 1587 allocation for arena <i>, or for all arenas if <i> equals 1588 <link 1589 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link>. See 1590 <link linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for supported 1591 settings.</para></listitem> 1592 </varlistentry> 1593 1594 <varlistentry id="arena.i.lg_dirty_mult"> 1595 <term> 1596 <mallctl>arena.<i>.lg_dirty_mult</mallctl> 1597 (<type>ssize_t</type>) 1598 <literal>rw</literal> 1599 </term> 1600 <listitem><para>Current per-arena minimum ratio (log base 2) of active 1601 to dirty pages for arena <i>. Each time this interface is set and 1602 the ratio is increased, pages are synchronously purged as necessary to 1603 impose the new ratio. See <link 1604 linkend="opt.lg_dirty_mult"><mallctl>opt.lg_dirty_mult</mallctl></link> 1605 for additional information.</para></listitem> 1606 </varlistentry> 1607 1608 <varlistentry id="arena.i.decay_time"> 1609 <term> 1610 <mallctl>arena.<i>.decay_time</mallctl> 1611 (<type>ssize_t</type>) 1612 <literal>rw</literal> 1613 </term> 1614 <listitem><para>Current per-arena approximate time in seconds from the 1615 creation of a set of unused dirty pages until an equivalent set of 1616 unused dirty pages is purged and/or reused. Each time this interface is 1617 set, all currently unused dirty pages are considered to have fully 1618 decayed, which causes immediate purging of all unused dirty pages unless 1619 the decay time is set to -1 (i.e. purging disabled). See <link 1620 linkend="opt.decay_time"><mallctl>opt.decay_time</mallctl></link> for 1621 additional information.</para></listitem> 1622 </varlistentry> 1623 1624 <varlistentry id="arena.i.chunk_hooks"> 1625 <term> 1626 <mallctl>arena.<i>.chunk_hooks</mallctl> 1627 (<type>chunk_hooks_t</type>) 1628 <literal>rw</literal> 1629 </term> 1630 <listitem><para>Get or set the chunk management hook functions for arena 1631 <i>. The functions must be capable of operating on all extant 1632 chunks associated with arena <i>, usually by passing unknown 1633 chunks to the replaced functions. In practice, it is feasible to 1634 control allocation for arenas created via <link 1635 linkend="arenas.extend"><mallctl>arenas.extend</mallctl></link> such 1636 that all chunks originate from an application-supplied chunk allocator 1637 (by setting custom chunk hook functions just after arena creation), but 1638 the automatically created arenas may have already created chunks prior 1639 to the application having an opportunity to take over chunk 1640 allocation.</para> 1641 1642 <programlisting language="C"><![CDATA[ 1643 typedef struct { 1644 chunk_alloc_t *alloc; 1645 chunk_dalloc_t *dalloc; 1646 chunk_commit_t *commit; 1647 chunk_decommit_t *decommit; 1648 chunk_purge_t *purge; 1649 chunk_split_t *split; 1650 chunk_merge_t *merge; 1651 } chunk_hooks_t;]]></programlisting> 1652 <para>The <type>chunk_hooks_t</type> structure comprises function 1653 pointers which are described individually below. jemalloc uses these 1654 functions to manage chunk lifetime, which starts off with allocation of 1655 mapped committed memory, in the simplest case followed by deallocation. 1656 However, there are performance and platform reasons to retain chunks for 1657 later reuse. Cleanup attempts cascade from deallocation to decommit to 1658 purging, which gives the chunk management functions opportunities to 1659 reject the most permanent cleanup operations in favor of less permanent 1660 (and often less costly) operations. The chunk splitting and merging 1661 operations can also be opted out of, but this is mainly intended to 1662 support platforms on which virtual memory mappings provided by the 1663 operating system kernel do not automatically coalesce and split, e.g. 1664 Windows.</para> 1665 1666 <funcsynopsis><funcprototype> 1667 <funcdef>typedef void *<function>(chunk_alloc_t)</function></funcdef> 1668 <paramdef>void *<parameter>chunk</parameter></paramdef> 1669 <paramdef>size_t <parameter>size</parameter></paramdef> 1670 <paramdef>size_t <parameter>alignment</parameter></paramdef> 1671 <paramdef>bool *<parameter>zero</parameter></paramdef> 1672 <paramdef>bool *<parameter>commit</parameter></paramdef> 1673 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1674 </funcprototype></funcsynopsis> 1675 <literallayout></literallayout> 1676 <para>A chunk allocation function conforms to the 1677 <type>chunk_alloc_t</type> type and upon success returns a pointer to 1678 <parameter>size</parameter> bytes of mapped memory on behalf of arena 1679 <parameter>arena_ind</parameter> such that the chunk's base address is a 1680 multiple of <parameter>alignment</parameter>, as well as setting 1681 <parameter>*zero</parameter> to indicate whether the chunk is zeroed and 1682 <parameter>*commit</parameter> to indicate whether the chunk is 1683 committed. Upon error the function returns <constant>NULL</constant> 1684 and leaves <parameter>*zero</parameter> and 1685 <parameter>*commit</parameter> unmodified. The 1686 <parameter>size</parameter> parameter is always a multiple of the chunk 1687 size. The <parameter>alignment</parameter> parameter is always a power 1688 of two at least as large as the chunk size. Zeroing is mandatory if 1689 <parameter>*zero</parameter> is true upon function entry. Committing is 1690 mandatory if <parameter>*commit</parameter> is true upon function entry. 1691 If <parameter>chunk</parameter> is not <constant>NULL</constant>, the 1692 returned pointer must be <parameter>chunk</parameter> on success or 1693 <constant>NULL</constant> on error. Committed memory may be committed 1694 in absolute terms as on a system that does not overcommit, or in 1695 implicit terms as on a system that overcommits and satisfies physical 1696 memory needs on demand via soft page faults. Note that replacing the 1697 default chunk allocation function makes the arena's <link 1698 linkend="arena.i.dss"><mallctl>arena.<i>.dss</mallctl></link> 1699 setting irrelevant.</para> 1700 1701 <funcsynopsis><funcprototype> 1702 <funcdef>typedef bool <function>(chunk_dalloc_t)</function></funcdef> 1703 <paramdef>void *<parameter>chunk</parameter></paramdef> 1704 <paramdef>size_t <parameter>size</parameter></paramdef> 1705 <paramdef>bool <parameter>committed</parameter></paramdef> 1706 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1707 </funcprototype></funcsynopsis> 1708 <literallayout></literallayout> 1709 <para> 1710 A chunk deallocation function conforms to the 1711 <type>chunk_dalloc_t</type> type and deallocates a 1712 <parameter>chunk</parameter> of given <parameter>size</parameter> with 1713 <parameter>committed</parameter>/decommited memory as indicated, on 1714 behalf of arena <parameter>arena_ind</parameter>, returning false upon 1715 success. If the function returns true, this indicates opt-out from 1716 deallocation; the virtual memory mapping associated with the chunk 1717 remains mapped, in the same commit state, and available for future use, 1718 in which case it will be automatically retained for later reuse.</para> 1719 1720 <funcsynopsis><funcprototype> 1721 <funcdef>typedef bool <function>(chunk_commit_t)</function></funcdef> 1722 <paramdef>void *<parameter>chunk</parameter></paramdef> 1723 <paramdef>size_t <parameter>size</parameter></paramdef> 1724 <paramdef>size_t <parameter>offset</parameter></paramdef> 1725 <paramdef>size_t <parameter>length</parameter></paramdef> 1726 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1727 </funcprototype></funcsynopsis> 1728 <literallayout></literallayout> 1729 <para>A chunk commit function conforms to the 1730 <type>chunk_commit_t</type> type and commits zeroed physical memory to 1731 back pages within a <parameter>chunk</parameter> of given 1732 <parameter>size</parameter> at <parameter>offset</parameter> bytes, 1733 extending for <parameter>length</parameter> on behalf of arena 1734 <parameter>arena_ind</parameter>, returning false upon success. 1735 Committed memory may be committed in absolute terms as on a system that 1736 does not overcommit, or in implicit terms as on a system that 1737 overcommits and satisfies physical memory needs on demand via soft page 1738 faults. If the function returns true, this indicates insufficient 1739 physical memory to satisfy the request.</para> 1740 1741 <funcsynopsis><funcprototype> 1742 <funcdef>typedef bool <function>(chunk_decommit_t)</function></funcdef> 1743 <paramdef>void *<parameter>chunk</parameter></paramdef> 1744 <paramdef>size_t <parameter>size</parameter></paramdef> 1745 <paramdef>size_t <parameter>offset</parameter></paramdef> 1746 <paramdef>size_t <parameter>length</parameter></paramdef> 1747 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1748 </funcprototype></funcsynopsis> 1749 <literallayout></literallayout> 1750 <para>A chunk decommit function conforms to the 1751 <type>chunk_decommit_t</type> type and decommits any physical memory 1752 that is backing pages within a <parameter>chunk</parameter> of given 1753 <parameter>size</parameter> at <parameter>offset</parameter> bytes, 1754 extending for <parameter>length</parameter> on behalf of arena 1755 <parameter>arena_ind</parameter>, returning false upon success, in which 1756 case the pages will be committed via the chunk commit function before 1757 being reused. If the function returns true, this indicates opt-out from 1758 decommit; the memory remains committed and available for future use, in 1759 which case it will be automatically retained for later reuse.</para> 1760 1761 <funcsynopsis><funcprototype> 1762 <funcdef>typedef bool <function>(chunk_purge_t)</function></funcdef> 1763 <paramdef>void *<parameter>chunk</parameter></paramdef> 1764 <paramdef>size_t<parameter>size</parameter></paramdef> 1765 <paramdef>size_t <parameter>offset</parameter></paramdef> 1766 <paramdef>size_t <parameter>length</parameter></paramdef> 1767 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1768 </funcprototype></funcsynopsis> 1769 <literallayout></literallayout> 1770 <para>A chunk purge function conforms to the <type>chunk_purge_t</type> 1771 type and optionally discards physical pages within the virtual memory 1772 mapping associated with <parameter>chunk</parameter> of given 1773 <parameter>size</parameter> at <parameter>offset</parameter> bytes, 1774 extending for <parameter>length</parameter> on behalf of arena 1775 <parameter>arena_ind</parameter>, returning false if pages within the 1776 purged virtual memory range will be zero-filled the next time they are 1777 accessed.</para> 1778 1779 <funcsynopsis><funcprototype> 1780 <funcdef>typedef bool <function>(chunk_split_t)</function></funcdef> 1781 <paramdef>void *<parameter>chunk</parameter></paramdef> 1782 <paramdef>size_t <parameter>size</parameter></paramdef> 1783 <paramdef>size_t <parameter>size_a</parameter></paramdef> 1784 <paramdef>size_t <parameter>size_b</parameter></paramdef> 1785 <paramdef>bool <parameter>committed</parameter></paramdef> 1786 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1787 </funcprototype></funcsynopsis> 1788 <literallayout></literallayout> 1789 <para>A chunk split function conforms to the <type>chunk_split_t</type> 1790 type and optionally splits <parameter>chunk</parameter> of given 1791 <parameter>size</parameter> into two adjacent chunks, the first of 1792 <parameter>size_a</parameter> bytes, and the second of 1793 <parameter>size_b</parameter> bytes, operating on 1794 <parameter>committed</parameter>/decommitted memory as indicated, on 1795 behalf of arena <parameter>arena_ind</parameter>, returning false upon 1796 success. If the function returns true, this indicates that the chunk 1797 remains unsplit and therefore should continue to be operated on as a 1798 whole.</para> 1799 1800 <funcsynopsis><funcprototype> 1801 <funcdef>typedef bool <function>(chunk_merge_t)</function></funcdef> 1802 <paramdef>void *<parameter>chunk_a</parameter></paramdef> 1803 <paramdef>size_t <parameter>size_a</parameter></paramdef> 1804 <paramdef>void *<parameter>chunk_b</parameter></paramdef> 1805 <paramdef>size_t <parameter>size_b</parameter></paramdef> 1806 <paramdef>bool <parameter>committed</parameter></paramdef> 1807 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1808 </funcprototype></funcsynopsis> 1809 <literallayout></literallayout> 1810 <para>A chunk merge function conforms to the <type>chunk_merge_t</type> 1811 type and optionally merges adjacent chunks, 1812 <parameter>chunk_a</parameter> of given <parameter>size_a</parameter> 1813 and <parameter>chunk_b</parameter> of given 1814 <parameter>size_b</parameter> into one contiguous chunk, operating on 1815 <parameter>committed</parameter>/decommitted memory as indicated, on 1816 behalf of arena <parameter>arena_ind</parameter>, returning false upon 1817 success. If the function returns true, this indicates that the chunks 1818 remain distinct mappings and therefore should continue to be operated on 1819 independently.</para> 1820 </listitem> 1821 </varlistentry> 1822 1823 <varlistentry id="arenas.narenas"> 1824 <term> 1825 <mallctl>arenas.narenas</mallctl> 1826 (<type>unsigned</type>) 1827 <literal>r-</literal> 1828 </term> 1829 <listitem><para>Current limit on number of arenas.</para></listitem> 1830 </varlistentry> 1831 1832 <varlistentry id="arenas.initialized"> 1833 <term> 1834 <mallctl>arenas.initialized</mallctl> 1835 (<type>bool *</type>) 1836 <literal>r-</literal> 1837 </term> 1838 <listitem><para>An array of <link 1839 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> 1840 booleans. Each boolean indicates whether the corresponding arena is 1841 initialized.</para></listitem> 1842 </varlistentry> 1843 1844 <varlistentry id="arenas.lg_dirty_mult"> 1845 <term> 1846 <mallctl>arenas.lg_dirty_mult</mallctl> 1847 (<type>ssize_t</type>) 1848 <literal>rw</literal> 1849 </term> 1850 <listitem><para>Current default per-arena minimum ratio (log base 2) of 1851 active to dirty pages, used to initialize <link 1852 linkend="arena.i.lg_dirty_mult"><mallctl>arena.<i>.lg_dirty_mult</mallctl></link> 1853 during arena creation. See <link 1854 linkend="opt.lg_dirty_mult"><mallctl>opt.lg_dirty_mult</mallctl></link> 1855 for additional information.</para></listitem> 1856 </varlistentry> 1857 1858 <varlistentry id="arenas.decay_time"> 1859 <term> 1860 <mallctl>arenas.decay_time</mallctl> 1861 (<type>ssize_t</type>) 1862 <literal>rw</literal> 1863 </term> 1864 <listitem><para>Current default per-arena approximate time in seconds 1865 from the creation of a set of unused dirty pages until an equivalent set 1866 of unused dirty pages is purged and/or reused, used to initialize <link 1867 linkend="arena.i.decay_time"><mallctl>arena.<i>.decay_time</mallctl></link> 1868 during arena creation. See <link 1869 linkend="opt.decay_time"><mallctl>opt.decay_time</mallctl></link> for 1870 additional information.</para></listitem> 1871 </varlistentry> 1872 1873 <varlistentry id="arenas.quantum"> 1874 <term> 1875 <mallctl>arenas.quantum</mallctl> 1876 (<type>size_t</type>) 1877 <literal>r-</literal> 1878 </term> 1879 <listitem><para>Quantum size.</para></listitem> 1880 </varlistentry> 1881 1882 <varlistentry id="arenas.page"> 1883 <term> 1884 <mallctl>arenas.page</mallctl> 1885 (<type>size_t</type>) 1886 <literal>r-</literal> 1887 </term> 1888 <listitem><para>Page size.</para></listitem> 1889 </varlistentry> 1890 1891 <varlistentry id="arenas.tcache_max"> 1892 <term> 1893 <mallctl>arenas.tcache_max</mallctl> 1894 (<type>size_t</type>) 1895 <literal>r-</literal> 1896 [<option>--enable-tcache</option>] 1897 </term> 1898 <listitem><para>Maximum thread-cached size class.</para></listitem> 1899 </varlistentry> 1900 1901 <varlistentry id="arenas.nbins"> 1902 <term> 1903 <mallctl>arenas.nbins</mallctl> 1904 (<type>unsigned</type>) 1905 <literal>r-</literal> 1906 </term> 1907 <listitem><para>Number of bin size classes.</para></listitem> 1908 </varlistentry> 1909 1910 <varlistentry id="arenas.nhbins"> 1911 <term> 1912 <mallctl>arenas.nhbins</mallctl> 1913 (<type>unsigned</type>) 1914 <literal>r-</literal> 1915 [<option>--enable-tcache</option>] 1916 </term> 1917 <listitem><para>Total number of thread cache bin size 1918 classes.</para></listitem> 1919 </varlistentry> 1920 1921 <varlistentry id="arenas.bin.i.size"> 1922 <term> 1923 <mallctl>arenas.bin.<i>.size</mallctl> 1924 (<type>size_t</type>) 1925 <literal>r-</literal> 1926 </term> 1927 <listitem><para>Maximum size supported by size class.</para></listitem> 1928 </varlistentry> 1929 1930 <varlistentry id="arenas.bin.i.nregs"> 1931 <term> 1932 <mallctl>arenas.bin.<i>.nregs</mallctl> 1933 (<type>uint32_t</type>) 1934 <literal>r-</literal> 1935 </term> 1936 <listitem><para>Number of regions per page run.</para></listitem> 1937 </varlistentry> 1938 1939 <varlistentry id="arenas.bin.i.run_size"> 1940 <term> 1941 <mallctl>arenas.bin.<i>.run_size</mallctl> 1942 (<type>size_t</type>) 1943 <literal>r-</literal> 1944 </term> 1945 <listitem><para>Number of bytes per page run.</para></listitem> 1946 </varlistentry> 1947 1948 <varlistentry id="arenas.nlruns"> 1949 <term> 1950 <mallctl>arenas.nlruns</mallctl> 1951 (<type>unsigned</type>) 1952 <literal>r-</literal> 1953 </term> 1954 <listitem><para>Total number of large size classes.</para></listitem> 1955 </varlistentry> 1956 1957 <varlistentry id="arenas.lrun.i.size"> 1958 <term> 1959 <mallctl>arenas.lrun.<i>.size</mallctl> 1960 (<type>size_t</type>) 1961 <literal>r-</literal> 1962 </term> 1963 <listitem><para>Maximum size supported by this large size 1964 class.</para></listitem> 1965 </varlistentry> 1966 1967 <varlistentry id="arenas.nhchunks"> 1968 <term> 1969 <mallctl>arenas.nhchunks</mallctl> 1970 (<type>unsigned</type>) 1971 <literal>r-</literal> 1972 </term> 1973 <listitem><para>Total number of huge size classes.</para></listitem> 1974 </varlistentry> 1975 1976 <varlistentry id="arenas.hchunk.i.size"> 1977 <term> 1978 <mallctl>arenas.hchunk.<i>.size</mallctl> 1979 (<type>size_t</type>) 1980 <literal>r-</literal> 1981 </term> 1982 <listitem><para>Maximum size supported by this huge size 1983 class.</para></listitem> 1984 </varlistentry> 1985 1986 <varlistentry id="arenas.extend"> 1987 <term> 1988 <mallctl>arenas.extend</mallctl> 1989 (<type>unsigned</type>) 1990 <literal>r-</literal> 1991 </term> 1992 <listitem><para>Extend the array of arenas by appending a new arena, 1993 and returning the new arena index.</para></listitem> 1994 </varlistentry> 1995 1996 <varlistentry id="prof.thread_active_init"> 1997 <term> 1998 <mallctl>prof.thread_active_init</mallctl> 1999 (<type>bool</type>) 2000 <literal>rw</literal> 2001 [<option>--enable-prof</option>] 2002 </term> 2003 <listitem><para>Control the initial setting for <link 2004 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 2005 in newly created threads. See the <link 2006 linkend="opt.prof_thread_active_init"><mallctl>opt.prof_thread_active_init</mallctl></link> 2007 option for additional information.</para></listitem> 2008 </varlistentry> 2009 2010 <varlistentry id="prof.active"> 2011 <term> 2012 <mallctl>prof.active</mallctl> 2013 (<type>bool</type>) 2014 <literal>rw</literal> 2015 [<option>--enable-prof</option>] 2016 </term> 2017 <listitem><para>Control whether sampling is currently active. See the 2018 <link 2019 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 2020 option for additional information, as well as the interrelated <link 2021 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 2022 mallctl.</para></listitem> 2023 </varlistentry> 2024 2025 <varlistentry id="prof.dump"> 2026 <term> 2027 <mallctl>prof.dump</mallctl> 2028 (<type>const char *</type>) 2029 <literal>-w</literal> 2030 [<option>--enable-prof</option>] 2031 </term> 2032 <listitem><para>Dump a memory profile to the specified file, or if NULL 2033 is specified, to a file according to the pattern 2034 <filename><prefix>.<pid>.<seq>.m<mseq>.heap</filename>, 2035 where <literal><prefix></literal> is controlled by the 2036 <link 2037 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 2038 option.</para></listitem> 2039 </varlistentry> 2040 2041 <varlistentry id="prof.gdump"> 2042 <term> 2043 <mallctl>prof.gdump</mallctl> 2044 (<type>bool</type>) 2045 <literal>rw</literal> 2046 [<option>--enable-prof</option>] 2047 </term> 2048 <listitem><para>When enabled, trigger a memory profile dump every time 2049 the total virtual memory exceeds the previous maximum. Profiles are 2050 dumped to files named according to the pattern 2051 <filename><prefix>.<pid>.<seq>.u<useq>.heap</filename>, 2052 where <literal><prefix></literal> is controlled by the <link 2053 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 2054 option.</para></listitem> 2055 </varlistentry> 2056 2057 <varlistentry id="prof.reset"> 2058 <term> 2059 <mallctl>prof.reset</mallctl> 2060 (<type>size_t</type>) 2061 <literal>-w</literal> 2062 [<option>--enable-prof</option>] 2063 </term> 2064 <listitem><para>Reset all memory profile statistics, and optionally 2065 update the sample rate (see <link 2066 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 2067 and <link 2068 linkend="prof.lg_sample"><mallctl>prof.lg_sample</mallctl></link>). 2069 </para></listitem> 2070 </varlistentry> 2071 2072 <varlistentry id="prof.lg_sample"> 2073 <term> 2074 <mallctl>prof.lg_sample</mallctl> 2075 (<type>size_t</type>) 2076 <literal>r-</literal> 2077 [<option>--enable-prof</option>] 2078 </term> 2079 <listitem><para>Get the current sample rate (see <link 2080 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link>). 2081 </para></listitem> 2082 </varlistentry> 2083 2084 <varlistentry id="prof.interval"> 2085 <term> 2086 <mallctl>prof.interval</mallctl> 2087 (<type>uint64_t</type>) 2088 <literal>r-</literal> 2089 [<option>--enable-prof</option>] 2090 </term> 2091 <listitem><para>Average number of bytes allocated between 2092 interval-based profile dumps. See the 2093 <link 2094 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 2095 option for additional information.</para></listitem> 2096 </varlistentry> 2097 2098 <varlistentry id="stats.cactive"> 2099 <term> 2100 <mallctl>stats.cactive</mallctl> 2101 (<type>size_t *</type>) 2102 <literal>r-</literal> 2103 [<option>--enable-stats</option>] 2104 </term> 2105 <listitem><para>Pointer to a counter that contains an approximate count 2106 of the current number of bytes in active pages. The estimate may be 2107 high, but never low, because each arena rounds up when computing its 2108 contribution to the counter. Note that the <link 2109 linkend="epoch"><mallctl>epoch</mallctl></link> mallctl has no bearing 2110 on this counter. Furthermore, counter consistency is maintained via 2111 atomic operations, so it is necessary to use an atomic operation in 2112 order to guarantee a consistent read when dereferencing the pointer. 2113 </para></listitem> 2114 </varlistentry> 2115 2116 <varlistentry id="stats.allocated"> 2117 <term> 2118 <mallctl>stats.allocated</mallctl> 2119 (<type>size_t</type>) 2120 <literal>r-</literal> 2121 [<option>--enable-stats</option>] 2122 </term> 2123 <listitem><para>Total number of bytes allocated by the 2124 application.</para></listitem> 2125 </varlistentry> 2126 2127 <varlistentry id="stats.active"> 2128 <term> 2129 <mallctl>stats.active</mallctl> 2130 (<type>size_t</type>) 2131 <literal>r-</literal> 2132 [<option>--enable-stats</option>] 2133 </term> 2134 <listitem><para>Total number of bytes in active pages allocated by the 2135 application. This is a multiple of the page size, and greater than or 2136 equal to <link 2137 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>. 2138 This does not include <link linkend="stats.arenas.i.pdirty"> 2139 <mallctl>stats.arenas.<i>.pdirty</mallctl></link>, nor pages 2140 entirely devoted to allocator metadata.</para></listitem> 2141 </varlistentry> 2142 2143 <varlistentry id="stats.metadata"> 2144 <term> 2145 <mallctl>stats.metadata</mallctl> 2146 (<type>size_t</type>) 2147 <literal>r-</literal> 2148 [<option>--enable-stats</option>] 2149 </term> 2150 <listitem><para>Total number of bytes dedicated to metadata, which 2151 comprise base allocations used for bootstrap-sensitive internal 2152 allocator data structures, arena chunk headers (see <link 2153 linkend="stats.arenas.i.metadata.mapped"><mallctl>stats.arenas.<i>.metadata.mapped</mallctl></link>), 2154 and internal allocations (see <link 2155 linkend="stats.arenas.i.metadata.allocated"><mallctl>stats.arenas.<i>.metadata.allocated</mallctl></link>).</para></listitem> 2156 </varlistentry> 2157 2158 <varlistentry id="stats.resident"> 2159 <term> 2160 <mallctl>stats.resident</mallctl> 2161 (<type>size_t</type>) 2162 <literal>r-</literal> 2163 [<option>--enable-stats</option>] 2164 </term> 2165 <listitem><para>Maximum number of bytes in physically resident data 2166 pages mapped by the allocator, comprising all pages dedicated to 2167 allocator metadata, pages backing active allocations, and unused dirty 2168 pages. This is a maximum rather than precise because pages may not 2169 actually be physically resident if they correspond to demand-zeroed 2170 virtual memory that has not yet been touched. This is a multiple of the 2171 page size, and is larger than <link 2172 linkend="stats.active"><mallctl>stats.active</mallctl></link>.</para></listitem> 2173 </varlistentry> 2174 2175 <varlistentry id="stats.mapped"> 2176 <term> 2177 <mallctl>stats.mapped</mallctl> 2178 (<type>size_t</type>) 2179 <literal>r-</literal> 2180 [<option>--enable-stats</option>] 2181 </term> 2182 <listitem><para>Total number of bytes in active chunks mapped by the 2183 allocator. This is a multiple of the chunk size, and is larger than 2184 <link linkend="stats.active"><mallctl>stats.active</mallctl></link>. 2185 This does not include inactive chunks, even those that contain unused 2186 dirty pages, which means that there is no strict ordering between this 2187 and <link 2188 linkend="stats.resident"><mallctl>stats.resident</mallctl></link>.</para></listitem> 2189 </varlistentry> 2190 2191 <varlistentry id="stats.retained"> 2192 <term> 2193 <mallctl>stats.retained</mallctl> 2194 (<type>size_t</type>) 2195 <literal>r-</literal> 2196 [<option>--enable-stats</option>] 2197 </term> 2198 <listitem><para>Total number of bytes in virtual memory mappings that 2199 were retained rather than being returned to the operating system via 2200 e.g. <citerefentry><refentrytitle>munmap</refentrytitle> 2201 <manvolnum>2</manvolnum></citerefentry>. Retained virtual memory is 2202 typically untouched, decommitted, or purged, so it has no strongly 2203 associated physical memory (see <link 2204 linkend="arena.i.chunk_hooks">chunk hooks</link> for details). Retained 2205 memory is excluded from mapped memory statistics, e.g. <link 2206 linkend="stats.mapped"><mallctl>stats.mapped</mallctl></link>. 2207 </para></listitem> 2208 </varlistentry> 2209 2210 <varlistentry id="stats.arenas.i.dss"> 2211 <term> 2212 <mallctl>stats.arenas.<i>.dss</mallctl> 2213 (<type>const char *</type>) 2214 <literal>r-</literal> 2215 </term> 2216 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 2217 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 2218 related to <citerefentry><refentrytitle>mmap</refentrytitle> 2219 <manvolnum>2</manvolnum></citerefentry> allocation. See <link 2220 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for details. 2221 </para></listitem> 2222 </varlistentry> 2223 2224 <varlistentry id="stats.arenas.i.lg_dirty_mult"> 2225 <term> 2226 <mallctl>stats.arenas.<i>.lg_dirty_mult</mallctl> 2227 (<type>ssize_t</type>) 2228 <literal>r-</literal> 2229 </term> 2230 <listitem><para>Minimum ratio (log base 2) of active to dirty pages. 2231 See <link 2232 linkend="opt.lg_dirty_mult"><mallctl>opt.lg_dirty_mult</mallctl></link> 2233 for details.</para></listitem> 2234 </varlistentry> 2235 2236 <varlistentry id="stats.arenas.i.decay_time"> 2237 <term> 2238 <mallctl>stats.arenas.<i>.decay_time</mallctl> 2239 (<type>ssize_t</type>) 2240 <literal>r-</literal> 2241 </term> 2242 <listitem><para>Approximate time in seconds from the creation of a set 2243 of unused dirty pages until an equivalent set of unused dirty pages is 2244 purged and/or reused. See <link 2245 linkend="opt.decay_time"><mallctl>opt.decay_time</mallctl></link> 2246 for details.</para></listitem> 2247 </varlistentry> 2248 2249 <varlistentry id="stats.arenas.i.nthreads"> 2250 <term> 2251 <mallctl>stats.arenas.<i>.nthreads</mallctl> 2252 (<type>unsigned</type>) 2253 <literal>r-</literal> 2254 </term> 2255 <listitem><para>Number of threads currently assigned to 2256 arena.</para></listitem> 2257 </varlistentry> 2258 2259 <varlistentry id="stats.arenas.i.pactive"> 2260 <term> 2261 <mallctl>stats.arenas.<i>.pactive</mallctl> 2262 (<type>size_t</type>) 2263 <literal>r-</literal> 2264 </term> 2265 <listitem><para>Number of pages in active runs.</para></listitem> 2266 </varlistentry> 2267 2268 <varlistentry id="stats.arenas.i.pdirty"> 2269 <term> 2270 <mallctl>stats.arenas.<i>.pdirty</mallctl> 2271 (<type>size_t</type>) 2272 <literal>r-</literal> 2273 </term> 2274 <listitem><para>Number of pages within unused runs that are potentially 2275 dirty, and for which <function>madvise<parameter>...</parameter> 2276 <parameter><constant>MADV_DONTNEED</constant></parameter></function> or 2277 similar has not been called.</para></listitem> 2278 </varlistentry> 2279 2280 <varlistentry id="stats.arenas.i.mapped"> 2281 <term> 2282 <mallctl>stats.arenas.<i>.mapped</mallctl> 2283 (<type>size_t</type>) 2284 <literal>r-</literal> 2285 [<option>--enable-stats</option>] 2286 </term> 2287 <listitem><para>Number of mapped bytes.</para></listitem> 2288 </varlistentry> 2289 2290 <varlistentry id="stats.arenas.i.retained"> 2291 <term> 2292 <mallctl>stats.arenas.<i>.retained</mallctl> 2293 (<type>size_t</type>) 2294 <literal>r-</literal> 2295 [<option>--enable-stats</option>] 2296 </term> 2297 <listitem><para>Number of retained bytes. See <link 2298 linkend="stats.retained"><mallctl>stats.retained</mallctl></link> for 2299 details.</para></listitem> 2300 </varlistentry> 2301 2302 <varlistentry id="stats.arenas.i.metadata.mapped"> 2303 <term> 2304 <mallctl>stats.arenas.<i>.metadata.mapped</mallctl> 2305 (<type>size_t</type>) 2306 <literal>r-</literal> 2307 [<option>--enable-stats</option>] 2308 </term> 2309 <listitem><para>Number of mapped bytes in arena chunk headers, which 2310 track the states of the non-metadata pages.</para></listitem> 2311 </varlistentry> 2312 2313 <varlistentry id="stats.arenas.i.metadata.allocated"> 2314 <term> 2315 <mallctl>stats.arenas.<i>.metadata.allocated</mallctl> 2316 (<type>size_t</type>) 2317 <literal>r-</literal> 2318 [<option>--enable-stats</option>] 2319 </term> 2320 <listitem><para>Number of bytes dedicated to internal allocations. 2321 Internal allocations differ from application-originated allocations in 2322 that they are for internal use, and that they are omitted from heap 2323 profiles. This statistic is reported separately from <link 2324 linkend="stats.metadata"><mallctl>stats.metadata</mallctl></link> and 2325 <link 2326 linkend="stats.arenas.i.metadata.mapped"><mallctl>stats.arenas.<i>.metadata.mapped</mallctl></link> 2327 because it overlaps with e.g. the <link 2328 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link> and 2329 <link linkend="stats.active"><mallctl>stats.active</mallctl></link> 2330 statistics, whereas the other metadata statistics do 2331 not.</para></listitem> 2332 </varlistentry> 2333 2334 <varlistentry id="stats.arenas.i.npurge"> 2335 <term> 2336 <mallctl>stats.arenas.<i>.npurge</mallctl> 2337 (<type>uint64_t</type>) 2338 <literal>r-</literal> 2339 [<option>--enable-stats</option>] 2340 </term> 2341 <listitem><para>Number of dirty page purge sweeps performed. 2342 </para></listitem> 2343 </varlistentry> 2344 2345 <varlistentry id="stats.arenas.i.nmadvise"> 2346 <term> 2347 <mallctl>stats.arenas.<i>.nmadvise</mallctl> 2348 (<type>uint64_t</type>) 2349 <literal>r-</literal> 2350 [<option>--enable-stats</option>] 2351 </term> 2352 <listitem><para>Number of <function>madvise<parameter>...</parameter> 2353 <parameter><constant>MADV_DONTNEED</constant></parameter></function> or 2354 similar calls made to purge dirty pages.</para></listitem> 2355 </varlistentry> 2356 2357 <varlistentry id="stats.arenas.i.purged"> 2358 <term> 2359 <mallctl>stats.arenas.<i>.purged</mallctl> 2360 (<type>uint64_t</type>) 2361 <literal>r-</literal> 2362 [<option>--enable-stats</option>] 2363 </term> 2364 <listitem><para>Number of pages purged.</para></listitem> 2365 </varlistentry> 2366 2367 <varlistentry id="stats.arenas.i.small.allocated"> 2368 <term> 2369 <mallctl>stats.arenas.<i>.small.allocated</mallctl> 2370 (<type>size_t</type>) 2371 <literal>r-</literal> 2372 [<option>--enable-stats</option>] 2373 </term> 2374 <listitem><para>Number of bytes currently allocated by small objects. 2375 </para></listitem> 2376 </varlistentry> 2377 2378 <varlistentry id="stats.arenas.i.small.nmalloc"> 2379 <term> 2380 <mallctl>stats.arenas.<i>.small.nmalloc</mallctl> 2381 (<type>uint64_t</type>) 2382 <literal>r-</literal> 2383 [<option>--enable-stats</option>] 2384 </term> 2385 <listitem><para>Cumulative number of allocation requests served by 2386 small bins.</para></listitem> 2387 </varlistentry> 2388 2389 <varlistentry id="stats.arenas.i.small.ndalloc"> 2390 <term> 2391 <mallctl>stats.arenas.<i>.small.ndalloc</mallctl> 2392 (<type>uint64_t</type>) 2393 <literal>r-</literal> 2394 [<option>--enable-stats</option>] 2395 </term> 2396 <listitem><para>Cumulative number of small objects returned to bins. 2397 </para></listitem> 2398 </varlistentry> 2399 2400 <varlistentry id="stats.arenas.i.small.nrequests"> 2401 <term> 2402 <mallctl>stats.arenas.<i>.small.nrequests</mallctl> 2403 (<type>uint64_t</type>) 2404 <literal>r-</literal> 2405 [<option>--enable-stats</option>] 2406 </term> 2407 <listitem><para>Cumulative number of small allocation requests. 2408 </para></listitem> 2409 </varlistentry> 2410 2411 <varlistentry id="stats.arenas.i.large.allocated"> 2412 <term> 2413 <mallctl>stats.arenas.<i>.large.allocated</mallctl> 2414 (<type>size_t</type>) 2415 <literal>r-</literal> 2416 [<option>--enable-stats</option>] 2417 </term> 2418 <listitem><para>Number of bytes currently allocated by large objects. 2419 </para></listitem> 2420 </varlistentry> 2421 2422 <varlistentry id="stats.arenas.i.large.nmalloc"> 2423 <term> 2424 <mallctl>stats.arenas.<i>.large.nmalloc</mallctl> 2425 (<type>uint64_t</type>) 2426 <literal>r-</literal> 2427 [<option>--enable-stats</option>] 2428 </term> 2429 <listitem><para>Cumulative number of large allocation requests served 2430 directly by the arena.</para></listitem> 2431 </varlistentry> 2432 2433 <varlistentry id="stats.arenas.i.large.ndalloc"> 2434 <term> 2435 <mallctl>stats.arenas.<i>.large.ndalloc</mallctl> 2436 (<type>uint64_t</type>) 2437 <literal>r-</literal> 2438 [<option>--enable-stats</option>] 2439 </term> 2440 <listitem><para>Cumulative number of large deallocation requests served 2441 directly by the arena.</para></listitem> 2442 </varlistentry> 2443 2444 <varlistentry id="stats.arenas.i.large.nrequests"> 2445 <term> 2446 <mallctl>stats.arenas.<i>.large.nrequests</mallctl> 2447 (<type>uint64_t</type>) 2448 <literal>r-</literal> 2449 [<option>--enable-stats</option>] 2450 </term> 2451 <listitem><para>Cumulative number of large allocation requests. 2452 </para></listitem> 2453 </varlistentry> 2454 2455 <varlistentry id="stats.arenas.i.huge.allocated"> 2456 <term> 2457 <mallctl>stats.arenas.<i>.huge.allocated</mallctl> 2458 (<type>size_t</type>) 2459 <literal>r-</literal> 2460 [<option>--enable-stats</option>] 2461 </term> 2462 <listitem><para>Number of bytes currently allocated by huge objects. 2463 </para></listitem> 2464 </varlistentry> 2465 2466 <varlistentry id="stats.arenas.i.huge.nmalloc"> 2467 <term> 2468 <mallctl>stats.arenas.<i>.huge.nmalloc</mallctl> 2469 (<type>uint64_t</type>) 2470 <literal>r-</literal> 2471 [<option>--enable-stats</option>] 2472 </term> 2473 <listitem><para>Cumulative number of huge allocation requests served 2474 directly by the arena.</para></listitem> 2475 </varlistentry> 2476 2477 <varlistentry id="stats.arenas.i.huge.ndalloc"> 2478 <term> 2479 <mallctl>stats.arenas.<i>.huge.ndalloc</mallctl> 2480 (<type>uint64_t</type>) 2481 <literal>r-</literal> 2482 [<option>--enable-stats</option>] 2483 </term> 2484 <listitem><para>Cumulative number of huge deallocation requests served 2485 directly by the arena.</para></listitem> 2486 </varlistentry> 2487 2488 <varlistentry id="stats.arenas.i.huge.nrequests"> 2489 <term> 2490 <mallctl>stats.arenas.<i>.huge.nrequests</mallctl> 2491 (<type>uint64_t</type>) 2492 <literal>r-</literal> 2493 [<option>--enable-stats</option>] 2494 </term> 2495 <listitem><para>Cumulative number of huge allocation requests. 2496 </para></listitem> 2497 </varlistentry> 2498 2499 <varlistentry id="stats.arenas.i.bins.j.nmalloc"> 2500 <term> 2501 <mallctl>stats.arenas.<i>.bins.<j>.nmalloc</mallctl> 2502 (<type>uint64_t</type>) 2503 <literal>r-</literal> 2504 [<option>--enable-stats</option>] 2505 </term> 2506 <listitem><para>Cumulative number of allocations served by bin. 2507 </para></listitem> 2508 </varlistentry> 2509 2510 <varlistentry id="stats.arenas.i.bins.j.ndalloc"> 2511 <term> 2512 <mallctl>stats.arenas.<i>.bins.<j>.ndalloc</mallctl> 2513 (<type>uint64_t</type>) 2514 <literal>r-</literal> 2515 [<option>--enable-stats</option>] 2516 </term> 2517 <listitem><para>Cumulative number of allocations returned to bin. 2518 </para></listitem> 2519 </varlistentry> 2520 2521 <varlistentry id="stats.arenas.i.bins.j.nrequests"> 2522 <term> 2523 <mallctl>stats.arenas.<i>.bins.<j>.nrequests</mallctl> 2524 (<type>uint64_t</type>) 2525 <literal>r-</literal> 2526 [<option>--enable-stats</option>] 2527 </term> 2528 <listitem><para>Cumulative number of allocation 2529 requests.</para></listitem> 2530 </varlistentry> 2531 2532 <varlistentry id="stats.arenas.i.bins.j.curregs"> 2533 <term> 2534 <mallctl>stats.arenas.<i>.bins.<j>.curregs</mallctl> 2535 (<type>size_t</type>) 2536 <literal>r-</literal> 2537 [<option>--enable-stats</option>] 2538 </term> 2539 <listitem><para>Current number of regions for this size 2540 class.</para></listitem> 2541 </varlistentry> 2542 2543 <varlistentry id="stats.arenas.i.bins.j.nfills"> 2544 <term> 2545 <mallctl>stats.arenas.<i>.bins.<j>.nfills</mallctl> 2546 (<type>uint64_t</type>) 2547 <literal>r-</literal> 2548 [<option>--enable-stats</option> <option>--enable-tcache</option>] 2549 </term> 2550 <listitem><para>Cumulative number of tcache fills.</para></listitem> 2551 </varlistentry> 2552 2553 <varlistentry id="stats.arenas.i.bins.j.nflushes"> 2554 <term> 2555 <mallctl>stats.arenas.<i>.bins.<j>.nflushes</mallctl> 2556 (<type>uint64_t</type>) 2557 <literal>r-</literal> 2558 [<option>--enable-stats</option> <option>--enable-tcache</option>] 2559 </term> 2560 <listitem><para>Cumulative number of tcache flushes.</para></listitem> 2561 </varlistentry> 2562 2563 <varlistentry id="stats.arenas.i.bins.j.nruns"> 2564 <term> 2565 <mallctl>stats.arenas.<i>.bins.<j>.nruns</mallctl> 2566 (<type>uint64_t</type>) 2567 <literal>r-</literal> 2568 [<option>--enable-stats</option>] 2569 </term> 2570 <listitem><para>Cumulative number of runs created.</para></listitem> 2571 </varlistentry> 2572 2573 <varlistentry id="stats.arenas.i.bins.j.nreruns"> 2574 <term> 2575 <mallctl>stats.arenas.<i>.bins.<j>.nreruns</mallctl> 2576 (<type>uint64_t</type>) 2577 <literal>r-</literal> 2578 [<option>--enable-stats</option>] 2579 </term> 2580 <listitem><para>Cumulative number of times the current run from which 2581 to allocate changed.</para></listitem> 2582 </varlistentry> 2583 2584 <varlistentry id="stats.arenas.i.bins.j.curruns"> 2585 <term> 2586 <mallctl>stats.arenas.<i>.bins.<j>.curruns</mallctl> 2587 (<type>size_t</type>) 2588 <literal>r-</literal> 2589 [<option>--enable-stats</option>] 2590 </term> 2591 <listitem><para>Current number of runs.</para></listitem> 2592 </varlistentry> 2593 2594 <varlistentry id="stats.arenas.i.lruns.j.nmalloc"> 2595 <term> 2596 <mallctl>stats.arenas.<i>.lruns.<j>.nmalloc</mallctl> 2597 (<type>uint64_t</type>) 2598 <literal>r-</literal> 2599 [<option>--enable-stats</option>] 2600 </term> 2601 <listitem><para>Cumulative number of allocation requests for this size 2602 class served directly by the arena.</para></listitem> 2603 </varlistentry> 2604 2605 <varlistentry id="stats.arenas.i.lruns.j.ndalloc"> 2606 <term> 2607 <mallctl>stats.arenas.<i>.lruns.<j>.ndalloc</mallctl> 2608 (<type>uint64_t</type>) 2609 <literal>r-</literal> 2610 [<option>--enable-stats</option>] 2611 </term> 2612 <listitem><para>Cumulative number of deallocation requests for this 2613 size class served directly by the arena.</para></listitem> 2614 </varlistentry> 2615 2616 <varlistentry id="stats.arenas.i.lruns.j.nrequests"> 2617 <term> 2618 <mallctl>stats.arenas.<i>.lruns.<j>.nrequests</mallctl> 2619 (<type>uint64_t</type>) 2620 <literal>r-</literal> 2621 [<option>--enable-stats</option>] 2622 </term> 2623 <listitem><para>Cumulative number of allocation requests for this size 2624 class.</para></listitem> 2625 </varlistentry> 2626 2627 <varlistentry id="stats.arenas.i.lruns.j.curruns"> 2628 <term> 2629 <mallctl>stats.arenas.<i>.lruns.<j>.curruns</mallctl> 2630 (<type>size_t</type>) 2631 <literal>r-</literal> 2632 [<option>--enable-stats</option>] 2633 </term> 2634 <listitem><para>Current number of runs for this size class. 2635 </para></listitem> 2636 </varlistentry> 2637 2638 <varlistentry id="stats.arenas.i.hchunks.j.nmalloc"> 2639 <term> 2640 <mallctl>stats.arenas.<i>.hchunks.<j>.nmalloc</mallctl> 2641 (<type>uint64_t</type>) 2642 <literal>r-</literal> 2643 [<option>--enable-stats</option>] 2644 </term> 2645 <listitem><para>Cumulative number of allocation requests for this size 2646 class served directly by the arena.</para></listitem> 2647 </varlistentry> 2648 2649 <varlistentry id="stats.arenas.i.hchunks.j.ndalloc"> 2650 <term> 2651 <mallctl>stats.arenas.<i>.hchunks.<j>.ndalloc</mallctl> 2652 (<type>uint64_t</type>) 2653 <literal>r-</literal> 2654 [<option>--enable-stats</option>] 2655 </term> 2656 <listitem><para>Cumulative number of deallocation requests for this 2657 size class served directly by the arena.</para></listitem> 2658 </varlistentry> 2659 2660 <varlistentry id="stats.arenas.i.hchunks.j.nrequests"> 2661 <term> 2662 <mallctl>stats.arenas.<i>.hchunks.<j>.nrequests</mallctl> 2663 (<type>uint64_t</type>) 2664 <literal>r-</literal> 2665 [<option>--enable-stats</option>] 2666 </term> 2667 <listitem><para>Cumulative number of allocation requests for this size 2668 class.</para></listitem> 2669 </varlistentry> 2670 2671 <varlistentry id="stats.arenas.i.hchunks.j.curhchunks"> 2672 <term> 2673 <mallctl>stats.arenas.<i>.hchunks.<j>.curhchunks</mallctl> 2674 (<type>size_t</type>) 2675 <literal>r-</literal> 2676 [<option>--enable-stats</option>] 2677 </term> 2678 <listitem><para>Current number of huge allocations for this size class. 2679 </para></listitem> 2680 </varlistentry> 2681 </variablelist> 2682 </refsect1> 2683 <refsect1 id="heap_profile_format"> 2684 <title>HEAP PROFILE FORMAT</title> 2685 <para>Although the heap profiling functionality was originally designed to 2686 be compatible with the 2687 <command>pprof</command> command that is developed as part of the <ulink 2688 url="http://code.google.com/p/gperftools/">gperftools 2689 package</ulink>, the addition of per thread heap profiling functionality 2690 required a different heap profile format. The <command>jeprof</command> 2691 command is derived from <command>pprof</command>, with enhancements to 2692 support the heap profile format described here.</para> 2693 2694 <para>In the following hypothetical heap profile, <constant>[...]</constant> 2695 indicates elision for the sake of compactness. <programlisting><![CDATA[ 2696 heap_v2/524288 2697 t*: 28106: 56637512 [0: 0] 2698 [...] 2699 t3: 352: 16777344 [0: 0] 2700 [...] 2701 t99: 17754: 29341640 [0: 0] 2702 [...] 2703 @ 0x5f86da8 0x5f5a1dc [...] 0x29e4d4e 0xa200316 0xabb2988 [...] 2704 t*: 13: 6688 [0: 0] 2705 t3: 12: 6496 [0: ] 2706 t99: 1: 192 [0: 0] 2707 [...] 2708 2709 MAPPED_LIBRARIES: 2710 [...]]]></programlisting> The following matches the above heap profile, but most 2711 tokens are replaced with <constant><description></constant> to indicate 2712 descriptions of the corresponding fields. <programlisting><![CDATA[ 2713 <heap_profile_format_version>/<mean_sample_interval> 2714 <aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 2715 [...] 2716 <thread_3_aggregate>: <curobjs>: <curbytes>[<cumobjs>: <cumbytes>] 2717 [...] 2718 <thread_99_aggregate>: <curobjs>: <curbytes>[<cumobjs>: <cumbytes>] 2719 [...] 2720 @ <top_frame> <frame> [...] <frame> <frame> <frame> [...] 2721 <backtrace_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 2722 <backtrace_thread_3>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 2723 <backtrace_thread_99>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 2724 [...] 2725 2726 MAPPED_LIBRARIES: 2727 </proc/<pid>/maps>]]></programlisting></para> 2728 </refsect1> 2729 2730 <refsect1 id="debugging_malloc_problems"> 2731 <title>DEBUGGING MALLOC PROBLEMS</title> 2732 <para>When debugging, it is a good idea to configure/build jemalloc with 2733 the <option>--enable-debug</option> and <option>--enable-fill</option> 2734 options, and recompile the program with suitable options and symbols for 2735 debugger support. When so configured, jemalloc incorporates a wide variety 2736 of run-time assertions that catch application errors such as double-free, 2737 write-after-free, etc.</para> 2738 2739 <para>Programs often accidentally depend on <quote>uninitialized</quote> 2740 memory actually being filled with zero bytes. Junk filling 2741 (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> 2742 option) tends to expose such bugs in the form of obviously incorrect 2743 results and/or coredumps. Conversely, zero 2744 filling (see the <link 2745 linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates 2746 the symptoms of such bugs. Between these two options, it is usually 2747 possible to quickly detect, diagnose, and eliminate such bugs.</para> 2748 2749 <para>This implementation does not provide much detail about the problems 2750 it detects, because the performance impact for storing such information 2751 would be prohibitive. However, jemalloc does integrate with the most 2752 excellent <ulink url="http://valgrind.org/">Valgrind</ulink> tool if the 2753 <option>--enable-valgrind</option> configuration option is enabled.</para> 2754 </refsect1> 2755 <refsect1 id="diagnostic_messages"> 2756 <title>DIAGNOSTIC MESSAGES</title> 2757 <para>If any of the memory allocation/deallocation functions detect an 2758 error or warning condition, a message will be printed to file descriptor 2759 <constant>STDERR_FILENO</constant>. Errors will result in the process 2760 dumping core. If the <link 2761 linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most 2762 warnings are treated as errors.</para> 2763 2764 <para>The <varname>malloc_message</varname> variable allows the programmer 2765 to override the function which emits the text strings forming the errors 2766 and warnings if for some reason the <constant>STDERR_FILENO</constant> file 2767 descriptor is not suitable for this. 2768 <function>malloc_message()</function> takes the 2769 <parameter>cbopaque</parameter> pointer argument that is 2770 <constant>NULL</constant> unless overridden by the arguments in a call to 2771 <function>malloc_stats_print()</function>, followed by a string 2772 pointer. Please note that doing anything which tries to allocate memory in 2773 this function is likely to result in a crash or deadlock.</para> 2774 2775 <para>All messages are prefixed by 2776 <quote><computeroutput><jemalloc>: </computeroutput></quote>.</para> 2777 </refsect1> 2778 <refsect1 id="return_values"> 2779 <title>RETURN VALUES</title> 2780 <refsect2> 2781 <title>Standard API</title> 2782 <para>The <function>malloc()</function> and 2783 <function>calloc()</function> functions return a pointer to the 2784 allocated memory if successful; otherwise a <constant>NULL</constant> 2785 pointer is returned and <varname>errno</varname> is set to 2786 <errorname>ENOMEM</errorname>.</para> 2787 2788 <para>The <function>posix_memalign()</function> function 2789 returns the value 0 if successful; otherwise it returns an error value. 2790 The <function>posix_memalign()</function> function will fail 2791 if: 2792 <variablelist> 2793 <varlistentry> 2794 <term><errorname>EINVAL</errorname></term> 2795 2796 <listitem><para>The <parameter>alignment</parameter> parameter is 2797 not a power of 2 at least as large as 2798 <code language="C">sizeof(<type>void *</type>)</code>. 2799 </para></listitem> 2800 </varlistentry> 2801 <varlistentry> 2802 <term><errorname>ENOMEM</errorname></term> 2803 2804 <listitem><para>Memory allocation error.</para></listitem> 2805 </varlistentry> 2806 </variablelist> 2807 </para> 2808 2809 <para>The <function>aligned_alloc()</function> function returns 2810 a pointer to the allocated memory if successful; otherwise a 2811 <constant>NULL</constant> pointer is returned and 2812 <varname>errno</varname> is set. The 2813 <function>aligned_alloc()</function> function will fail if: 2814 <variablelist> 2815 <varlistentry> 2816 <term><errorname>EINVAL</errorname></term> 2817 2818 <listitem><para>The <parameter>alignment</parameter> parameter is 2819 not a power of 2. 2820 </para></listitem> 2821 </varlistentry> 2822 <varlistentry> 2823 <term><errorname>ENOMEM</errorname></term> 2824 2825 <listitem><para>Memory allocation error.</para></listitem> 2826 </varlistentry> 2827 </variablelist> 2828 </para> 2829 2830 <para>The <function>realloc()</function> function returns a 2831 pointer, possibly identical to <parameter>ptr</parameter>, to the 2832 allocated memory if successful; otherwise a <constant>NULL</constant> 2833 pointer is returned, and <varname>errno</varname> is set to 2834 <errorname>ENOMEM</errorname> if the error was the result of an 2835 allocation failure. The <function>realloc()</function> 2836 function always leaves the original buffer intact when an error occurs. 2837 </para> 2838 2839 <para>The <function>free()</function> function returns no 2840 value.</para> 2841 </refsect2> 2842 <refsect2> 2843 <title>Non-standard API</title> 2844 <para>The <function>mallocx()</function> and 2845 <function>rallocx()</function> functions return a pointer to 2846 the allocated memory if successful; otherwise a <constant>NULL</constant> 2847 pointer is returned to indicate insufficient contiguous memory was 2848 available to service the allocation request. </para> 2849 2850 <para>The <function>xallocx()</function> function returns the 2851 real size of the resulting resized allocation pointed to by 2852 <parameter>ptr</parameter>, which is a value less than 2853 <parameter>size</parameter> if the allocation could not be adequately 2854 grown in place. </para> 2855 2856 <para>The <function>sallocx()</function> function returns the 2857 real size of the allocation pointed to by <parameter>ptr</parameter>. 2858 </para> 2859 2860 <para>The <function>nallocx()</function> returns the real size 2861 that would result from a successful equivalent 2862 <function>mallocx()</function> function call, or zero if 2863 insufficient memory is available to perform the size computation. </para> 2864 2865 <para>The <function>mallctl()</function>, 2866 <function>mallctlnametomib()</function>, and 2867 <function>mallctlbymib()</function> functions return 0 on 2868 success; otherwise they return an error value. The functions will fail 2869 if: 2870 <variablelist> 2871 <varlistentry> 2872 <term><errorname>EINVAL</errorname></term> 2873 2874 <listitem><para><parameter>newp</parameter> is not 2875 <constant>NULL</constant>, and <parameter>newlen</parameter> is too 2876 large or too small. Alternatively, <parameter>*oldlenp</parameter> 2877 is too large or too small; in this case as much data as possible 2878 are read despite the error.</para></listitem> 2879 </varlistentry> 2880 <varlistentry> 2881 <term><errorname>ENOENT</errorname></term> 2882 2883 <listitem><para><parameter>name</parameter> or 2884 <parameter>mib</parameter> specifies an unknown/invalid 2885 value.</para></listitem> 2886 </varlistentry> 2887 <varlistentry> 2888 <term><errorname>EPERM</errorname></term> 2889 2890 <listitem><para>Attempt to read or write void value, or attempt to 2891 write read-only value.</para></listitem> 2892 </varlistentry> 2893 <varlistentry> 2894 <term><errorname>EAGAIN</errorname></term> 2895 2896 <listitem><para>A memory allocation failure 2897 occurred.</para></listitem> 2898 </varlistentry> 2899 <varlistentry> 2900 <term><errorname>EFAULT</errorname></term> 2901 2902 <listitem><para>An interface with side effects failed in some way 2903 not directly related to <function>mallctl*()</function> 2904 read/write processing.</para></listitem> 2905 </varlistentry> 2906 </variablelist> 2907 </para> 2908 2909 <para>The <function>malloc_usable_size()</function> function 2910 returns the usable size of the allocation pointed to by 2911 <parameter>ptr</parameter>. </para> 2912 </refsect2> 2913 </refsect1> 2914 <refsect1 id="environment"> 2915 <title>ENVIRONMENT</title> 2916 <para>The following environment variable affects the execution of the 2917 allocation functions: 2918 <variablelist> 2919 <varlistentry> 2920 <term><envar>MALLOC_CONF</envar></term> 2921 2922 <listitem><para>If the environment variable 2923 <envar>MALLOC_CONF</envar> is set, the characters it contains 2924 will be interpreted as options.</para></listitem> 2925 </varlistentry> 2926 </variablelist> 2927 </para> 2928 </refsect1> 2929 <refsect1 id="examples"> 2930 <title>EXAMPLES</title> 2931 <para>To dump core whenever a problem occurs: 2932 <screen>ln -s 'abort:true' /etc/malloc.conf</screen> 2933 </para> 2934 <para>To specify in the source a chunk size that is 16 MiB: 2935 <programlisting language="C"><![CDATA[ 2936 malloc_conf = "lg_chunk:24";]]></programlisting></para> 2937 </refsect1> 2938 <refsect1 id="see_also"> 2939 <title>SEE ALSO</title> 2940 <para><citerefentry><refentrytitle>madvise</refentrytitle> 2941 <manvolnum>2</manvolnum></citerefentry>, 2942 <citerefentry><refentrytitle>mmap</refentrytitle> 2943 <manvolnum>2</manvolnum></citerefentry>, 2944 <citerefentry><refentrytitle>sbrk</refentrytitle> 2945 <manvolnum>2</manvolnum></citerefentry>, 2946 <citerefentry><refentrytitle>utrace</refentrytitle> 2947 <manvolnum>2</manvolnum></citerefentry>, 2948 <citerefentry><refentrytitle>alloca</refentrytitle> 2949 <manvolnum>3</manvolnum></citerefentry>, 2950 <citerefentry><refentrytitle>atexit</refentrytitle> 2951 <manvolnum>3</manvolnum></citerefentry>, 2952 <citerefentry><refentrytitle>getpagesize</refentrytitle> 2953 <manvolnum>3</manvolnum></citerefentry></para> 2954 </refsect1> 2955 <refsect1 id="standards"> 2956 <title>STANDARDS</title> 2957 <para>The <function>malloc()</function>, 2958 <function>calloc()</function>, 2959 <function>realloc()</function>, and 2960 <function>free()</function> functions conform to ISO/IEC 2961 9899:1990 (<quote>ISO C90</quote>).</para> 2962 2963 <para>The <function>posix_memalign()</function> function conforms 2964 to IEEE Std 1003.1-2001 (<quote>POSIX.1</quote>).</para> 2965 </refsect1> 2966 </refentry> 2967
