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[ 395unsigned nbins, i; 396size_t mib[4]; 397size_t len, miblen; 398 399len = sizeof(nbins); 400mallctl("arenas.nbins", &nbins, &len, NULL, 0); 401 402miblen = 4; 403mallctlnametomib("arenas.bin.0.size", mib, &miblen); 404for (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 <varlistentry id="malloc_stats_print_opts"> 414 </varlistentry> 415 <para>The <function>malloc_stats_print()</function> function writes 416 summary statistics via the <parameter>write_cb</parameter> callback 417 function pointer and <parameter>cbopaque</parameter> data passed to 418 <parameter>write_cb</parameter>, or <function>malloc_message()</function> 419 if <parameter>write_cb</parameter> is <constant>NULL</constant>. The 420 statistics are presented in human-readable form unless <quote>J</quote> is 421 specified as a character within the <parameter>opts</parameter> string, in 422 which case the statistics are presented in <ulink 423 url="http://www.json.org/">JSON format</ulink>. This function can be 424 called repeatedly. General information that never changes during 425 execution can be omitted by specifying <quote>g</quote> as a character 426 within the <parameter>opts</parameter> string. Note that 427 <function>malloc_stats_print()</function> uses the 428 <function>mallctl*()</function> functions internally, so inconsistent 429 statistics can be reported if multiple threads use these functions 430 simultaneously. If <option>--enable-stats</option> is specified during 431 configuration, <quote>m</quote>, <quote>d</quote>, and <quote>a</quote> 432 can be specified to omit merged arena, destroyed merged arena, and per 433 arena statistics, respectively; <quote>b</quote> and <quote>l</quote> can 434 be specified to omit per size class statistics for bins and large objects, 435 respectively; <quote>x</quote> can be specified to omit all mutex 436 statistics; <quote>e</quote> can be used to omit extent statistics. 437 Unrecognized characters are silently ignored. Note that thread caching 438 may prevent some statistics from being completely up to date, since extra 439 locking would be required to merge counters that track thread cache 440 operations.</para> 441 442 <para>The <function>malloc_usable_size()</function> function 443 returns the usable size of the allocation pointed to by 444 <parameter>ptr</parameter>. The return value may be larger than the size 445 that was requested during allocation. The 446 <function>malloc_usable_size()</function> function is not a 447 mechanism for in-place <function>realloc()</function>; rather 448 it is provided solely as a tool for introspection purposes. Any 449 discrepancy between the requested allocation size and the size reported 450 by <function>malloc_usable_size()</function> should not be 451 depended on, since such behavior is entirely implementation-dependent. 452 </para> 453 </refsect2> 454 </refsect1> 455 <refsect1 id="tuning"> 456 <title>TUNING</title> 457 <para>Once, when the first call is made to one of the memory allocation 458 routines, the allocator initializes its internals based in part on various 459 options that can be specified at compile- or run-time.</para> 460 461 <para>The string specified via <option>--with-malloc-conf</option>, the 462 string pointed to by the global variable <varname>malloc_conf</varname>, the 463 <quote>name</quote> of the file referenced by the symbolic link named 464 <filename class="symlink">/etc/malloc.conf</filename>, and the value of the 465 environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in 466 that order, from left to right as options. Note that 467 <varname>malloc_conf</varname> may be read before 468 <function>main()</function> is entered, so the declaration of 469 <varname>malloc_conf</varname> should specify an initializer that contains 470 the final value to be read by jemalloc. <option>--with-malloc-conf</option> 471 and <varname>malloc_conf</varname> are compile-time mechanisms, whereas 472 <filename class="symlink">/etc/malloc.conf</filename> and 473 <envar>MALLOC_CONF</envar> can be safely set any time prior to program 474 invocation.</para> 475 476 <para>An options string is a comma-separated list of option:value pairs. 477 There is one key corresponding to each <link 478 linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the <xref 479 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for options 480 documentation). For example, <literal>abort:true,narenas:1</literal> sets 481 the <link linkend="opt.abort"><mallctl>opt.abort</mallctl></link> and <link 482 linkend="opt.narenas"><mallctl>opt.narenas</mallctl></link> options. Some 483 options have boolean values (true/false), others have integer values (base 484 8, 10, or 16, depending on prefix), and yet others have raw string 485 values.</para> 486 </refsect1> 487 <refsect1 id="implementation_notes"> 488 <title>IMPLEMENTATION NOTES</title> 489 <para>Traditionally, allocators have used 490 <citerefentry><refentrytitle>sbrk</refentrytitle> 491 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is 492 suboptimal for several reasons, including race conditions, increased 493 fragmentation, and artificial limitations on maximum usable memory. If 494 <citerefentry><refentrytitle>sbrk</refentrytitle> 495 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 496 system, this allocator uses both 497 <citerefentry><refentrytitle>mmap</refentrytitle> 498 <manvolnum>2</manvolnum></citerefentry> and 499 <citerefentry><refentrytitle>sbrk</refentrytitle> 500 <manvolnum>2</manvolnum></citerefentry>, in that order of preference; 501 otherwise only <citerefentry><refentrytitle>mmap</refentrytitle> 502 <manvolnum>2</manvolnum></citerefentry> is used.</para> 503 504 <para>This allocator uses multiple arenas in order to reduce lock 505 contention for threaded programs on multi-processor systems. This works 506 well with regard to threading scalability, but incurs some costs. There is 507 a small fixed per-arena overhead, and additionally, arenas manage memory 508 completely independently of each other, which means a small fixed increase 509 in overall memory fragmentation. These overheads are not generally an 510 issue, given the number of arenas normally used. Note that using 511 substantially more arenas than the default is not likely to improve 512 performance, mainly due to reduced cache performance. However, it may make 513 sense to reduce the number of arenas if an application does not make much 514 use of the allocation functions.</para> 515 516 <para>In addition to multiple arenas, this allocator supports 517 thread-specific caching, in order to make it possible to completely avoid 518 synchronization for most allocation requests. Such caching allows very fast 519 allocation in the common case, but it increases memory usage and 520 fragmentation, since a bounded number of objects can remain allocated in 521 each thread cache.</para> 522 523 <para>Memory is conceptually broken into extents. Extents are always 524 aligned to multiples of the page size. This alignment makes it possible to 525 find metadata for user objects quickly. User objects are broken into two 526 categories according to size: small and large. Contiguous small objects 527 comprise a slab, which resides within a single extent, whereas large objects 528 each have their own extents backing them.</para> 529 530 <para>Small objects are managed in groups by slabs. Each slab maintains 531 a bitmap to track which regions are in use. Allocation requests that are no 532 more than half the quantum (8 or 16, depending on architecture) are rounded 533 up to the nearest power of two that is at least <code 534 language="C">sizeof(<type>double</type>)</code>. All other object size 535 classes are multiples of the quantum, spaced such that there are four size 536 classes for each doubling in size, which limits internal fragmentation to 537 approximately 20% for all but the smallest size classes. Small size classes 538 are smaller than four times the page size, and large size classes extend 539 from four times the page size up to the largest size class that does not 540 exceed <constant>PTRDIFF_MAX</constant>.</para> 541 542 <para>Allocations are packed tightly together, which can be an issue for 543 multi-threaded applications. If you need to assure that allocations do not 544 suffer from cacheline sharing, round your allocation requests up to the 545 nearest multiple of the cacheline size, or specify cacheline alignment when 546 allocating.</para> 547 548 <para>The <function>realloc()</function>, 549 <function>rallocx()</function>, and 550 <function>xallocx()</function> functions may resize allocations 551 without moving them under limited circumstances. Unlike the 552 <function>*allocx()</function> API, the standard API does not 553 officially round up the usable size of an allocation to the nearest size 554 class, so technically it is necessary to call 555 <function>realloc()</function> to grow e.g. a 9-byte allocation to 556 16 bytes, or shrink a 16-byte allocation to 9 bytes. Growth and shrinkage 557 trivially succeeds in place as long as the pre-size and post-size both round 558 up to the same size class. No other API guarantees are made regarding 559 in-place resizing, but the current implementation also tries to resize large 560 allocations in place, as long as the pre-size and post-size are both large. 561 For shrinkage to succeed, the extent allocator must support splitting (see 562 <link 563 linkend="arena.i.extent_hooks"><mallctl>arena.<i>.extent_hooks</mallctl></link>). 564 Growth only succeeds if the trailing memory is currently available, and the 565 extent allocator supports merging.</para> 566 567 <para>Assuming 4 KiB pages and a 16-byte quantum on a 64-bit system, the 568 size classes in each category are as shown in <xref linkend="size_classes" 569 xrefstyle="template:Table %n"/>.</para> 570 571 <table xml:id="size_classes" frame="all"> 572 <title>Size classes</title> 573 <tgroup cols="3" colsep="1" rowsep="1"> 574 <colspec colname="c1" align="left"/> 575 <colspec colname="c2" align="right"/> 576 <colspec colname="c3" align="left"/> 577 <thead> 578 <row> 579 <entry>Category</entry> 580 <entry>Spacing</entry> 581 <entry>Size</entry> 582 </row> 583 </thead> 584 <tbody> 585 <row> 586 <entry morerows="8">Small</entry> 587 <entry>lg</entry> 588 <entry>[8]</entry> 589 </row> 590 <row> 591 <entry>16</entry> 592 <entry>[16, 32, 48, 64, 80, 96, 112, 128]</entry> 593 </row> 594 <row> 595 <entry>32</entry> 596 <entry>[160, 192, 224, 256]</entry> 597 </row> 598 <row> 599 <entry>64</entry> 600 <entry>[320, 384, 448, 512]</entry> 601 </row> 602 <row> 603 <entry>128</entry> 604 <entry>[640, 768, 896, 1024]</entry> 605 </row> 606 <row> 607 <entry>256</entry> 608 <entry>[1280, 1536, 1792, 2048]</entry> 609 </row> 610 <row> 611 <entry>512</entry> 612 <entry>[2560, 3072, 3584, 4096]</entry> 613 </row> 614 <row> 615 <entry>1 KiB</entry> 616 <entry>[5 KiB, 6 KiB, 7 KiB, 8 KiB]</entry> 617 </row> 618 <row> 619 <entry>2 KiB</entry> 620 <entry>[10 KiB, 12 KiB, 14 KiB]</entry> 621 </row> 622 <row> 623 <entry morerows="15">Large</entry> 624 <entry>2 KiB</entry> 625 <entry>[16 KiB]</entry> 626 </row> 627 <row> 628 <entry>4 KiB</entry> 629 <entry>[20 KiB, 24 KiB, 28 KiB, 32 KiB]</entry> 630 </row> 631 <row> 632 <entry>8 KiB</entry> 633 <entry>[40 KiB, 48 KiB, 54 KiB, 64 KiB]</entry> 634 </row> 635 <row> 636 <entry>16 KiB</entry> 637 <entry>[80 KiB, 96 KiB, 112 KiB, 128 KiB]</entry> 638 </row> 639 <row> 640 <entry>32 KiB</entry> 641 <entry>[160 KiB, 192 KiB, 224 KiB, 256 KiB]</entry> 642 </row> 643 <row> 644 <entry>64 KiB</entry> 645 <entry>[320 KiB, 384 KiB, 448 KiB, 512 KiB]</entry> 646 </row> 647 <row> 648 <entry>128 KiB</entry> 649 <entry>[640 KiB, 768 KiB, 896 KiB, 1 MiB]</entry> 650 </row> 651 <row> 652 <entry>256 KiB</entry> 653 <entry>[1280 KiB, 1536 KiB, 1792 KiB, 2 MiB]</entry> 654 </row> 655 <row> 656 <entry>512 KiB</entry> 657 <entry>[2560 KiB, 3 MiB, 3584 KiB, 4 MiB]</entry> 658 </row> 659 <row> 660 <entry>1 MiB</entry> 661 <entry>[5 MiB, 6 MiB, 7 MiB, 8 MiB]</entry> 662 </row> 663 <row> 664 <entry>2 MiB</entry> 665 <entry>[10 MiB, 12 MiB, 14 MiB, 16 MiB]</entry> 666 </row> 667 <row> 668 <entry>4 MiB</entry> 669 <entry>[20 MiB, 24 MiB, 28 MiB, 32 MiB]</entry> 670 </row> 671 <row> 672 <entry>8 MiB</entry> 673 <entry>[40 MiB, 48 MiB, 56 MiB, 64 MiB]</entry> 674 </row> 675 <row> 676 <entry>...</entry> 677 <entry>...</entry> 678 </row> 679 <row> 680 <entry>512 PiB</entry> 681 <entry>[2560 PiB, 3 EiB, 3584 PiB, 4 EiB]</entry> 682 </row> 683 <row> 684 <entry>1 EiB</entry> 685 <entry>[5 EiB, 6 EiB, 7 EiB]</entry> 686 </row> 687 </tbody> 688 </tgroup> 689 </table> 690 </refsect1> 691 <refsect1 id="mallctl_namespace"> 692 <title>MALLCTL NAMESPACE</title> 693 <para>The following names are defined in the namespace accessible via the 694 <function>mallctl*()</function> functions. Value types are specified in 695 parentheses, their readable/writable statuses are encoded as 696 <literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or 697 <literal>--</literal>, and required build configuration flags follow, if 698 any. A name element encoded as <literal><i></literal> or 699 <literal><j></literal> indicates an integer component, where the 700 integer varies from 0 to some upper value that must be determined via 701 introspection. In the case of <mallctl>stats.arenas.<i>.*</mallctl> 702 and <mallctl>arena.<i>.{initialized,purge,decay,dss}</mallctl>, 703 <literal><i></literal> equal to 704 <constant>MALLCTL_ARENAS_ALL</constant> can be used to operate on all arenas 705 or access the summation of statistics from all arenas; similarly 706 <literal><i></literal> equal to 707 <constant>MALLCTL_ARENAS_DESTROYED</constant> can be used to access the 708 summation of statistics from all destroyed arenas. These constants can be 709 utilized either via <function>mallctlnametomib()</function> followed by 710 <function>mallctlbymib()</function>, or via code such as the following: 711 <programlisting language="C"><![CDATA[ 712#define STRINGIFY_HELPER(x) #x 713#define STRINGIFY(x) STRINGIFY_HELPER(x) 714 715mallctl("arena." STRINGIFY(MALLCTL_ARENAS_ALL) ".decay", 716 NULL, NULL, NULL, 0);]]></programlisting> 717 Take special note of the <link 718 linkend="epoch"><mallctl>epoch</mallctl></link> mallctl, which controls 719 refreshing of cached dynamic statistics.</para> 720 721 <variablelist> 722 <varlistentry id="version"> 723 <term> 724 <mallctl>version</mallctl> 725 (<type>const char *</type>) 726 <literal>r-</literal> 727 </term> 728 <listitem><para>Return the jemalloc version string.</para></listitem> 729 </varlistentry> 730 731 <varlistentry id="epoch"> 732 <term> 733 <mallctl>epoch</mallctl> 734 (<type>uint64_t</type>) 735 <literal>rw</literal> 736 </term> 737 <listitem><para>If a value is passed in, refresh the data from which 738 the <function>mallctl*()</function> functions report values, 739 and increment the epoch. Return the current epoch. This is useful for 740 detecting whether another thread caused a refresh.</para></listitem> 741 </varlistentry> 742 743 <varlistentry id="background_thread"> 744 <term> 745 <mallctl>background_thread</mallctl> 746 (<type>bool</type>) 747 <literal>rw</literal> 748 </term> 749 <listitem><para>Enable/disable internal background worker threads. When 750 set to true, background threads are created on demand (the number of 751 background threads will be no more than the number of CPUs or active 752 arenas). Threads run periodically, and handle <link 753 linkend="arena.i.decay">purging</link> asynchronously. When switching 754 off, background threads are terminated synchronously. Note that after 755 <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry> 756 function, the state in the child process will be disabled regardless 757 the state in parent process. See <link 758 linkend="stats.background_thread.num_threads"><mallctl>stats.background_thread</mallctl></link> 759 for related stats. <link 760 linkend="opt.background_thread"><mallctl>opt.background_thread</mallctl></link> 761 can be used to set the default option. This option is only available on 762 selected pthread-based platforms.</para></listitem> 763 </varlistentry> 764 765 <varlistentry id="max_background_threads"> 766 <term> 767 <mallctl>max_background_threads</mallctl> 768 (<type>size_t</type>) 769 <literal>rw</literal> 770 </term> 771 <listitem><para>Maximum number of background worker threads that will 772 be created. This value is capped at <link 773 linkend="opt.max_background_threads"><mallctl>opt.max_background_threads</mallctl></link> at 774 startup.</para></listitem> 775 </varlistentry> 776 777 <varlistentry id="config.cache_oblivious"> 778 <term> 779 <mallctl>config.cache_oblivious</mallctl> 780 (<type>bool</type>) 781 <literal>r-</literal> 782 </term> 783 <listitem><para><option>--enable-cache-oblivious</option> was specified 784 during build configuration.</para></listitem> 785 </varlistentry> 786 787 <varlistentry id="config.debug"> 788 <term> 789 <mallctl>config.debug</mallctl> 790 (<type>bool</type>) 791 <literal>r-</literal> 792 </term> 793 <listitem><para><option>--enable-debug</option> was specified during 794 build configuration.</para></listitem> 795 </varlistentry> 796 797 <varlistentry id="config.fill"> 798 <term> 799 <mallctl>config.fill</mallctl> 800 (<type>bool</type>) 801 <literal>r-</literal> 802 </term> 803 <listitem><para><option>--enable-fill</option> was specified during 804 build configuration.</para></listitem> 805 </varlistentry> 806 807 <varlistentry id="config.lazy_lock"> 808 <term> 809 <mallctl>config.lazy_lock</mallctl> 810 (<type>bool</type>) 811 <literal>r-</literal> 812 </term> 813 <listitem><para><option>--enable-lazy-lock</option> was specified 814 during build configuration.</para></listitem> 815 </varlistentry> 816 817 <varlistentry id="config.malloc_conf"> 818 <term> 819 <mallctl>config.malloc_conf</mallctl> 820 (<type>const char *</type>) 821 <literal>r-</literal> 822 </term> 823 <listitem><para>Embedded configure-time-specified run-time options 824 string, empty unless <option>--with-malloc-conf</option> was specified 825 during build configuration.</para></listitem> 826 </varlistentry> 827 828 <varlistentry id="config.prof"> 829 <term> 830 <mallctl>config.prof</mallctl> 831 (<type>bool</type>) 832 <literal>r-</literal> 833 </term> 834 <listitem><para><option>--enable-prof</option> was specified during 835 build configuration.</para></listitem> 836 </varlistentry> 837 838 <varlistentry id="config.prof_libgcc"> 839 <term> 840 <mallctl>config.prof_libgcc</mallctl> 841 (<type>bool</type>) 842 <literal>r-</literal> 843 </term> 844 <listitem><para><option>--disable-prof-libgcc</option> was not 845 specified during build configuration.</para></listitem> 846 </varlistentry> 847 848 <varlistentry id="config.prof_libunwind"> 849 <term> 850 <mallctl>config.prof_libunwind</mallctl> 851 (<type>bool</type>) 852 <literal>r-</literal> 853 </term> 854 <listitem><para><option>--enable-prof-libunwind</option> was specified 855 during build configuration.</para></listitem> 856 </varlistentry> 857 858 <varlistentry id="config.stats"> 859 <term> 860 <mallctl>config.stats</mallctl> 861 (<type>bool</type>) 862 <literal>r-</literal> 863 </term> 864 <listitem><para><option>--enable-stats</option> was specified during 865 build configuration.</para></listitem> 866 </varlistentry> 867 868 869 <varlistentry id="config.utrace"> 870 <term> 871 <mallctl>config.utrace</mallctl> 872 (<type>bool</type>) 873 <literal>r-</literal> 874 </term> 875 <listitem><para><option>--enable-utrace</option> was specified during 876 build configuration.</para></listitem> 877 </varlistentry> 878 879 <varlistentry id="config.xmalloc"> 880 <term> 881 <mallctl>config.xmalloc</mallctl> 882 (<type>bool</type>) 883 <literal>r-</literal> 884 </term> 885 <listitem><para><option>--enable-xmalloc</option> was specified during 886 build configuration.</para></listitem> 887 </varlistentry> 888 889 <varlistentry id="opt.abort"> 890 <term> 891 <mallctl>opt.abort</mallctl> 892 (<type>bool</type>) 893 <literal>r-</literal> 894 </term> 895 <listitem><para>Abort-on-warning enabled/disabled. If true, most 896 warnings are fatal. Note that runtime option warnings are not included 897 (see <link 898 linkend="opt.abort_conf"><mallctl>opt.abort_conf</mallctl></link> for 899 that). The process will call 900 <citerefentry><refentrytitle>abort</refentrytitle> 901 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 902 disabled by default unless <option>--enable-debug</option> is 903 specified during configuration, in which case it is enabled by default. 904 </para></listitem> 905 </varlistentry> 906 907 <varlistentry id="opt.confirm_conf"> 908 <term> 909 <mallctl>opt.confirm_conf</mallctl> 910 (<type>bool</type>) 911 <literal>r-</literal> 912 </term> 913 <listitem><para>Confirm-runtime-options-when-program-starts 914 enabled/disabled. If true, the string specified via 915 <option>--with-malloc-conf</option>, the string pointed to by the 916 global variable <varname>malloc_conf</varname>, the <quote>name</quote> 917 of the file referenced by the symbolic link named 918 <filename class="symlink">/etc/malloc.conf</filename>, and the value of 919 the environment variable <envar>MALLOC_CONF</envar>, will be printed in 920 order. Then, each option being set will be individually printed. This 921 option is disabled by default.</para></listitem> 922 </varlistentry> 923 924 <varlistentry id="opt.abort_conf"> 925 <term> 926 <mallctl>opt.abort_conf</mallctl> 927 (<type>bool</type>) 928 <literal>r-</literal> 929 </term> 930 <listitem><para>Abort-on-invalid-configuration enabled/disabled. If 931 true, invalid runtime options are fatal. The process will call 932 <citerefentry><refentrytitle>abort</refentrytitle> 933 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 934 disabled by default unless <option>--enable-debug</option> is 935 specified during configuration, in which case it is enabled by default. 936 </para></listitem> 937 </varlistentry> 938 939 <varlistentry id="opt.metadata_thp"> 940 <term> 941 <mallctl>opt.metadata_thp</mallctl> 942 (<type>const char *</type>) 943 <literal>r-</literal> 944 </term> 945 <listitem><para>Controls whether to allow jemalloc to use transparent 946 huge page (THP) for internal metadata (see <link 947 linkend="stats.metadata">stats.metadata</link>). <quote>always</quote> 948 allows such usage. <quote>auto</quote> uses no THP initially, but may 949 begin to do so when metadata usage reaches certain level. The default 950 is <quote>disabled</quote>.</para></listitem> 951 </varlistentry> 952 953 <varlistentry id="opt.retain"> 954 <term> 955 <mallctl>opt.retain</mallctl> 956 (<type>bool</type>) 957 <literal>r-</literal> 958 </term> 959 <listitem><para>If true, retain unused virtual memory for later reuse 960 rather than discarding it by calling 961 <citerefentry><refentrytitle>munmap</refentrytitle> 962 <manvolnum>2</manvolnum></citerefentry> or equivalent (see <link 963 linkend="stats.retained">stats.retained</link> for related details). 964 It also makes jemalloc use <citerefentry> 965 <refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum> 966 </citerefentry> or equivalent in a more greedy way, mapping larger 967 chunks in one go. This option is disabled by default unless discarding 968 virtual memory is known to trigger platform-specific performance 969 problems, namely 1) for [64-bit] Linux, which has a quirk in its virtual 970 memory allocation algorithm that causes semi-permanent VM map holes 971 under normal jemalloc operation; and 2) for [64-bit] Windows, which 972 disallows split / merged regions with 973 <parameter><constant>MEM_RELEASE</constant></parameter>. Although the 974 same issues may present on 32-bit platforms as well, retaining virtual 975 memory for 32-bit Linux and Windows is disabled by default due to the 976 practical possibility of address space exhaustion. </para></listitem> 977 </varlistentry> 978 979 <varlistentry id="opt.dss"> 980 <term> 981 <mallctl>opt.dss</mallctl> 982 (<type>const char *</type>) 983 <literal>r-</literal> 984 </term> 985 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 986 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 987 related to <citerefentry><refentrytitle>mmap</refentrytitle> 988 <manvolnum>2</manvolnum></citerefentry> allocation. The following 989 settings are supported if 990 <citerefentry><refentrytitle>sbrk</refentrytitle> 991 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 992 system: <quote>disabled</quote>, <quote>primary</quote>, and 993 <quote>secondary</quote>; otherwise only <quote>disabled</quote> is 994 supported. The default is <quote>secondary</quote> if 995 <citerefentry><refentrytitle>sbrk</refentrytitle> 996 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 997 system; <quote>disabled</quote> otherwise. 998 </para></listitem> 999 </varlistentry> 1000 1001 <varlistentry id="opt.narenas"> 1002 <term> 1003 <mallctl>opt.narenas</mallctl> 1004 (<type>unsigned</type>) 1005 <literal>r-</literal> 1006 </term> 1007 <listitem><para>Maximum number of arenas to use for automatic 1008 multiplexing of threads and arenas. The default is four times the 1009 number of CPUs, or one if there is a single CPU.</para></listitem> 1010 </varlistentry> 1011 1012 <varlistentry id="opt.oversize_threshold"> 1013 <term> 1014 <mallctl>opt.oversize_threshold</mallctl> 1015 (<type>size_t</type>) 1016 <literal>r-</literal> 1017 </term> 1018 <listitem><para>The threshold in bytes of which requests are considered 1019 oversize. Allocation requests with greater sizes are fulfilled from a 1020 dedicated arena (automatically managed, however not within 1021 <literal>narenas</literal>), in order to reduce fragmentation by not 1022 mixing huge allocations with small ones. In addition, the decay API 1023 guarantees on the extents greater than the specified threshold may be 1024 overridden. Note that requests with arena index specified via 1025 <constant>MALLOCX_ARENA</constant>, or threads associated with explicit 1026 arenas will not be considered. The default threshold is 8MiB. Values 1027 not within large size classes disables this feature.</para></listitem> 1028 </varlistentry> 1029 1030 <varlistentry id="opt.percpu_arena"> 1031 <term> 1032 <mallctl>opt.percpu_arena</mallctl> 1033 (<type>const char *</type>) 1034 <literal>r-</literal> 1035 </term> 1036 <listitem><para>Per CPU arena mode. Use the <quote>percpu</quote> 1037 setting to enable this feature, which uses number of CPUs to determine 1038 number of arenas, and bind threads to arenas dynamically based on the 1039 CPU the thread runs on currently. <quote>phycpu</quote> setting uses 1040 one arena per physical CPU, which means the two hyper threads on the 1041 same CPU share one arena. Note that no runtime checking regarding the 1042 availability of hyper threading is done at the moment. When set to 1043 <quote>disabled</quote>, narenas and thread to arena association will 1044 not be impacted by this option. The default is <quote>disabled</quote>. 1045 </para></listitem> 1046 </varlistentry> 1047 1048 <varlistentry id="opt.background_thread"> 1049 <term> 1050 <mallctl>opt.background_thread</mallctl> 1051 (<type>bool</type>) 1052 <literal>r-</literal> 1053 </term> 1054 <listitem><para>Internal background worker threads enabled/disabled. 1055 Because of potential circular dependencies, enabling background thread 1056 using this option may cause crash or deadlock during initialization. For 1057 a reliable way to use this feature, see <link 1058 linkend="background_thread">background_thread</link> for dynamic control 1059 options and details. This option is disabled by 1060 default.</para></listitem> 1061 </varlistentry> 1062 1063 <varlistentry id="opt.max_background_threads"> 1064 <term> 1065 <mallctl>opt.max_background_threads</mallctl> 1066 (<type>size_t</type>) 1067 <literal>r-</literal> 1068 </term> 1069 <listitem><para>Maximum number of background threads that will be created 1070 if <link linkend="background_thread">background_thread</link> is set. 1071 Defaults to number of cpus.</para></listitem> 1072 </varlistentry> 1073 1074 <varlistentry id="opt.dirty_decay_ms"> 1075 <term> 1076 <mallctl>opt.dirty_decay_ms</mallctl> 1077 (<type>ssize_t</type>) 1078 <literal>r-</literal> 1079 </term> 1080 <listitem><para>Approximate time in milliseconds from the creation of a 1081 set of unused dirty pages until an equivalent set of unused dirty pages 1082 is purged (i.e. converted to muzzy via e.g. 1083 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function> 1084 if supported by the operating system, or converted to clean otherwise) 1085 and/or reused. Dirty pages are defined as previously having been 1086 potentially written to by the application, and therefore consuming 1087 physical memory, yet having no current use. The pages are incrementally 1088 purged according to a sigmoidal decay curve that starts and ends with 1089 zero purge rate. A decay time of 0 causes all unused dirty pages to be 1090 purged immediately upon creation. A decay time of -1 disables purging. 1091 The default decay time is 10 seconds. See <link 1092 linkend="arenas.dirty_decay_ms"><mallctl>arenas.dirty_decay_ms</mallctl></link> 1093 and <link 1094 linkend="arena.i.dirty_decay_ms"><mallctl>arena.<i>.dirty_decay_ms</mallctl></link> 1095 for related dynamic control options. See <link 1096 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 1097 for a description of muzzy pages.for a description of muzzy pages. Note 1098 that when the <link 1099 linkend="opt.oversize_threshold"><mallctl>oversize_threshold</mallctl></link> 1100 feature is enabled, the arenas reserved for oversize requests may have 1101 its own default decay settings.</para></listitem> 1102 </varlistentry> 1103 1104 <varlistentry id="opt.muzzy_decay_ms"> 1105 <term> 1106 <mallctl>opt.muzzy_decay_ms</mallctl> 1107 (<type>ssize_t</type>) 1108 <literal>r-</literal> 1109 </term> 1110 <listitem><para>Approximate time in milliseconds from the creation of a 1111 set of unused muzzy pages until an equivalent set of unused muzzy pages 1112 is purged (i.e. converted to clean) and/or reused. Muzzy pages are 1113 defined as previously having been unused dirty pages that were 1114 subsequently purged in a manner that left them subject to the 1115 reclamation whims of the operating system (e.g. 1116 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function>), 1117 and therefore in an indeterminate state. The pages are incrementally 1118 purged according to a sigmoidal decay curve that starts and ends with 1119 zero purge rate. A decay time of 0 causes all unused muzzy pages to be 1120 purged immediately upon creation. A decay time of -1 disables purging. 1121 The default decay time is 10 seconds. See <link 1122 linkend="arenas.muzzy_decay_ms"><mallctl>arenas.muzzy_decay_ms</mallctl></link> 1123 and <link 1124 linkend="arena.i.muzzy_decay_ms"><mallctl>arena.<i>.muzzy_decay_ms</mallctl></link> 1125 for related dynamic control options.</para></listitem> 1126 </varlistentry> 1127 1128 <varlistentry id="opt.lg_extent_max_active_fit"> 1129 <term> 1130 <mallctl>opt.lg_extent_max_active_fit</mallctl> 1131 (<type>size_t</type>) 1132 <literal>r-</literal> 1133 </term> 1134 <listitem><para>When reusing dirty extents, this determines the (log 1135 base 2 of the) maximum ratio between the size of the active extent 1136 selected (to split off from) and the size of the requested allocation. 1137 This prevents the splitting of large active extents for smaller 1138 allocations, which can reduce fragmentation over the long run 1139 (especially for non-active extents). Lower value may reduce 1140 fragmentation, at the cost of extra active extents. The default value 1141 is 6, which gives a maximum ratio of 64 (2^6).</para></listitem> 1142 </varlistentry> 1143 1144 <varlistentry id="opt.stats_print"> 1145 <term> 1146 <mallctl>opt.stats_print</mallctl> 1147 (<type>bool</type>) 1148 <literal>r-</literal> 1149 </term> 1150 <listitem><para>Enable/disable statistics printing at exit. If 1151 enabled, the <function>malloc_stats_print()</function> 1152 function is called at program exit via an 1153 <citerefentry><refentrytitle>atexit</refentrytitle> 1154 <manvolnum>3</manvolnum></citerefentry> function. <link 1155 linkend="opt.stats_print_opts"><mallctl>opt.stats_print_opts</mallctl></link> 1156 can be combined to specify output options. If 1157 <option>--enable-stats</option> is specified during configuration, this 1158 has the potential to cause deadlock for a multi-threaded process that 1159 exits while one or more threads are executing in the memory allocation 1160 functions. Furthermore, <function>atexit()</function> may 1161 allocate memory during application initialization and then deadlock 1162 internally when jemalloc in turn calls 1163 <function>atexit()</function>, so this option is not 1164 universally usable (though the application can register its own 1165 <function>atexit()</function> function with equivalent 1166 functionality). Therefore, this option should only be used with care; 1167 it is primarily intended as a performance tuning aid during application 1168 development. This option is disabled by default.</para></listitem> 1169 </varlistentry> 1170 1171 <varlistentry id="opt.stats_print_opts"> 1172 <term> 1173 <mallctl>opt.stats_print_opts</mallctl> 1174 (<type>const char *</type>) 1175 <literal>r-</literal> 1176 </term> 1177 <listitem><para>Options (the <parameter>opts</parameter> string) to pass 1178 to the <function>malloc_stats_print()</function> at exit (enabled 1179 through <link 1180 linkend="opt.stats_print"><mallctl>opt.stats_print</mallctl></link>). See 1181 available options in <link 1182 linkend="malloc_stats_print_opts"><function>malloc_stats_print()</function></link>. 1183 Has no effect unless <link 1184 linkend="opt.stats_print"><mallctl>opt.stats_print</mallctl></link> is 1185 enabled. The default is <quote></quote>.</para></listitem> 1186 </varlistentry> 1187 1188 <varlistentry id="opt.junk"> 1189 <term> 1190 <mallctl>opt.junk</mallctl> 1191 (<type>const char *</type>) 1192 <literal>r-</literal> 1193 [<option>--enable-fill</option>] 1194 </term> 1195 <listitem><para>Junk filling. If set to <quote>alloc</quote>, each byte 1196 of uninitialized allocated memory will be initialized to 1197 <literal>0xa5</literal>. If set to <quote>free</quote>, all deallocated 1198 memory will be initialized to <literal>0x5a</literal>. If set to 1199 <quote>true</quote>, both allocated and deallocated memory will be 1200 initialized, and if set to <quote>false</quote>, junk filling be 1201 disabled entirely. This is intended for debugging and will impact 1202 performance negatively. This option is <quote>false</quote> by default 1203 unless <option>--enable-debug</option> is specified during 1204 configuration, in which case it is <quote>true</quote> by 1205 default.</para></listitem> 1206 </varlistentry> 1207 1208 <varlistentry id="opt.zero"> 1209 <term> 1210 <mallctl>opt.zero</mallctl> 1211 (<type>bool</type>) 1212 <literal>r-</literal> 1213 [<option>--enable-fill</option>] 1214 </term> 1215 <listitem><para>Zero filling enabled/disabled. If enabled, each byte 1216 of uninitialized allocated memory will be initialized to 0. Note that 1217 this initialization only happens once for each byte, so 1218 <function>realloc()</function> and 1219 <function>rallocx()</function> calls do not zero memory that 1220 was previously allocated. This is intended for debugging and will 1221 impact performance negatively. This option is disabled by default. 1222 </para></listitem> 1223 </varlistentry> 1224 1225 <varlistentry id="opt.utrace"> 1226 <term> 1227 <mallctl>opt.utrace</mallctl> 1228 (<type>bool</type>) 1229 <literal>r-</literal> 1230 [<option>--enable-utrace</option>] 1231 </term> 1232 <listitem><para>Allocation tracing based on 1233 <citerefentry><refentrytitle>utrace</refentrytitle> 1234 <manvolnum>2</manvolnum></citerefentry> enabled/disabled. This option 1235 is disabled by default.</para></listitem> 1236 </varlistentry> 1237 1238 <varlistentry id="opt.xmalloc"> 1239 <term> 1240 <mallctl>opt.xmalloc</mallctl> 1241 (<type>bool</type>) 1242 <literal>r-</literal> 1243 [<option>--enable-xmalloc</option>] 1244 </term> 1245 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled, 1246 rather than returning failure for any allocation function, display a 1247 diagnostic message on <constant>STDERR_FILENO</constant> and cause the 1248 program to drop core (using 1249 <citerefentry><refentrytitle>abort</refentrytitle> 1250 <manvolnum>3</manvolnum></citerefentry>). If an application is 1251 designed to depend on this behavior, set the option at compile time by 1252 including the following in the source code: 1253 <programlisting language="C"><![CDATA[ 1254malloc_conf = "xmalloc:true";]]></programlisting> 1255 This option is disabled by default.</para></listitem> 1256 </varlistentry> 1257 1258 <varlistentry id="opt.tcache"> 1259 <term> 1260 <mallctl>opt.tcache</mallctl> 1261 (<type>bool</type>) 1262 <literal>r-</literal> 1263 </term> 1264 <listitem><para>Thread-specific caching (tcache) enabled/disabled. When 1265 there are multiple threads, each thread uses a tcache for objects up to 1266 a certain size. Thread-specific caching allows many allocations to be 1267 satisfied without performing any thread synchronization, at the cost of 1268 increased memory use. See the <link 1269 linkend="opt.lg_tcache_max"><mallctl>opt.lg_tcache_max</mallctl></link> 1270 option for related tuning information. This option is enabled by 1271 default.</para></listitem> 1272 </varlistentry> 1273 1274 <varlistentry id="opt.lg_tcache_max"> 1275 <term> 1276 <mallctl>opt.lg_tcache_max</mallctl> 1277 (<type>size_t</type>) 1278 <literal>r-</literal> 1279 </term> 1280 <listitem><para>Maximum size class (log base 2) to cache in the 1281 thread-specific cache (tcache). At a minimum, all small size classes 1282 are cached, and at a maximum all large size classes are cached. The 1283 default maximum is 32 KiB (2^15).</para></listitem> 1284 </varlistentry> 1285 1286 <varlistentry id="opt.thp"> 1287 <term> 1288 <mallctl>opt.thp</mallctl> 1289 (<type>const char *</type>) 1290 <literal>r-</literal> 1291 </term> 1292 <listitem><para>Transparent hugepage (THP) mode. Settings "always", 1293 "never" and "default" are available if THP is supported by the operating 1294 system. The "always" setting enables transparent hugepage for all user 1295 memory mappings with 1296 <parameter><constant>MADV_HUGEPAGE</constant></parameter>; "never" 1297 ensures no transparent hugepage with 1298 <parameter><constant>MADV_NOHUGEPAGE</constant></parameter>; the default 1299 setting "default" makes no changes. Note that: this option does not 1300 affect THP for jemalloc internal metadata (see <link 1301 linkend="opt.metadata_thp"><mallctl>opt.metadata_thp</mallctl></link>); 1302 in addition, for arenas with customized <link 1303 linkend="arena.i.extent_hooks"><mallctl>extent_hooks</mallctl></link>, 1304 this option is bypassed as it is implemented as part of the default 1305 extent hooks.</para></listitem> 1306 </varlistentry> 1307 1308 <varlistentry id="opt.prof"> 1309 <term> 1310 <mallctl>opt.prof</mallctl> 1311 (<type>bool</type>) 1312 <literal>r-</literal> 1313 [<option>--enable-prof</option>] 1314 </term> 1315 <listitem><para>Memory profiling enabled/disabled. If enabled, profile 1316 memory allocation activity. See the <link 1317 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 1318 option for on-the-fly activation/deactivation. See the <link 1319 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 1320 option for probabilistic sampling control. See the <link 1321 linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> 1322 option for control of cumulative sample reporting. See the <link 1323 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 1324 option for information on interval-triggered profile dumping, the <link 1325 linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link> 1326 option for information on high-water-triggered profile dumping, and the 1327 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link> 1328 option for final profile dumping. Profile output is compatible with 1329 the <command>jeprof</command> command, which is based on the 1330 <command>pprof</command> that is developed as part of the <ulink 1331 url="http://code.google.com/p/gperftools/">gperftools 1332 package</ulink>. See <link linkend="heap_profile_format">HEAP PROFILE 1333 FORMAT</link> for heap profile format documentation.</para></listitem> 1334 </varlistentry> 1335 1336 <varlistentry id="opt.prof_prefix"> 1337 <term> 1338 <mallctl>opt.prof_prefix</mallctl> 1339 (<type>const char *</type>) 1340 <literal>r-</literal> 1341 [<option>--enable-prof</option>] 1342 </term> 1343 <listitem><para>Filename prefix for profile dumps. If the prefix is 1344 set to the empty string, no automatic dumps will occur; this is 1345 primarily useful for disabling the automatic final heap dump (which 1346 also disables leak reporting, if enabled). The default prefix is 1347 <filename>jeprof</filename>.</para></listitem> 1348 </varlistentry> 1349 1350 <varlistentry id="opt.prof_active"> 1351 <term> 1352 <mallctl>opt.prof_active</mallctl> 1353 (<type>bool</type>) 1354 <literal>r-</literal> 1355 [<option>--enable-prof</option>] 1356 </term> 1357 <listitem><para>Profiling activated/deactivated. This is a secondary 1358 control mechanism that makes it possible to start the application with 1359 profiling enabled (see the <link 1360 linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but 1361 inactive, then toggle profiling at any time during program execution 1362 with the <link 1363 linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl. 1364 This option is enabled by default.</para></listitem> 1365 </varlistentry> 1366 1367 <varlistentry id="opt.prof_thread_active_init"> 1368 <term> 1369 <mallctl>opt.prof_thread_active_init</mallctl> 1370 (<type>bool</type>) 1371 <literal>r-</literal> 1372 [<option>--enable-prof</option>] 1373 </term> 1374 <listitem><para>Initial setting for <link 1375 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 1376 in newly created threads. The initial setting for newly created threads 1377 can also be changed during execution via the <link 1378 linkend="prof.thread_active_init"><mallctl>prof.thread_active_init</mallctl></link> 1379 mallctl. This option is enabled by default.</para></listitem> 1380 </varlistentry> 1381 1382 <varlistentry id="opt.lg_prof_sample"> 1383 <term> 1384 <mallctl>opt.lg_prof_sample</mallctl> 1385 (<type>size_t</type>) 1386 <literal>r-</literal> 1387 [<option>--enable-prof</option>] 1388 </term> 1389 <listitem><para>Average interval (log base 2) between allocation 1390 samples, as measured in bytes of allocation activity. Increasing the 1391 sampling interval decreases profile fidelity, but also decreases the 1392 computational overhead. The default sample interval is 512 KiB (2^19 1393 B).</para></listitem> 1394 </varlistentry> 1395 1396 <varlistentry id="opt.prof_accum"> 1397 <term> 1398 <mallctl>opt.prof_accum</mallctl> 1399 (<type>bool</type>) 1400 <literal>r-</literal> 1401 [<option>--enable-prof</option>] 1402 </term> 1403 <listitem><para>Reporting of cumulative object/byte counts in profile 1404 dumps enabled/disabled. If this option is enabled, every unique 1405 backtrace must be stored for the duration of execution. Depending on 1406 the application, this can impose a large memory overhead, and the 1407 cumulative counts are not always of interest. This option is disabled 1408 by default.</para></listitem> 1409 </varlistentry> 1410 1411 <varlistentry id="opt.lg_prof_interval"> 1412 <term> 1413 <mallctl>opt.lg_prof_interval</mallctl> 1414 (<type>ssize_t</type>) 1415 <literal>r-</literal> 1416 [<option>--enable-prof</option>] 1417 </term> 1418 <listitem><para>Average interval (log base 2) between memory profile 1419 dumps, as measured in bytes of allocation activity. The actual 1420 interval between dumps may be sporadic because decentralized allocation 1421 counters are used to avoid synchronization bottlenecks. Profiles are 1422 dumped to files named according to the pattern 1423 <filename><prefix>.<pid>.<seq>.i<iseq>.heap</filename>, 1424 where <literal><prefix></literal> is controlled by the 1425 <link 1426 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1427 option. By default, interval-triggered profile dumping is disabled 1428 (encoded as -1). 1429 </para></listitem> 1430 </varlistentry> 1431 1432 <varlistentry id="opt.prof_gdump"> 1433 <term> 1434 <mallctl>opt.prof_gdump</mallctl> 1435 (<type>bool</type>) 1436 <literal>r-</literal> 1437 [<option>--enable-prof</option>] 1438 </term> 1439 <listitem><para>Set the initial state of <link 1440 linkend="prof.gdump"><mallctl>prof.gdump</mallctl></link>, which when 1441 enabled triggers a memory profile dump every time the total virtual 1442 memory exceeds the previous maximum. This option is disabled by 1443 default.</para></listitem> 1444 </varlistentry> 1445 1446 <varlistentry id="opt.prof_final"> 1447 <term> 1448 <mallctl>opt.prof_final</mallctl> 1449 (<type>bool</type>) 1450 <literal>r-</literal> 1451 [<option>--enable-prof</option>] 1452 </term> 1453 <listitem><para>Use an 1454 <citerefentry><refentrytitle>atexit</refentrytitle> 1455 <manvolnum>3</manvolnum></citerefentry> function to dump final memory 1456 usage to a file named according to the pattern 1457 <filename><prefix>.<pid>.<seq>.f.heap</filename>, 1458 where <literal><prefix></literal> is controlled by the <link 1459 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1460 option. Note that <function>atexit()</function> may allocate 1461 memory during application initialization and then deadlock internally 1462 when jemalloc in turn calls <function>atexit()</function>, so 1463 this option is not universally usable (though the application can 1464 register its own <function>atexit()</function> function with 1465 equivalent functionality). This option is disabled by 1466 default.</para></listitem> 1467 </varlistentry> 1468 1469 <varlistentry id="opt.prof_leak"> 1470 <term> 1471 <mallctl>opt.prof_leak</mallctl> 1472 (<type>bool</type>) 1473 <literal>r-</literal> 1474 [<option>--enable-prof</option>] 1475 </term> 1476 <listitem><para>Leak reporting enabled/disabled. If enabled, use an 1477 <citerefentry><refentrytitle>atexit</refentrytitle> 1478 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks 1479 detected by allocation sampling. See the 1480 <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for 1481 information on analyzing heap profile output. This option is disabled 1482 by default.</para></listitem> 1483 </varlistentry> 1484 1485 <varlistentry id="thread.arena"> 1486 <term> 1487 <mallctl>thread.arena</mallctl> 1488 (<type>unsigned</type>) 1489 <literal>rw</literal> 1490 </term> 1491 <listitem><para>Get or set the arena associated with the calling 1492 thread. If the specified arena was not initialized beforehand (see the 1493 <link 1494 linkend="arena.i.initialized"><mallctl>arena.i.initialized</mallctl></link> 1495 mallctl), it will be automatically initialized as a side effect of 1496 calling this interface.</para></listitem> 1497 </varlistentry> 1498 1499 <varlistentry id="thread.allocated"> 1500 <term> 1501 <mallctl>thread.allocated</mallctl> 1502 (<type>uint64_t</type>) 1503 <literal>r-</literal> 1504 [<option>--enable-stats</option>] 1505 </term> 1506 <listitem><para>Get the total number of bytes ever allocated by the 1507 calling thread. This counter has the potential to wrap around; it is 1508 up to the application to appropriately interpret the counter in such 1509 cases.</para></listitem> 1510 </varlistentry> 1511 1512 <varlistentry id="thread.allocatedp"> 1513 <term> 1514 <mallctl>thread.allocatedp</mallctl> 1515 (<type>uint64_t *</type>) 1516 <literal>r-</literal> 1517 [<option>--enable-stats</option>] 1518 </term> 1519 <listitem><para>Get a pointer to the the value that is returned by the 1520 <link 1521 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 1522 mallctl. This is useful for avoiding the overhead of repeated 1523 <function>mallctl*()</function> calls.</para></listitem> 1524 </varlistentry> 1525 1526 <varlistentry id="thread.deallocated"> 1527 <term> 1528 <mallctl>thread.deallocated</mallctl> 1529 (<type>uint64_t</type>) 1530 <literal>r-</literal> 1531 [<option>--enable-stats</option>] 1532 </term> 1533 <listitem><para>Get the total number of bytes ever deallocated by the 1534 calling thread. This counter has the potential to wrap around; it is 1535 up to the application to appropriately interpret the counter in such 1536 cases.</para></listitem> 1537 </varlistentry> 1538 1539 <varlistentry id="thread.deallocatedp"> 1540 <term> 1541 <mallctl>thread.deallocatedp</mallctl> 1542 (<type>uint64_t *</type>) 1543 <literal>r-</literal> 1544 [<option>--enable-stats</option>] 1545 </term> 1546 <listitem><para>Get a pointer to the the value that is returned by the 1547 <link 1548 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link> 1549 mallctl. This is useful for avoiding the overhead of repeated 1550 <function>mallctl*()</function> calls.</para></listitem> 1551 </varlistentry> 1552 1553 <varlistentry id="thread.tcache.enabled"> 1554 <term> 1555 <mallctl>thread.tcache.enabled</mallctl> 1556 (<type>bool</type>) 1557 <literal>rw</literal> 1558 </term> 1559 <listitem><para>Enable/disable calling thread's tcache. The tcache is 1560 implicitly flushed as a side effect of becoming 1561 disabled (see <link 1562 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>). 1563 </para></listitem> 1564 </varlistentry> 1565 1566 <varlistentry id="thread.tcache.flush"> 1567 <term> 1568 <mallctl>thread.tcache.flush</mallctl> 1569 (<type>void</type>) 1570 <literal>--</literal> 1571 </term> 1572 <listitem><para>Flush calling thread's thread-specific cache (tcache). 1573 This interface releases all cached objects and internal data structures 1574 associated with the calling thread's tcache. Ordinarily, this interface 1575 need not be called, since automatic periodic incremental garbage 1576 collection occurs, and the thread cache is automatically discarded when 1577 a thread exits. However, garbage collection is triggered by allocation 1578 activity, so it is possible for a thread that stops 1579 allocating/deallocating to retain its cache indefinitely, in which case 1580 the developer may find manual flushing useful.</para></listitem> 1581 </varlistentry> 1582 1583 <varlistentry id="thread.prof.name"> 1584 <term> 1585 <mallctl>thread.prof.name</mallctl> 1586 (<type>const char *</type>) 1587 <literal>r-</literal> or 1588 <literal>-w</literal> 1589 [<option>--enable-prof</option>] 1590 </term> 1591 <listitem><para>Get/set the descriptive name associated with the calling 1592 thread in memory profile dumps. An internal copy of the name string is 1593 created, so the input string need not be maintained after this interface 1594 completes execution. The output string of this interface should be 1595 copied for non-ephemeral uses, because multiple implementation details 1596 can cause asynchronous string deallocation. Furthermore, each 1597 invocation of this interface can only read or write; simultaneous 1598 read/write is not supported due to string lifetime limitations. The 1599 name string must be nil-terminated and comprised only of characters in 1600 the sets recognized 1601 by <citerefentry><refentrytitle>isgraph</refentrytitle> 1602 <manvolnum>3</manvolnum></citerefentry> and 1603 <citerefentry><refentrytitle>isblank</refentrytitle> 1604 <manvolnum>3</manvolnum></citerefentry>.</para></listitem> 1605 </varlistentry> 1606 1607 <varlistentry id="thread.prof.active"> 1608 <term> 1609 <mallctl>thread.prof.active</mallctl> 1610 (<type>bool</type>) 1611 <literal>rw</literal> 1612 [<option>--enable-prof</option>] 1613 </term> 1614 <listitem><para>Control whether sampling is currently active for the 1615 calling thread. This is an activation mechanism in addition to <link 1616 linkend="prof.active"><mallctl>prof.active</mallctl></link>; both must 1617 be active for the calling thread to sample. This flag is enabled by 1618 default.</para></listitem> 1619 </varlistentry> 1620 1621 <varlistentry id="tcache.create"> 1622 <term> 1623 <mallctl>tcache.create</mallctl> 1624 (<type>unsigned</type>) 1625 <literal>r-</literal> 1626 </term> 1627 <listitem><para>Create an explicit thread-specific cache (tcache) and 1628 return an identifier that can be passed to the <link 1629 linkend="MALLOCX_TCACHE"><constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant></link> 1630 macro to explicitly use the specified cache rather than the 1631 automatically managed one that is used by default. Each explicit cache 1632 can be used by only one thread at a time; the application must assure 1633 that this constraint holds. 1634 </para></listitem> 1635 </varlistentry> 1636 1637 <varlistentry id="tcache.flush"> 1638 <term> 1639 <mallctl>tcache.flush</mallctl> 1640 (<type>unsigned</type>) 1641 <literal>-w</literal> 1642 </term> 1643 <listitem><para>Flush the specified thread-specific cache (tcache). The 1644 same considerations apply to this interface as to <link 1645 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>, 1646 except that the tcache will never be automatically discarded. 1647 </para></listitem> 1648 </varlistentry> 1649 1650 <varlistentry id="tcache.destroy"> 1651 <term> 1652 <mallctl>tcache.destroy</mallctl> 1653 (<type>unsigned</type>) 1654 <literal>-w</literal> 1655 </term> 1656 <listitem><para>Flush the specified thread-specific cache (tcache) and 1657 make the identifier available for use during a future tcache creation. 1658 </para></listitem> 1659 </varlistentry> 1660 1661 <varlistentry id="arena.i.initialized"> 1662 <term> 1663 <mallctl>arena.<i>.initialized</mallctl> 1664 (<type>bool</type>) 1665 <literal>r-</literal> 1666 </term> 1667 <listitem><para>Get whether the specified arena's statistics are 1668 initialized (i.e. the arena was initialized prior to the current epoch). 1669 This interface can also be nominally used to query whether the merged 1670 statistics corresponding to <constant>MALLCTL_ARENAS_ALL</constant> are 1671 initialized (always true).</para></listitem> 1672 </varlistentry> 1673 1674 <varlistentry id="arena.i.decay"> 1675 <term> 1676 <mallctl>arena.<i>.decay</mallctl> 1677 (<type>void</type>) 1678 <literal>--</literal> 1679 </term> 1680 <listitem><para>Trigger decay-based purging of unused dirty/muzzy pages 1681 for arena <i>, or for all arenas if <i> equals 1682 <constant>MALLCTL_ARENAS_ALL</constant>. The proportion of unused 1683 dirty/muzzy pages to be purged depends on the current time; see <link 1684 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 1685 and <link 1686 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzy_decay_ms</mallctl></link> 1687 for details.</para></listitem> 1688 </varlistentry> 1689 1690 <varlistentry id="arena.i.purge"> 1691 <term> 1692 <mallctl>arena.<i>.purge</mallctl> 1693 (<type>void</type>) 1694 <literal>--</literal> 1695 </term> 1696 <listitem><para>Purge all unused dirty pages for arena <i>, or for 1697 all arenas if <i> equals <constant>MALLCTL_ARENAS_ALL</constant>. 1698 </para></listitem> 1699 </varlistentry> 1700 1701 <varlistentry id="arena.i.reset"> 1702 <term> 1703 <mallctl>arena.<i>.reset</mallctl> 1704 (<type>void</type>) 1705 <literal>--</literal> 1706 </term> 1707 <listitem><para>Discard all of the arena's extant allocations. This 1708 interface can only be used with arenas explicitly created via <link 1709 linkend="arenas.create"><mallctl>arenas.create</mallctl></link>. None 1710 of the arena's discarded/cached allocations may accessed afterward. As 1711 part of this requirement, all thread caches which were used to 1712 allocate/deallocate in conjunction with the arena must be flushed 1713 beforehand.</para></listitem> 1714 </varlistentry> 1715 1716 <varlistentry id="arena.i.destroy"> 1717 <term> 1718 <mallctl>arena.<i>.destroy</mallctl> 1719 (<type>void</type>) 1720 <literal>--</literal> 1721 </term> 1722 <listitem><para>Destroy the arena. Discard all of the arena's extant 1723 allocations using the same mechanism as for <link 1724 linkend="arena.i.reset"><mallctl>arena.<i>.reset</mallctl></link> 1725 (with all the same constraints and side effects), merge the arena stats 1726 into those accessible at arena index 1727 <constant>MALLCTL_ARENAS_DESTROYED</constant>, and then completely 1728 discard all metadata associated with the arena. Future calls to <link 1729 linkend="arenas.create"><mallctl>arenas.create</mallctl></link> may 1730 recycle the arena index. Destruction will fail if any threads are 1731 currently associated with the arena as a result of calls to <link 1732 linkend="thread.arena"><mallctl>thread.arena</mallctl></link>.</para></listitem> 1733 </varlistentry> 1734 1735 <varlistentry id="arena.i.dss"> 1736 <term> 1737 <mallctl>arena.<i>.dss</mallctl> 1738 (<type>const char *</type>) 1739 <literal>rw</literal> 1740 </term> 1741 <listitem><para>Set the precedence of dss allocation as related to mmap 1742 allocation for arena <i>, or for all arenas if <i> equals 1743 <constant>MALLCTL_ARENAS_ALL</constant>. See <link 1744 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for supported 1745 settings.</para></listitem> 1746 </varlistentry> 1747 1748 <varlistentry id="arena.i.dirty_decay_ms"> 1749 <term> 1750 <mallctl>arena.<i>.dirty_decay_ms</mallctl> 1751 (<type>ssize_t</type>) 1752 <literal>rw</literal> 1753 </term> 1754 <listitem><para>Current per-arena approximate time in milliseconds from 1755 the creation of a set of unused dirty pages until an equivalent set of 1756 unused dirty pages is purged and/or reused. Each time this interface is 1757 set, all currently unused dirty pages are considered to have fully 1758 decayed, which causes immediate purging of all unused dirty pages unless 1759 the decay time is set to -1 (i.e. purging disabled). See <link 1760 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 1761 for additional information.</para></listitem> 1762 </varlistentry> 1763 1764 <varlistentry id="arena.i.muzzy_decay_ms"> 1765 <term> 1766 <mallctl>arena.<i>.muzzy_decay_ms</mallctl> 1767 (<type>ssize_t</type>) 1768 <literal>rw</literal> 1769 </term> 1770 <listitem><para>Current per-arena approximate time in milliseconds from 1771 the creation of a set of unused muzzy pages until an equivalent set of 1772 unused muzzy pages is purged and/or reused. Each time this interface is 1773 set, all currently unused muzzy pages are considered to have fully 1774 decayed, which causes immediate purging of all unused muzzy pages unless 1775 the decay time is set to -1 (i.e. purging disabled). See <link 1776 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 1777 for additional information.</para></listitem> 1778 </varlistentry> 1779 1780 <varlistentry id="arena.i.retain_grow_limit"> 1781 <term> 1782 <mallctl>arena.<i>.retain_grow_limit</mallctl> 1783 (<type>size_t</type>) 1784 <literal>rw</literal> 1785 </term> 1786 <listitem><para>Maximum size to grow retained region (only relevant when 1787 <link linkend="opt.retain"><mallctl>opt.retain</mallctl></link> is 1788 enabled). This controls the maximum increment to expand virtual memory, 1789 or allocation through <link 1790 linkend="arena.i.extent_hooks"><mallctl>arena.<i>extent_hooks</mallctl></link>. 1791 In particular, if customized extent hooks reserve physical memory 1792 (e.g. 1G huge pages), this is useful to control the allocation hook's 1793 input size. The default is no limit.</para></listitem> 1794 </varlistentry> 1795 1796 <varlistentry id="arena.i.extent_hooks"> 1797 <term> 1798 <mallctl>arena.<i>.extent_hooks</mallctl> 1799 (<type>extent_hooks_t *</type>) 1800 <literal>rw</literal> 1801 </term> 1802 <listitem><para>Get or set the extent management hook functions for 1803 arena <i>. The functions must be capable of operating on all 1804 extant extents associated with arena <i>, usually by passing 1805 unknown extents to the replaced functions. In practice, it is feasible 1806 to control allocation for arenas explicitly created via <link 1807 linkend="arenas.create"><mallctl>arenas.create</mallctl></link> such 1808 that all extents originate from an application-supplied extent allocator 1809 (by specifying the custom extent hook functions during arena creation). 1810 However, the API guarantees for the automatically created arenas may be 1811 relaxed -- hooks set there may be called in a "best effort" fashion; in 1812 addition there may be extents created prior to the application having an 1813 opportunity to take over extent allocation.</para> 1814 1815 <programlisting language="C"><![CDATA[ 1816typedef extent_hooks_s extent_hooks_t; 1817struct extent_hooks_s { 1818 extent_alloc_t *alloc; 1819 extent_dalloc_t *dalloc; 1820 extent_destroy_t *destroy; 1821 extent_commit_t *commit; 1822 extent_decommit_t *decommit; 1823 extent_purge_t *purge_lazy; 1824 extent_purge_t *purge_forced; 1825 extent_split_t *split; 1826 extent_merge_t *merge; 1827};]]></programlisting> 1828 <para>The <type>extent_hooks_t</type> structure comprises function 1829 pointers which are described individually below. jemalloc uses these 1830 functions to manage extent lifetime, which starts off with allocation of 1831 mapped committed memory, in the simplest case followed by deallocation. 1832 However, there are performance and platform reasons to retain extents 1833 for later reuse. Cleanup attempts cascade from deallocation to decommit 1834 to forced purging to lazy purging, which gives the extent management 1835 functions opportunities to reject the most permanent cleanup operations 1836 in favor of less permanent (and often less costly) operations. All 1837 operations except allocation can be universally opted out of by setting 1838 the hook pointers to <constant>NULL</constant>, or selectively opted out 1839 of by returning failure. Note that once the extent hook is set, the 1840 structure is accessed directly by the associated arenas, so it must 1841 remain valid for the entire lifetime of the arenas.</para> 1842 1843 <funcsynopsis><funcprototype> 1844 <funcdef>typedef void *<function>(extent_alloc_t)</function></funcdef> 1845 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 1846 <paramdef>void *<parameter>new_addr</parameter></paramdef> 1847 <paramdef>size_t <parameter>size</parameter></paramdef> 1848 <paramdef>size_t <parameter>alignment</parameter></paramdef> 1849 <paramdef>bool *<parameter>zero</parameter></paramdef> 1850 <paramdef>bool *<parameter>commit</parameter></paramdef> 1851 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1852 </funcprototype></funcsynopsis> 1853 <literallayout></literallayout> 1854 <para>An extent allocation function conforms to the 1855 <type>extent_alloc_t</type> type and upon success returns a pointer to 1856 <parameter>size</parameter> bytes of mapped memory on behalf of arena 1857 <parameter>arena_ind</parameter> such that the extent's base address is 1858 a multiple of <parameter>alignment</parameter>, as well as setting 1859 <parameter>*zero</parameter> to indicate whether the extent is zeroed 1860 and <parameter>*commit</parameter> to indicate whether the extent is 1861 committed. Upon error the function returns <constant>NULL</constant> 1862 and leaves <parameter>*zero</parameter> and 1863 <parameter>*commit</parameter> unmodified. The 1864 <parameter>size</parameter> parameter is always a multiple of the page 1865 size. The <parameter>alignment</parameter> parameter is always a power 1866 of two at least as large as the page size. Zeroing is mandatory if 1867 <parameter>*zero</parameter> is true upon function entry. Committing is 1868 mandatory if <parameter>*commit</parameter> is true upon function entry. 1869 If <parameter>new_addr</parameter> is not <constant>NULL</constant>, the 1870 returned pointer must be <parameter>new_addr</parameter> on success or 1871 <constant>NULL</constant> on error. Committed memory may be committed 1872 in absolute terms as on a system that does not overcommit, or in 1873 implicit terms as on a system that overcommits and satisfies physical 1874 memory needs on demand via soft page faults. Note that replacing the 1875 default extent allocation function makes the arena's <link 1876 linkend="arena.i.dss"><mallctl>arena.<i>.dss</mallctl></link> 1877 setting irrelevant.</para> 1878 1879 <funcsynopsis><funcprototype> 1880 <funcdef>typedef bool <function>(extent_dalloc_t)</function></funcdef> 1881 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 1882 <paramdef>void *<parameter>addr</parameter></paramdef> 1883 <paramdef>size_t <parameter>size</parameter></paramdef> 1884 <paramdef>bool <parameter>committed</parameter></paramdef> 1885 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1886 </funcprototype></funcsynopsis> 1887 <literallayout></literallayout> 1888 <para> 1889 An extent deallocation function conforms to the 1890 <type>extent_dalloc_t</type> type and deallocates an extent at given 1891 <parameter>addr</parameter> and <parameter>size</parameter> with 1892 <parameter>committed</parameter>/decommited memory as indicated, on 1893 behalf of arena <parameter>arena_ind</parameter>, returning false upon 1894 success. If the function returns true, this indicates opt-out from 1895 deallocation; the virtual memory mapping associated with the extent 1896 remains mapped, in the same commit state, and available for future use, 1897 in which case it will be automatically retained for later reuse.</para> 1898 1899 <funcsynopsis><funcprototype> 1900 <funcdef>typedef void <function>(extent_destroy_t)</function></funcdef> 1901 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 1902 <paramdef>void *<parameter>addr</parameter></paramdef> 1903 <paramdef>size_t <parameter>size</parameter></paramdef> 1904 <paramdef>bool <parameter>committed</parameter></paramdef> 1905 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1906 </funcprototype></funcsynopsis> 1907 <literallayout></literallayout> 1908 <para> 1909 An extent destruction function conforms to the 1910 <type>extent_destroy_t</type> type and unconditionally destroys an 1911 extent at given <parameter>addr</parameter> and 1912 <parameter>size</parameter> with 1913 <parameter>committed</parameter>/decommited memory as indicated, on 1914 behalf of arena <parameter>arena_ind</parameter>. This function may be 1915 called to destroy retained extents during arena destruction (see <link 1916 linkend="arena.i.destroy"><mallctl>arena.<i>.destroy</mallctl></link>).</para> 1917 1918 <funcsynopsis><funcprototype> 1919 <funcdef>typedef bool <function>(extent_commit_t)</function></funcdef> 1920 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 1921 <paramdef>void *<parameter>addr</parameter></paramdef> 1922 <paramdef>size_t <parameter>size</parameter></paramdef> 1923 <paramdef>size_t <parameter>offset</parameter></paramdef> 1924 <paramdef>size_t <parameter>length</parameter></paramdef> 1925 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1926 </funcprototype></funcsynopsis> 1927 <literallayout></literallayout> 1928 <para>An extent commit function conforms to the 1929 <type>extent_commit_t</type> type and commits zeroed physical memory to 1930 back pages within an extent at given <parameter>addr</parameter> and 1931 <parameter>size</parameter> at <parameter>offset</parameter> bytes, 1932 extending for <parameter>length</parameter> on behalf of arena 1933 <parameter>arena_ind</parameter>, returning false upon success. 1934 Committed memory may be committed in absolute terms as on a system that 1935 does not overcommit, or in implicit terms as on a system that 1936 overcommits and satisfies physical memory needs on demand via soft page 1937 faults. If the function returns true, this indicates insufficient 1938 physical memory to satisfy the request.</para> 1939 1940 <funcsynopsis><funcprototype> 1941 <funcdef>typedef bool <function>(extent_decommit_t)</function></funcdef> 1942 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 1943 <paramdef>void *<parameter>addr</parameter></paramdef> 1944 <paramdef>size_t <parameter>size</parameter></paramdef> 1945 <paramdef>size_t <parameter>offset</parameter></paramdef> 1946 <paramdef>size_t <parameter>length</parameter></paramdef> 1947 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1948 </funcprototype></funcsynopsis> 1949 <literallayout></literallayout> 1950 <para>An extent decommit function conforms to the 1951 <type>extent_decommit_t</type> type and decommits any physical memory 1952 that is backing pages within an extent at given 1953 <parameter>addr</parameter> and <parameter>size</parameter> at 1954 <parameter>offset</parameter> bytes, extending for 1955 <parameter>length</parameter> on behalf of arena 1956 <parameter>arena_ind</parameter>, returning false upon success, in which 1957 case the pages will be committed via the extent commit function before 1958 being reused. If the function returns true, this indicates opt-out from 1959 decommit; the memory remains committed and available for future use, in 1960 which case it will be automatically retained for later reuse.</para> 1961 1962 <funcsynopsis><funcprototype> 1963 <funcdef>typedef bool <function>(extent_purge_t)</function></funcdef> 1964 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 1965 <paramdef>void *<parameter>addr</parameter></paramdef> 1966 <paramdef>size_t <parameter>size</parameter></paramdef> 1967 <paramdef>size_t <parameter>offset</parameter></paramdef> 1968 <paramdef>size_t <parameter>length</parameter></paramdef> 1969 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1970 </funcprototype></funcsynopsis> 1971 <literallayout></literallayout> 1972 <para>An extent purge function conforms to the 1973 <type>extent_purge_t</type> type and discards physical pages 1974 within the virtual memory mapping associated with an extent at given 1975 <parameter>addr</parameter> and <parameter>size</parameter> at 1976 <parameter>offset</parameter> bytes, extending for 1977 <parameter>length</parameter> on behalf of arena 1978 <parameter>arena_ind</parameter>. A lazy extent purge function (e.g. 1979 implemented via 1980 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function>) 1981 can delay purging indefinitely and leave the pages within the purged 1982 virtual memory range in an indeterminite state, whereas a forced extent 1983 purge function immediately purges, and the pages within the virtual 1984 memory range will be zero-filled the next time they are accessed. If 1985 the function returns true, this indicates failure to purge.</para> 1986 1987 <funcsynopsis><funcprototype> 1988 <funcdef>typedef bool <function>(extent_split_t)</function></funcdef> 1989 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 1990 <paramdef>void *<parameter>addr</parameter></paramdef> 1991 <paramdef>size_t <parameter>size</parameter></paramdef> 1992 <paramdef>size_t <parameter>size_a</parameter></paramdef> 1993 <paramdef>size_t <parameter>size_b</parameter></paramdef> 1994 <paramdef>bool <parameter>committed</parameter></paramdef> 1995 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 1996 </funcprototype></funcsynopsis> 1997 <literallayout></literallayout> 1998 <para>An extent split function conforms to the 1999 <type>extent_split_t</type> type and optionally splits an extent at 2000 given <parameter>addr</parameter> and <parameter>size</parameter> into 2001 two adjacent extents, the first of <parameter>size_a</parameter> bytes, 2002 and the second of <parameter>size_b</parameter> bytes, operating on 2003 <parameter>committed</parameter>/decommitted memory as indicated, on 2004 behalf of arena <parameter>arena_ind</parameter>, returning false upon 2005 success. If the function returns true, this indicates that the extent 2006 remains unsplit and therefore should continue to be operated on as a 2007 whole.</para> 2008 2009 <funcsynopsis><funcprototype> 2010 <funcdef>typedef bool <function>(extent_merge_t)</function></funcdef> 2011 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2012 <paramdef>void *<parameter>addr_a</parameter></paramdef> 2013 <paramdef>size_t <parameter>size_a</parameter></paramdef> 2014 <paramdef>void *<parameter>addr_b</parameter></paramdef> 2015 <paramdef>size_t <parameter>size_b</parameter></paramdef> 2016 <paramdef>bool <parameter>committed</parameter></paramdef> 2017 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2018 </funcprototype></funcsynopsis> 2019 <literallayout></literallayout> 2020 <para>An extent merge function conforms to the 2021 <type>extent_merge_t</type> type and optionally merges adjacent extents, 2022 at given <parameter>addr_a</parameter> and <parameter>size_a</parameter> 2023 with given <parameter>addr_b</parameter> and 2024 <parameter>size_b</parameter> into one contiguous extent, operating on 2025 <parameter>committed</parameter>/decommitted memory as indicated, on 2026 behalf of arena <parameter>arena_ind</parameter>, returning false upon 2027 success. If the function returns true, this indicates that the extents 2028 remain distinct mappings and therefore should continue to be operated on 2029 independently.</para> 2030 </listitem> 2031 </varlistentry> 2032 2033 <varlistentry id="arenas.narenas"> 2034 <term> 2035 <mallctl>arenas.narenas</mallctl> 2036 (<type>unsigned</type>) 2037 <literal>r-</literal> 2038 </term> 2039 <listitem><para>Current limit on number of arenas.</para></listitem> 2040 </varlistentry> 2041 2042 <varlistentry id="arenas.dirty_decay_ms"> 2043 <term> 2044 <mallctl>arenas.dirty_decay_ms</mallctl> 2045 (<type>ssize_t</type>) 2046 <literal>rw</literal> 2047 </term> 2048 <listitem><para>Current default per-arena approximate time in 2049 milliseconds from the creation of a set of unused dirty pages until an 2050 equivalent set of unused dirty pages is purged and/or reused, used to 2051 initialize <link 2052 linkend="arena.i.dirty_decay_ms"><mallctl>arena.<i>.dirty_decay_ms</mallctl></link> 2053 during arena creation. See <link 2054 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2055 for additional information.</para></listitem> 2056 </varlistentry> 2057 2058 <varlistentry id="arenas.muzzy_decay_ms"> 2059 <term> 2060 <mallctl>arenas.muzzy_decay_ms</mallctl> 2061 (<type>ssize_t</type>) 2062 <literal>rw</literal> 2063 </term> 2064 <listitem><para>Current default per-arena approximate time in 2065 milliseconds from the creation of a set of unused muzzy pages until an 2066 equivalent set of unused muzzy pages is purged and/or reused, used to 2067 initialize <link 2068 linkend="arena.i.muzzy_decay_ms"><mallctl>arena.<i>.muzzy_decay_ms</mallctl></link> 2069 during arena creation. See <link 2070 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2071 for additional information.</para></listitem> 2072 </varlistentry> 2073 2074 <varlistentry id="arenas.quantum"> 2075 <term> 2076 <mallctl>arenas.quantum</mallctl> 2077 (<type>size_t</type>) 2078 <literal>r-</literal> 2079 </term> 2080 <listitem><para>Quantum size.</para></listitem> 2081 </varlistentry> 2082 2083 <varlistentry id="arenas.page"> 2084 <term> 2085 <mallctl>arenas.page</mallctl> 2086 (<type>size_t</type>) 2087 <literal>r-</literal> 2088 </term> 2089 <listitem><para>Page size.</para></listitem> 2090 </varlistentry> 2091 2092 <varlistentry id="arenas.tcache_max"> 2093 <term> 2094 <mallctl>arenas.tcache_max</mallctl> 2095 (<type>size_t</type>) 2096 <literal>r-</literal> 2097 </term> 2098 <listitem><para>Maximum thread-cached size class.</para></listitem> 2099 </varlistentry> 2100 2101 <varlistentry id="arenas.nbins"> 2102 <term> 2103 <mallctl>arenas.nbins</mallctl> 2104 (<type>unsigned</type>) 2105 <literal>r-</literal> 2106 </term> 2107 <listitem><para>Number of bin size classes.</para></listitem> 2108 </varlistentry> 2109 2110 <varlistentry id="arenas.nhbins"> 2111 <term> 2112 <mallctl>arenas.nhbins</mallctl> 2113 (<type>unsigned</type>) 2114 <literal>r-</literal> 2115 </term> 2116 <listitem><para>Total number of thread cache bin size 2117 classes.</para></listitem> 2118 </varlistentry> 2119 2120 <varlistentry id="arenas.bin.i.size"> 2121 <term> 2122 <mallctl>arenas.bin.<i>.size</mallctl> 2123 (<type>size_t</type>) 2124 <literal>r-</literal> 2125 </term> 2126 <listitem><para>Maximum size supported by size class.</para></listitem> 2127 </varlistentry> 2128 2129 <varlistentry id="arenas.bin.i.nregs"> 2130 <term> 2131 <mallctl>arenas.bin.<i>.nregs</mallctl> 2132 (<type>uint32_t</type>) 2133 <literal>r-</literal> 2134 </term> 2135 <listitem><para>Number of regions per slab.</para></listitem> 2136 </varlistentry> 2137 2138 <varlistentry id="arenas.bin.i.slab_size"> 2139 <term> 2140 <mallctl>arenas.bin.<i>.slab_size</mallctl> 2141 (<type>size_t</type>) 2142 <literal>r-</literal> 2143 </term> 2144 <listitem><para>Number of bytes per slab.</para></listitem> 2145 </varlistentry> 2146 2147 <varlistentry id="arenas.nlextents"> 2148 <term> 2149 <mallctl>arenas.nlextents</mallctl> 2150 (<type>unsigned</type>) 2151 <literal>r-</literal> 2152 </term> 2153 <listitem><para>Total number of large size classes.</para></listitem> 2154 </varlistentry> 2155 2156 <varlistentry id="arenas.lextent.i.size"> 2157 <term> 2158 <mallctl>arenas.lextent.<i>.size</mallctl> 2159 (<type>size_t</type>) 2160 <literal>r-</literal> 2161 </term> 2162 <listitem><para>Maximum size supported by this large size 2163 class.</para></listitem> 2164 </varlistentry> 2165 2166 <varlistentry id="arenas.create"> 2167 <term> 2168 <mallctl>arenas.create</mallctl> 2169 (<type>unsigned</type>, <type>extent_hooks_t *</type>) 2170 <literal>rw</literal> 2171 </term> 2172 <listitem><para>Explicitly create a new arena outside the range of 2173 automatically managed arenas, with optionally specified extent hooks, 2174 and return the new arena index.</para></listitem> 2175 </varlistentry> 2176 2177 <varlistentry id="arenas.lookup"> 2178 <term> 2179 <mallctl>arenas.lookup</mallctl> 2180 (<type>unsigned</type>, <type>void*</type>) 2181 <literal>rw</literal> 2182 </term> 2183 <listitem><para>Index of the arena to which an allocation belongs to.</para></listitem> 2184 </varlistentry> 2185 2186 <varlistentry id="prof.thread_active_init"> 2187 <term> 2188 <mallctl>prof.thread_active_init</mallctl> 2189 (<type>bool</type>) 2190 <literal>rw</literal> 2191 [<option>--enable-prof</option>] 2192 </term> 2193 <listitem><para>Control the initial setting for <link 2194 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 2195 in newly created threads. See the <link 2196 linkend="opt.prof_thread_active_init"><mallctl>opt.prof_thread_active_init</mallctl></link> 2197 option for additional information.</para></listitem> 2198 </varlistentry> 2199 2200 <varlistentry id="prof.active"> 2201 <term> 2202 <mallctl>prof.active</mallctl> 2203 (<type>bool</type>) 2204 <literal>rw</literal> 2205 [<option>--enable-prof</option>] 2206 </term> 2207 <listitem><para>Control whether sampling is currently active. See the 2208 <link 2209 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 2210 option for additional information, as well as the interrelated <link 2211 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 2212 mallctl.</para></listitem> 2213 </varlistentry> 2214 2215 <varlistentry id="prof.dump"> 2216 <term> 2217 <mallctl>prof.dump</mallctl> 2218 (<type>const char *</type>) 2219 <literal>-w</literal> 2220 [<option>--enable-prof</option>] 2221 </term> 2222 <listitem><para>Dump a memory profile to the specified file, or if NULL 2223 is specified, to a file according to the pattern 2224 <filename><prefix>.<pid>.<seq>.m<mseq>.heap</filename>, 2225 where <literal><prefix></literal> is controlled by the 2226 <link 2227 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 2228 option.</para></listitem> 2229 </varlistentry> 2230 2231 <varlistentry id="prof.gdump"> 2232 <term> 2233 <mallctl>prof.gdump</mallctl> 2234 (<type>bool</type>) 2235 <literal>rw</literal> 2236 [<option>--enable-prof</option>] 2237 </term> 2238 <listitem><para>When enabled, trigger a memory profile dump every time 2239 the total virtual memory exceeds the previous maximum. Profiles are 2240 dumped to files named according to the pattern 2241 <filename><prefix>.<pid>.<seq>.u<useq>.heap</filename>, 2242 where <literal><prefix></literal> is controlled by the <link 2243 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 2244 option.</para></listitem> 2245 </varlistentry> 2246 2247 <varlistentry id="prof.reset"> 2248 <term> 2249 <mallctl>prof.reset</mallctl> 2250 (<type>size_t</type>) 2251 <literal>-w</literal> 2252 [<option>--enable-prof</option>] 2253 </term> 2254 <listitem><para>Reset all memory profile statistics, and optionally 2255 update the sample rate (see <link 2256 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 2257 and <link 2258 linkend="prof.lg_sample"><mallctl>prof.lg_sample</mallctl></link>). 2259 </para></listitem> 2260 </varlistentry> 2261 2262 <varlistentry id="prof.lg_sample"> 2263 <term> 2264 <mallctl>prof.lg_sample</mallctl> 2265 (<type>size_t</type>) 2266 <literal>r-</literal> 2267 [<option>--enable-prof</option>] 2268 </term> 2269 <listitem><para>Get the current sample rate (see <link 2270 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link>). 2271 </para></listitem> 2272 </varlistentry> 2273 2274 <varlistentry id="prof.interval"> 2275 <term> 2276 <mallctl>prof.interval</mallctl> 2277 (<type>uint64_t</type>) 2278 <literal>r-</literal> 2279 [<option>--enable-prof</option>] 2280 </term> 2281 <listitem><para>Average number of bytes allocated between 2282 interval-based profile dumps. See the 2283 <link 2284 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 2285 option for additional information.</para></listitem> 2286 </varlistentry> 2287 2288 <varlistentry id="stats.allocated"> 2289 <term> 2290 <mallctl>stats.allocated</mallctl> 2291 (<type>size_t</type>) 2292 <literal>r-</literal> 2293 [<option>--enable-stats</option>] 2294 </term> 2295 <listitem><para>Total number of bytes allocated by the 2296 application.</para></listitem> 2297 </varlistentry> 2298 2299 <varlistentry id="stats.active"> 2300 <term> 2301 <mallctl>stats.active</mallctl> 2302 (<type>size_t</type>) 2303 <literal>r-</literal> 2304 [<option>--enable-stats</option>] 2305 </term> 2306 <listitem><para>Total number of bytes in active pages allocated by the 2307 application. This is a multiple of the page size, and greater than or 2308 equal to <link 2309 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>. 2310 This does not include <link linkend="stats.arenas.i.pdirty"> 2311 <mallctl>stats.arenas.<i>.pdirty</mallctl></link>, 2312 <link linkend="stats.arenas.i.pmuzzy"> 2313 <mallctl>stats.arenas.<i>.pmuzzy</mallctl></link>, nor pages 2314 entirely devoted to allocator metadata.</para></listitem> 2315 </varlistentry> 2316 2317 <varlistentry id="stats.metadata"> 2318 <term> 2319 <mallctl>stats.metadata</mallctl> 2320 (<type>size_t</type>) 2321 <literal>r-</literal> 2322 [<option>--enable-stats</option>] 2323 </term> 2324 <listitem><para>Total number of bytes dedicated to metadata, which 2325 comprise base allocations used for bootstrap-sensitive allocator 2326 metadata structures (see <link 2327 linkend="stats.arenas.i.base"><mallctl>stats.arenas.<i>.base</mallctl></link>) 2328 and internal allocations (see <link 2329 linkend="stats.arenas.i.internal"><mallctl>stats.arenas.<i>.internal</mallctl></link>). 2330 Transparent huge page (enabled with <link 2331 linkend="opt.metadata_thp">opt.metadata_thp</link>) usage is not 2332 considered.</para></listitem> 2333 </varlistentry> 2334 2335 <varlistentry id="stats.metadata_thp"> 2336 <term> 2337 <mallctl>stats.metadata_thp</mallctl> 2338 (<type>size_t</type>) 2339 <literal>r-</literal> 2340 [<option>--enable-stats</option>] 2341 </term> 2342 <listitem><para>Number of transparent huge pages (THP) used for 2343 metadata. See <link 2344 linkend="stats.metadata"><mallctl>stats.metadata</mallctl></link> and 2345 <link linkend="opt.metadata_thp">opt.metadata_thp</link>) for 2346 details.</para></listitem> 2347 </varlistentry> 2348 2349 <varlistentry id="stats.resident"> 2350 <term> 2351 <mallctl>stats.resident</mallctl> 2352 (<type>size_t</type>) 2353 <literal>r-</literal> 2354 [<option>--enable-stats</option>] 2355 </term> 2356 <listitem><para>Maximum number of bytes in physically resident data 2357 pages mapped by the allocator, comprising all pages dedicated to 2358 allocator metadata, pages backing active allocations, and unused dirty 2359 pages. This is a maximum rather than precise because pages may not 2360 actually be physically resident if they correspond to demand-zeroed 2361 virtual memory that has not yet been touched. This is a multiple of the 2362 page size, and is larger than <link 2363 linkend="stats.active"><mallctl>stats.active</mallctl></link>.</para></listitem> 2364 </varlistentry> 2365 2366 <varlistentry id="stats.mapped"> 2367 <term> 2368 <mallctl>stats.mapped</mallctl> 2369 (<type>size_t</type>) 2370 <literal>r-</literal> 2371 [<option>--enable-stats</option>] 2372 </term> 2373 <listitem><para>Total number of bytes in active extents mapped by the 2374 allocator. This is larger than <link 2375 linkend="stats.active"><mallctl>stats.active</mallctl></link>. This 2376 does not include inactive extents, even those that contain unused dirty 2377 pages, which means that there is no strict ordering between this and 2378 <link 2379 linkend="stats.resident"><mallctl>stats.resident</mallctl></link>.</para></listitem> 2380 </varlistentry> 2381 2382 <varlistentry id="stats.retained"> 2383 <term> 2384 <mallctl>stats.retained</mallctl> 2385 (<type>size_t</type>) 2386 <literal>r-</literal> 2387 [<option>--enable-stats</option>] 2388 </term> 2389 <listitem><para>Total number of bytes in virtual memory mappings that 2390 were retained rather than being returned to the operating system via 2391 e.g. <citerefentry><refentrytitle>munmap</refentrytitle> 2392 <manvolnum>2</manvolnum></citerefentry> or similar. Retained virtual 2393 memory is typically untouched, decommitted, or purged, so it has no 2394 strongly associated physical memory (see <link 2395 linkend="arena.i.extent_hooks">extent hooks</link> for details). 2396 Retained memory is excluded from mapped memory statistics, e.g. <link 2397 linkend="stats.mapped"><mallctl>stats.mapped</mallctl></link>. 2398 </para></listitem> 2399 </varlistentry> 2400 2401 <varlistentry id="stats.background_thread.num_threads"> 2402 <term> 2403 <mallctl>stats.background_thread.num_threads</mallctl> 2404 (<type>size_t</type>) 2405 <literal>r-</literal> 2406 [<option>--enable-stats</option>] 2407 </term> 2408 <listitem><para> Number of <link linkend="background_thread">background 2409 threads</link> running currently.</para></listitem> 2410 </varlistentry> 2411 2412 <varlistentry id="stats.background_thread.num_runs"> 2413 <term> 2414 <mallctl>stats.background_thread.num_runs</mallctl> 2415 (<type>uint64_t</type>) 2416 <literal>r-</literal> 2417 [<option>--enable-stats</option>] 2418 </term> 2419 <listitem><para> Total number of runs from all <link 2420 linkend="background_thread">background threads</link>.</para></listitem> 2421 </varlistentry> 2422 2423 <varlistentry id="stats.background_thread.run_interval"> 2424 <term> 2425 <mallctl>stats.background_thread.run_interval</mallctl> 2426 (<type>uint64_t</type>) 2427 <literal>r-</literal> 2428 [<option>--enable-stats</option>] 2429 </term> 2430 <listitem><para> Average run interval in nanoseconds of <link 2431 linkend="background_thread">background threads</link>.</para></listitem> 2432 </varlistentry> 2433 2434 <varlistentry id="stats.mutexes.ctl"> 2435 <term> 2436 <mallctl>stats.mutexes.ctl.{counter};</mallctl> 2437 (<type>counter specific type</type>) 2438 <literal>r-</literal> 2439 [<option>--enable-stats</option>] 2440 </term> 2441 <listitem><para>Statistics on <varname>ctl</varname> mutex (global 2442 scope; mallctl related). <mallctl>{counter}</mallctl> is one of the 2443 counters below:</para> 2444 <varlistentry id="mutex_counters"> 2445 <listitem><para><varname>num_ops</varname> (<type>uint64_t</type>): 2446 Total number of lock acquisition operations on this mutex.</para> 2447 2448 <para><varname>num_spin_acq</varname> (<type>uint64_t</type>): Number 2449 of times the mutex was spin-acquired. When the mutex is currently 2450 locked and cannot be acquired immediately, a short period of 2451 spin-retry within jemalloc will be performed. Acquired through spin 2452 generally means the contention was lightweight and not causing context 2453 switches.</para> 2454 2455 <para><varname>num_wait</varname> (<type>uint64_t</type>): Number of 2456 times the mutex was wait-acquired, which means the mutex contention 2457 was not solved by spin-retry, and blocking operation was likely 2458 involved in order to acquire the mutex. This event generally implies 2459 higher cost / longer delay, and should be investigated if it happens 2460 often.</para> 2461 2462 <para><varname>max_wait_time</varname> (<type>uint64_t</type>): 2463 Maximum length of time in nanoseconds spent on a single wait-acquired 2464 lock operation. Note that to avoid profiling overhead on the common 2465 path, this does not consider spin-acquired cases.</para> 2466 2467 <para><varname>total_wait_time</varname> (<type>uint64_t</type>): 2468 Cumulative time in nanoseconds spent on wait-acquired lock operations. 2469 Similarly, spin-acquired cases are not considered.</para> 2470 2471 <para><varname>max_num_thds</varname> (<type>uint32_t</type>): Maximum 2472 number of threads waiting on this mutex simultaneously. Similarly, 2473 spin-acquired cases are not considered.</para> 2474 2475 <para><varname>num_owner_switch</varname> (<type>uint64_t</type>): 2476 Number of times the current mutex owner is different from the previous 2477 one. This event does not generally imply an issue; rather it is an 2478 indicator of how often the protected data are accessed by different 2479 threads. 2480 </para> 2481 </listitem> 2482 </varlistentry> 2483 </listitem> 2484 </varlistentry> 2485 2486 <varlistentry id="stats.mutexes.background_thread"> 2487 <term> 2488 <mallctl>stats.mutexes.background_thread.{counter}</mallctl> 2489 (<type>counter specific type</type>) <literal>r-</literal> 2490 [<option>--enable-stats</option>] 2491 </term> 2492 <listitem><para>Statistics on <varname>background_thread</varname> mutex 2493 (global scope; <link 2494 linkend="background_thread"><mallctl>background_thread</mallctl></link> 2495 related). <mallctl>{counter}</mallctl> is one of the counters in <link 2496 linkend="mutex_counters">mutex profiling 2497 counters</link>.</para></listitem> 2498 </varlistentry> 2499 2500 <varlistentry id="stats.mutexes.prof"> 2501 <term> 2502 <mallctl>stats.mutexes.prof.{counter}</mallctl> 2503 (<type>counter specific type</type>) <literal>r-</literal> 2504 [<option>--enable-stats</option>] 2505 </term> 2506 <listitem><para>Statistics on <varname>prof</varname> mutex (global 2507 scope; profiling related). <mallctl>{counter}</mallctl> is one of the 2508 counters in <link linkend="mutex_counters">mutex profiling 2509 counters</link>.</para></listitem> 2510 </varlistentry> 2511 2512 <varlistentry id="stats.mutexes.reset"> 2513 <term> 2514 <mallctl>stats.mutexes.reset</mallctl> 2515 (<type>void</type>) <literal>--</literal> 2516 [<option>--enable-stats</option>] 2517 </term> 2518 <listitem><para>Reset all mutex profile statistics, including global 2519 mutexes, arena mutexes and bin mutexes.</para></listitem> 2520 </varlistentry> 2521 2522 <varlistentry id="stats.arenas.i.dss"> 2523 <term> 2524 <mallctl>stats.arenas.<i>.dss</mallctl> 2525 (<type>const char *</type>) 2526 <literal>r-</literal> 2527 </term> 2528 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 2529 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 2530 related to <citerefentry><refentrytitle>mmap</refentrytitle> 2531 <manvolnum>2</manvolnum></citerefentry> allocation. See <link 2532 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for details. 2533 </para></listitem> 2534 </varlistentry> 2535 2536 <varlistentry id="stats.arenas.i.dirty_decay_ms"> 2537 <term> 2538 <mallctl>stats.arenas.<i>.dirty_decay_ms</mallctl> 2539 (<type>ssize_t</type>) 2540 <literal>r-</literal> 2541 </term> 2542 <listitem><para>Approximate time in milliseconds from the creation of a 2543 set of unused dirty pages until an equivalent set of unused dirty pages 2544 is purged and/or reused. See <link 2545 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2546 for details.</para></listitem> 2547 </varlistentry> 2548 2549 <varlistentry id="stats.arenas.i.muzzy_decay_ms"> 2550 <term> 2551 <mallctl>stats.arenas.<i>.muzzy_decay_ms</mallctl> 2552 (<type>ssize_t</type>) 2553 <literal>r-</literal> 2554 </term> 2555 <listitem><para>Approximate time in milliseconds from the creation of a 2556 set of unused muzzy pages until an equivalent set of unused muzzy pages 2557 is purged and/or reused. See <link 2558 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2559 for details.</para></listitem> 2560 </varlistentry> 2561 2562 <varlistentry id="stats.arenas.i.nthreads"> 2563 <term> 2564 <mallctl>stats.arenas.<i>.nthreads</mallctl> 2565 (<type>unsigned</type>) 2566 <literal>r-</literal> 2567 </term> 2568 <listitem><para>Number of threads currently assigned to 2569 arena.</para></listitem> 2570 </varlistentry> 2571 2572 <varlistentry id="stats.arenas.i.uptime"> 2573 <term> 2574 <mallctl>stats.arenas.<i>.uptime</mallctl> 2575 (<type>uint64_t</type>) 2576 <literal>r-</literal> 2577 </term> 2578 <listitem><para>Time elapsed (in nanoseconds) since the arena was 2579 created. If <i> equals <constant>0</constant> or 2580 <constant>MALLCTL_ARENAS_ALL</constant>, this is the uptime since malloc 2581 initialization.</para></listitem> 2582 </varlistentry> 2583 2584 <varlistentry id="stats.arenas.i.pactive"> 2585 <term> 2586 <mallctl>stats.arenas.<i>.pactive</mallctl> 2587 (<type>size_t</type>) 2588 <literal>r-</literal> 2589 </term> 2590 <listitem><para>Number of pages in active extents.</para></listitem> 2591 </varlistentry> 2592 2593 <varlistentry id="stats.arenas.i.pdirty"> 2594 <term> 2595 <mallctl>stats.arenas.<i>.pdirty</mallctl> 2596 (<type>size_t</type>) 2597 <literal>r-</literal> 2598 </term> 2599 <listitem><para>Number of pages within unused extents that are 2600 potentially dirty, and for which <function>madvise()</function> or 2601 similar has not been called. See <link 2602 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2603 for a description of dirty pages.</para></listitem> 2604 </varlistentry> 2605 2606 <varlistentry id="stats.arenas.i.pmuzzy"> 2607 <term> 2608 <mallctl>stats.arenas.<i>.pmuzzy</mallctl> 2609 (<type>size_t</type>) 2610 <literal>r-</literal> 2611 </term> 2612 <listitem><para>Number of pages within unused extents that are muzzy. 2613 See <link 2614 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2615 for a description of muzzy pages.</para></listitem> 2616 </varlistentry> 2617 2618 <varlistentry id="stats.arenas.i.mapped"> 2619 <term> 2620 <mallctl>stats.arenas.<i>.mapped</mallctl> 2621 (<type>size_t</type>) 2622 <literal>r-</literal> 2623 [<option>--enable-stats</option>] 2624 </term> 2625 <listitem><para>Number of mapped bytes.</para></listitem> 2626 </varlistentry> 2627 2628 <varlistentry id="stats.arenas.i.retained"> 2629 <term> 2630 <mallctl>stats.arenas.<i>.retained</mallctl> 2631 (<type>size_t</type>) 2632 <literal>r-</literal> 2633 [<option>--enable-stats</option>] 2634 </term> 2635 <listitem><para>Number of retained bytes. See <link 2636 linkend="stats.retained"><mallctl>stats.retained</mallctl></link> for 2637 details.</para></listitem> 2638 </varlistentry> 2639 2640 <varlistentry id="stats.arenas.i.extent_avail"> 2641 <term> 2642 <mallctl>stats.arenas.<i>.extent_avail</mallctl> 2643 (<type>size_t</type>) 2644 <literal>r-</literal> 2645 [<option>--enable-stats</option>] 2646 </term> 2647 <listitem><para>Number of allocated (but unused) extent structs in this 2648 arena.</para></listitem> 2649 </varlistentry> 2650 2651 <varlistentry id="stats.arenas.i.base"> 2652 <term> 2653 <mallctl>stats.arenas.<i>.base</mallctl> 2654 (<type>size_t</type>) 2655 <literal>r-</literal> 2656 [<option>--enable-stats</option>] 2657 </term> 2658 <listitem><para> 2659 Number of bytes dedicated to bootstrap-sensitive allocator metadata 2660 structures.</para></listitem> 2661 </varlistentry> 2662 2663 <varlistentry id="stats.arenas.i.internal"> 2664 <term> 2665 <mallctl>stats.arenas.<i>.internal</mallctl> 2666 (<type>size_t</type>) 2667 <literal>r-</literal> 2668 [<option>--enable-stats</option>] 2669 </term> 2670 <listitem><para>Number of bytes dedicated to internal allocations. 2671 Internal allocations differ from application-originated allocations in 2672 that they are for internal use, and that they are omitted from heap 2673 profiles.</para></listitem> 2674 </varlistentry> 2675 2676 <varlistentry id="stats.arenas.i.metadata_thp"> 2677 <term> 2678 <mallctl>stats.arenas.<i>.metadata_thp</mallctl> 2679 (<type>size_t</type>) 2680 <literal>r-</literal> 2681 [<option>--enable-stats</option>] 2682 </term> 2683 <listitem><para>Number of transparent huge pages (THP) used for 2684 metadata. See <link linkend="opt.metadata_thp">opt.metadata_thp</link> 2685 for details.</para></listitem> 2686 </varlistentry> 2687 2688 <varlistentry id="stats.arenas.i.resident"> 2689 <term> 2690 <mallctl>stats.arenas.<i>.resident</mallctl> 2691 (<type>size_t</type>) 2692 <literal>r-</literal> 2693 [<option>--enable-stats</option>] 2694 </term> 2695 <listitem><para>Maximum number of bytes in physically resident data 2696 pages mapped by the arena, comprising all pages dedicated to allocator 2697 metadata, pages backing active allocations, and unused dirty pages. 2698 This is a maximum rather than precise because pages may not actually be 2699 physically resident if they correspond to demand-zeroed virtual memory 2700 that has not yet been touched. This is a multiple of the page 2701 size.</para></listitem> 2702 </varlistentry> 2703 2704 <varlistentry id="stats.arenas.i.dirty_npurge"> 2705 <term> 2706 <mallctl>stats.arenas.<i>.dirty_npurge</mallctl> 2707 (<type>uint64_t</type>) 2708 <literal>r-</literal> 2709 [<option>--enable-stats</option>] 2710 </term> 2711 <listitem><para>Number of dirty page purge sweeps performed. 2712 </para></listitem> 2713 </varlistentry> 2714 2715 <varlistentry id="stats.arenas.i.dirty_nmadvise"> 2716 <term> 2717 <mallctl>stats.arenas.<i>.dirty_nmadvise</mallctl> 2718 (<type>uint64_t</type>) 2719 <literal>r-</literal> 2720 [<option>--enable-stats</option>] 2721 </term> 2722 <listitem><para>Number of <function>madvise()</function> or similar 2723 calls made to purge dirty pages.</para></listitem> 2724 </varlistentry> 2725 2726 <varlistentry id="stats.arenas.i.dirty_purged"> 2727 <term> 2728 <mallctl>stats.arenas.<i>.dirty_purged</mallctl> 2729 (<type>uint64_t</type>) 2730 <literal>r-</literal> 2731 [<option>--enable-stats</option>] 2732 </term> 2733 <listitem><para>Number of dirty pages purged.</para></listitem> 2734 </varlistentry> 2735 2736 <varlistentry id="stats.arenas.i.muzzy_npurge"> 2737 <term> 2738 <mallctl>stats.arenas.<i>.muzzy_npurge</mallctl> 2739 (<type>uint64_t</type>) 2740 <literal>r-</literal> 2741 [<option>--enable-stats</option>] 2742 </term> 2743 <listitem><para>Number of muzzy page purge sweeps performed. 2744 </para></listitem> 2745 </varlistentry> 2746 2747 <varlistentry id="stats.arenas.i.muzzy_nmadvise"> 2748 <term> 2749 <mallctl>stats.arenas.<i>.muzzy_nmadvise</mallctl> 2750 (<type>uint64_t</type>) 2751 <literal>r-</literal> 2752 [<option>--enable-stats</option>] 2753 </term> 2754 <listitem><para>Number of <function>madvise()</function> or similar 2755 calls made to purge muzzy pages.</para></listitem> 2756 </varlistentry> 2757 2758 <varlistentry id="stats.arenas.i.muzzy_purged"> 2759 <term> 2760 <mallctl>stats.arenas.<i>.muzzy_purged</mallctl> 2761 (<type>uint64_t</type>) 2762 <literal>r-</literal> 2763 [<option>--enable-stats</option>] 2764 </term> 2765 <listitem><para>Number of muzzy pages purged.</para></listitem> 2766 </varlistentry> 2767 2768 <varlistentry id="stats.arenas.i.small.allocated"> 2769 <term> 2770 <mallctl>stats.arenas.<i>.small.allocated</mallctl> 2771 (<type>size_t</type>) 2772 <literal>r-</literal> 2773 [<option>--enable-stats</option>] 2774 </term> 2775 <listitem><para>Number of bytes currently allocated by small objects. 2776 </para></listitem> 2777 </varlistentry> 2778 2779 <varlistentry id="stats.arenas.i.small.nmalloc"> 2780 <term> 2781 <mallctl>stats.arenas.<i>.small.nmalloc</mallctl> 2782 (<type>uint64_t</type>) 2783 <literal>r-</literal> 2784 [<option>--enable-stats</option>] 2785 </term> 2786 <listitem><para>Cumulative number of times a small allocation was 2787 requested from the arena's bins, whether to fill the relevant tcache if 2788 <link linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is 2789 enabled, or to directly satisfy an allocation request 2790 otherwise.</para></listitem> 2791 </varlistentry> 2792 2793 <varlistentry id="stats.arenas.i.small.ndalloc"> 2794 <term> 2795 <mallctl>stats.arenas.<i>.small.ndalloc</mallctl> 2796 (<type>uint64_t</type>) 2797 <literal>r-</literal> 2798 [<option>--enable-stats</option>] 2799 </term> 2800 <listitem><para>Cumulative number of times a small allocation was 2801 returned to the arena's bins, whether to flush the relevant tcache if 2802 <link linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is 2803 enabled, or to directly deallocate an allocation 2804 otherwise.</para></listitem> 2805 </varlistentry> 2806 2807 <varlistentry id="stats.arenas.i.small.nrequests"> 2808 <term> 2809 <mallctl>stats.arenas.<i>.small.nrequests</mallctl> 2810 (<type>uint64_t</type>) 2811 <literal>r-</literal> 2812 [<option>--enable-stats</option>] 2813 </term> 2814 <listitem><para>Cumulative number of allocation requests satisfied by 2815 all bin size classes.</para></listitem> 2816 </varlistentry> 2817 2818 <varlistentry id="stats.arenas.i.small.nfills"> 2819 <term> 2820 <mallctl>stats.arenas.<i>.small.nfills</mallctl> 2821 (<type>uint64_t</type>) 2822 <literal>r-</literal> 2823 [<option>--enable-stats</option>] 2824 </term> 2825 <listitem><para>Cumulative number of tcache fills by all small size 2826 classes.</para></listitem> 2827 </varlistentry> 2828 2829 <varlistentry id="stats.arenas.i.small.nflushes"> 2830 <term> 2831 <mallctl>stats.arenas.<i>.small.nflushes</mallctl> 2832 (<type>uint64_t</type>) 2833 <literal>r-</literal> 2834 [<option>--enable-stats</option>] 2835 </term> 2836 <listitem><para>Cumulative number of tcache flushes by all small size 2837 classes.</para></listitem> 2838 </varlistentry> 2839 2840 <varlistentry id="stats.arenas.i.large.allocated"> 2841 <term> 2842 <mallctl>stats.arenas.<i>.large.allocated</mallctl> 2843 (<type>size_t</type>) 2844 <literal>r-</literal> 2845 [<option>--enable-stats</option>] 2846 </term> 2847 <listitem><para>Number of bytes currently allocated by large objects. 2848 </para></listitem> 2849 </varlistentry> 2850 2851 <varlistentry id="stats.arenas.i.large.nmalloc"> 2852 <term> 2853 <mallctl>stats.arenas.<i>.large.nmalloc</mallctl> 2854 (<type>uint64_t</type>) 2855 <literal>r-</literal> 2856 [<option>--enable-stats</option>] 2857 </term> 2858 <listitem><para>Cumulative number of times a large extent was allocated 2859 from the arena, whether to fill the relevant tcache if <link 2860 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 2861 the size class is within the range being cached, or to directly satisfy 2862 an allocation request otherwise.</para></listitem> 2863 </varlistentry> 2864 2865 <varlistentry id="stats.arenas.i.large.ndalloc"> 2866 <term> 2867 <mallctl>stats.arenas.<i>.large.ndalloc</mallctl> 2868 (<type>uint64_t</type>) 2869 <literal>r-</literal> 2870 [<option>--enable-stats</option>] 2871 </term> 2872 <listitem><para>Cumulative number of times a large extent was returned 2873 to the arena, whether to flush the relevant tcache if <link 2874 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 2875 the size class is within the range being cached, or to directly 2876 deallocate an allocation otherwise.</para></listitem> 2877 </varlistentry> 2878 2879 <varlistentry id="stats.arenas.i.large.nrequests"> 2880 <term> 2881 <mallctl>stats.arenas.<i>.large.nrequests</mallctl> 2882 (<type>uint64_t</type>) 2883 <literal>r-</literal> 2884 [<option>--enable-stats</option>] 2885 </term> 2886 <listitem><para>Cumulative number of allocation requests satisfied by 2887 all large size classes.</para></listitem> 2888 </varlistentry> 2889 2890 <varlistentry id="stats.arenas.i.large.nfills"> 2891 <term> 2892 <mallctl>stats.arenas.<i>.large.nfills</mallctl> 2893 (<type>uint64_t</type>) 2894 <literal>r-</literal> 2895 [<option>--enable-stats</option>] 2896 </term> 2897 <listitem><para>Cumulative number of tcache fills by all large size 2898 classes.</para></listitem> 2899 </varlistentry> 2900 2901 <varlistentry id="stats.arenas.i.large.nflushes"> 2902 <term> 2903 <mallctl>stats.arenas.<i>.large.nflushes</mallctl> 2904 (<type>uint64_t</type>) 2905 <literal>r-</literal> 2906 [<option>--enable-stats</option>] 2907 </term> 2908 <listitem><para>Cumulative number of tcache flushes by all large size 2909 classes.</para></listitem> 2910 </varlistentry> 2911 2912 <varlistentry id="stats.arenas.i.bins.j.nmalloc"> 2913 <term> 2914 <mallctl>stats.arenas.<i>.bins.<j>.nmalloc</mallctl> 2915 (<type>uint64_t</type>) 2916 <literal>r-</literal> 2917 [<option>--enable-stats</option>] 2918 </term> 2919 <listitem><para>Cumulative number of times a bin region of the 2920 corresponding size class was allocated from the arena, whether to fill 2921 the relevant tcache if <link 2922 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled, or 2923 to directly satisfy an allocation request otherwise.</para></listitem> 2924 </varlistentry> 2925 2926 <varlistentry id="stats.arenas.i.bins.j.ndalloc"> 2927 <term> 2928 <mallctl>stats.arenas.<i>.bins.<j>.ndalloc</mallctl> 2929 (<type>uint64_t</type>) 2930 <literal>r-</literal> 2931 [<option>--enable-stats</option>] 2932 </term> 2933 <listitem><para>Cumulative number of times a bin region of the 2934 corresponding size class was returned to the arena, whether to flush the 2935 relevant tcache if <link 2936 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled, or 2937 to directly deallocate an allocation otherwise.</para></listitem> 2938 </varlistentry> 2939 2940 <varlistentry id="stats.arenas.i.bins.j.nrequests"> 2941 <term> 2942 <mallctl>stats.arenas.<i>.bins.<j>.nrequests</mallctl> 2943 (<type>uint64_t</type>) 2944 <literal>r-</literal> 2945 [<option>--enable-stats</option>] 2946 </term> 2947 <listitem><para>Cumulative number of allocation requests satisfied by 2948 bin regions of the corresponding size class.</para></listitem> 2949 </varlistentry> 2950 2951 <varlistentry id="stats.arenas.i.bins.j.curregs"> 2952 <term> 2953 <mallctl>stats.arenas.<i>.bins.<j>.curregs</mallctl> 2954 (<type>size_t</type>) 2955 <literal>r-</literal> 2956 [<option>--enable-stats</option>] 2957 </term> 2958 <listitem><para>Current number of regions for this size 2959 class.</para></listitem> 2960 </varlistentry> 2961 2962 <varlistentry id="stats.arenas.i.bins.j.nfills"> 2963 <term> 2964 <mallctl>stats.arenas.<i>.bins.<j>.nfills</mallctl> 2965 (<type>uint64_t</type>) 2966 <literal>r-</literal> 2967 </term> 2968 <listitem><para>Cumulative number of tcache fills.</para></listitem> 2969 </varlistentry> 2970 2971 <varlistentry id="stats.arenas.i.bins.j.nflushes"> 2972 <term> 2973 <mallctl>stats.arenas.<i>.bins.<j>.nflushes</mallctl> 2974 (<type>uint64_t</type>) 2975 <literal>r-</literal> 2976 </term> 2977 <listitem><para>Cumulative number of tcache flushes.</para></listitem> 2978 </varlistentry> 2979 2980 <varlistentry id="stats.arenas.i.bins.j.nslabs"> 2981 <term> 2982 <mallctl>stats.arenas.<i>.bins.<j>.nslabs</mallctl> 2983 (<type>uint64_t</type>) 2984 <literal>r-</literal> 2985 [<option>--enable-stats</option>] 2986 </term> 2987 <listitem><para>Cumulative number of slabs created.</para></listitem> 2988 </varlistentry> 2989 2990 <varlistentry id="stats.arenas.i.bins.j.nreslabs"> 2991 <term> 2992 <mallctl>stats.arenas.<i>.bins.<j>.nreslabs</mallctl> 2993 (<type>uint64_t</type>) 2994 <literal>r-</literal> 2995 [<option>--enable-stats</option>] 2996 </term> 2997 <listitem><para>Cumulative number of times the current slab from which 2998 to allocate changed.</para></listitem> 2999 </varlistentry> 3000 3001 <varlistentry id="stats.arenas.i.bins.j.curslabs"> 3002 <term> 3003 <mallctl>stats.arenas.<i>.bins.<j>.curslabs</mallctl> 3004 (<type>size_t</type>) 3005 <literal>r-</literal> 3006 [<option>--enable-stats</option>] 3007 </term> 3008 <listitem><para>Current number of slabs.</para></listitem> 3009 </varlistentry> 3010 3011 3012 <varlistentry id="stats.arenas.i.bins.j.nonfull_slabs"> 3013 <term> 3014 <mallctl>stats.arenas.<i>.bins.<j>.nonfull_slabs</mallctl> 3015 (<type>size_t</type>) 3016 <literal>r-</literal> 3017 [<option>--enable-stats</option>] 3018 </term> 3019 <listitem><para>Current number of nonfull slabs.</para></listitem> 3020 </varlistentry> 3021 3022 <varlistentry id="stats.arenas.i.bins.mutex"> 3023 <term> 3024 <mallctl>stats.arenas.<i>.bins.<j>.mutex.{counter}</mallctl> 3025 (<type>counter specific type</type>) <literal>r-</literal> 3026 [<option>--enable-stats</option>] 3027 </term> 3028 <listitem><para>Statistics on 3029 <varname>arena.<i>.bins.<j></varname> mutex (arena bin 3030 scope; bin operation related). <mallctl>{counter}</mallctl> is one of 3031 the counters in <link linkend="mutex_counters">mutex profiling 3032 counters</link>.</para></listitem> 3033 </varlistentry> 3034 3035 <varlistentry id="stats.arenas.i.extents.n"> 3036 <term> 3037 <mallctl>stats.arenas.<i>.extents.<j>.n{extent_type}</mallctl> 3038 (<type>size_t</type>) 3039 <literal>r-</literal> 3040 [<option>--enable-stats</option>] 3041 </term> 3042 <listitem><para> Number of extents of the given type in this arena in 3043 the bucket corresponding to page size index <j>. The extent type 3044 is one of dirty, muzzy, or retained.</para></listitem> 3045 </varlistentry> 3046 3047 <varlistentry id="stats.arenas.i.extents.bytes"> 3048 <term> 3049 <mallctl>stats.arenas.<i>.extents.<j>.{extent_type}_bytes</mallctl> 3050 (<type>size_t</type>) 3051 <literal>r-</literal> 3052 [<option>--enable-stats</option>] 3053 </term> 3054 <listitem><para> Sum of the bytes managed by extents of the given type 3055 in this arena in the bucket corresponding to page size index <j>. 3056 The extent type is one of dirty, muzzy, or retained.</para></listitem> 3057 </varlistentry> 3058 3059 <varlistentry id="stats.arenas.i.lextents.j.nmalloc"> 3060 <term> 3061 <mallctl>stats.arenas.<i>.lextents.<j>.nmalloc</mallctl> 3062 (<type>uint64_t</type>) 3063 <literal>r-</literal> 3064 [<option>--enable-stats</option>] 3065 </term> 3066 <listitem><para>Cumulative number of times a large extent of the 3067 corresponding size class was allocated from the arena, whether to fill 3068 the relevant tcache if <link 3069 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3070 the size class is within the range being cached, or to directly satisfy 3071 an allocation request otherwise.</para></listitem> 3072 </varlistentry> 3073 3074 <varlistentry id="stats.arenas.i.lextents.j.ndalloc"> 3075 <term> 3076 <mallctl>stats.arenas.<i>.lextents.<j>.ndalloc</mallctl> 3077 (<type>uint64_t</type>) 3078 <literal>r-</literal> 3079 [<option>--enable-stats</option>] 3080 </term> 3081 <listitem><para>Cumulative number of times a large extent of the 3082 corresponding size class was returned to the arena, whether to flush the 3083 relevant tcache if <link 3084 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3085 the size class is within the range being cached, or to directly 3086 deallocate an allocation otherwise.</para></listitem> 3087 </varlistentry> 3088 3089 <varlistentry id="stats.arenas.i.lextents.j.nrequests"> 3090 <term> 3091 <mallctl>stats.arenas.<i>.lextents.<j>.nrequests</mallctl> 3092 (<type>uint64_t</type>) 3093 <literal>r-</literal> 3094 [<option>--enable-stats</option>] 3095 </term> 3096 <listitem><para>Cumulative number of allocation requests satisfied by 3097 large extents of the corresponding size class.</para></listitem> 3098 </varlistentry> 3099 3100 <varlistentry id="stats.arenas.i.lextents.j.curlextents"> 3101 <term> 3102 <mallctl>stats.arenas.<i>.lextents.<j>.curlextents</mallctl> 3103 (<type>size_t</type>) 3104 <literal>r-</literal> 3105 [<option>--enable-stats</option>] 3106 </term> 3107 <listitem><para>Current number of large allocations for this size class. 3108 </para></listitem> 3109 </varlistentry> 3110 3111 <varlistentry id="stats.arenas.i.mutexes.large"> 3112 <term> 3113 <mallctl>stats.arenas.<i>.mutexes.large.{counter}</mallctl> 3114 (<type>counter specific type</type>) <literal>r-</literal> 3115 [<option>--enable-stats</option>] 3116 </term> 3117 <listitem><para>Statistics on <varname>arena.<i>.large</varname> 3118 mutex (arena scope; large allocation related). 3119 <mallctl>{counter}</mallctl> is one of the counters in <link 3120 linkend="mutex_counters">mutex profiling 3121 counters</link>.</para></listitem> 3122 </varlistentry> 3123 3124 <varlistentry id="stats.arenas.i.mutexes.extent_avail"> 3125 <term> 3126 <mallctl>stats.arenas.<i>.mutexes.extent_avail.{counter}</mallctl> 3127 (<type>counter specific type</type>) <literal>r-</literal> 3128 [<option>--enable-stats</option>] 3129 </term> 3130 <listitem><para>Statistics on <varname>arena.<i>.extent_avail 3131 </varname> mutex (arena scope; extent avail related). 3132 <mallctl>{counter}</mallctl> is one of the counters in <link 3133 linkend="mutex_counters">mutex profiling 3134 counters</link>.</para></listitem> 3135 </varlistentry> 3136 3137 <varlistentry id="stats.arenas.i.mutexes.extents_dirty"> 3138 <term> 3139 <mallctl>stats.arenas.<i>.mutexes.extents_dirty.{counter}</mallctl> 3140 (<type>counter specific type</type>) <literal>r-</literal> 3141 [<option>--enable-stats</option>] 3142 </term> 3143 <listitem><para>Statistics on <varname>arena.<i>.extents_dirty 3144 </varname> mutex (arena scope; dirty extents related). 3145 <mallctl>{counter}</mallctl> is one of the counters in <link 3146 linkend="mutex_counters">mutex profiling 3147 counters</link>.</para></listitem> 3148 </varlistentry> 3149 3150 <varlistentry id="stats.arenas.i.mutexes.extents_muzzy"> 3151 <term> 3152 <mallctl>stats.arenas.<i>.mutexes.extents_muzzy.{counter}</mallctl> 3153 (<type>counter specific type</type>) <literal>r-</literal> 3154 [<option>--enable-stats</option>] 3155 </term> 3156 <listitem><para>Statistics on <varname>arena.<i>.extents_muzzy 3157 </varname> mutex (arena scope; muzzy extents related). 3158 <mallctl>{counter}</mallctl> is one of the counters in <link 3159 linkend="mutex_counters">mutex profiling 3160 counters</link>.</para></listitem> 3161 </varlistentry> 3162 3163 <varlistentry id="stats.arenas.i.mutexes.extents_retained"> 3164 <term> 3165 <mallctl>stats.arenas.<i>.mutexes.extents_retained.{counter}</mallctl> 3166 (<type>counter specific type</type>) <literal>r-</literal> 3167 [<option>--enable-stats</option>] 3168 </term> 3169 <listitem><para>Statistics on <varname>arena.<i>.extents_retained 3170 </varname> mutex (arena scope; retained extents related). 3171 <mallctl>{counter}</mallctl> is one of the counters in <link 3172 linkend="mutex_counters">mutex profiling 3173 counters</link>.</para></listitem> 3174 </varlistentry> 3175 3176 <varlistentry id="stats.arenas.i.mutexes.decay_dirty"> 3177 <term> 3178 <mallctl>stats.arenas.<i>.mutexes.decay_dirty.{counter}</mallctl> 3179 (<type>counter specific type</type>) <literal>r-</literal> 3180 [<option>--enable-stats</option>] 3181 </term> 3182 <listitem><para>Statistics on <varname>arena.<i>.decay_dirty 3183 </varname> mutex (arena scope; decay for dirty pages related). 3184 <mallctl>{counter}</mallctl> is one of the counters in <link 3185 linkend="mutex_counters">mutex profiling 3186 counters</link>.</para></listitem> 3187 </varlistentry> 3188 3189 <varlistentry id="stats.arenas.i.mutexes.decay_muzzy"> 3190 <term> 3191 <mallctl>stats.arenas.<i>.mutexes.decay_muzzy.{counter}</mallctl> 3192 (<type>counter specific type</type>) <literal>r-</literal> 3193 [<option>--enable-stats</option>] 3194 </term> 3195 <listitem><para>Statistics on <varname>arena.<i>.decay_muzzy 3196 </varname> mutex (arena scope; decay for muzzy pages related). 3197 <mallctl>{counter}</mallctl> is one of the counters in <link 3198 linkend="mutex_counters">mutex profiling 3199 counters</link>.</para></listitem> 3200 </varlistentry> 3201 3202 <varlistentry id="stats.arenas.i.mutexes.base"> 3203 <term> 3204 <mallctl>stats.arenas.<i>.mutexes.base.{counter}</mallctl> 3205 (<type>counter specific type</type>) <literal>r-</literal> 3206 [<option>--enable-stats</option>] 3207 </term> 3208 <listitem><para>Statistics on <varname>arena.<i>.base</varname> 3209 mutex (arena scope; base allocator related). 3210 <mallctl>{counter}</mallctl> is one of the counters in <link 3211 linkend="mutex_counters">mutex profiling 3212 counters</link>.</para></listitem> 3213 </varlistentry> 3214 3215 <varlistentry id="stats.arenas.i.mutexes.tcache_list"> 3216 <term> 3217 <mallctl>stats.arenas.<i>.mutexes.tcache_list.{counter}</mallctl> 3218 (<type>counter specific type</type>) <literal>r-</literal> 3219 [<option>--enable-stats</option>] 3220 </term> 3221 <listitem><para>Statistics on 3222 <varname>arena.<i>.tcache_list</varname> mutex (arena scope; 3223 tcache to arena association related). This mutex is expected to be 3224 accessed less often. <mallctl>{counter}</mallctl> is one of the 3225 counters in <link linkend="mutex_counters">mutex profiling 3226 counters</link>.</para></listitem> 3227 </varlistentry> 3228 3229 </variablelist> 3230 </refsect1> 3231 <refsect1 id="heap_profile_format"> 3232 <title>HEAP PROFILE FORMAT</title> 3233 <para>Although the heap profiling functionality was originally designed to 3234 be compatible with the 3235 <command>pprof</command> command that is developed as part of the <ulink 3236 url="http://code.google.com/p/gperftools/">gperftools 3237 package</ulink>, the addition of per thread heap profiling functionality 3238 required a different heap profile format. The <command>jeprof</command> 3239 command is derived from <command>pprof</command>, with enhancements to 3240 support the heap profile format described here.</para> 3241 3242 <para>In the following hypothetical heap profile, <constant>[...]</constant> 3243 indicates elision for the sake of compactness. <programlisting><![CDATA[ 3244heap_v2/524288 3245 t*: 28106: 56637512 [0: 0] 3246 [...] 3247 t3: 352: 16777344 [0: 0] 3248 [...] 3249 t99: 17754: 29341640 [0: 0] 3250 [...] 3251@ 0x5f86da8 0x5f5a1dc [...] 0x29e4d4e 0xa200316 0xabb2988 [...] 3252 t*: 13: 6688 [0: 0] 3253 t3: 12: 6496 [0: ] 3254 t99: 1: 192 [0: 0] 3255[...] 3256 3257MAPPED_LIBRARIES: 3258[...]]]></programlisting> The following matches the above heap profile, but most 3259tokens are replaced with <constant><description></constant> to indicate 3260descriptions of the corresponding fields. <programlisting><![CDATA[ 3261<heap_profile_format_version>/<mean_sample_interval> 3262 <aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3263 [...] 3264 <thread_3_aggregate>: <curobjs>: <curbytes>[<cumobjs>: <cumbytes>] 3265 [...] 3266 <thread_99_aggregate>: <curobjs>: <curbytes>[<cumobjs>: <cumbytes>] 3267 [...] 3268@ <top_frame> <frame> [...] <frame> <frame> <frame> [...] 3269 <backtrace_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3270 <backtrace_thread_3>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3271 <backtrace_thread_99>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3272[...] 3273 3274MAPPED_LIBRARIES: 3275</proc/<pid>/maps>]]></programlisting></para> 3276 </refsect1> 3277 3278 <refsect1 id="debugging_malloc_problems"> 3279 <title>DEBUGGING MALLOC PROBLEMS</title> 3280 <para>When debugging, it is a good idea to configure/build jemalloc with 3281 the <option>--enable-debug</option> and <option>--enable-fill</option> 3282 options, and recompile the program with suitable options and symbols for 3283 debugger support. When so configured, jemalloc incorporates a wide variety 3284 of run-time assertions that catch application errors such as double-free, 3285 write-after-free, etc.</para> 3286 3287 <para>Programs often accidentally depend on <quote>uninitialized</quote> 3288 memory actually being filled with zero bytes. Junk filling 3289 (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> 3290 option) tends to expose such bugs in the form of obviously incorrect 3291 results and/or coredumps. Conversely, zero 3292 filling (see the <link 3293 linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates 3294 the symptoms of such bugs. Between these two options, it is usually 3295 possible to quickly detect, diagnose, and eliminate such bugs.</para> 3296 3297 <para>This implementation does not provide much detail about the problems 3298 it detects, because the performance impact for storing such information 3299 would be prohibitive.</para> 3300 </refsect1> 3301 <refsect1 id="diagnostic_messages"> 3302 <title>DIAGNOSTIC MESSAGES</title> 3303 <para>If any of the memory allocation/deallocation functions detect an 3304 error or warning condition, a message will be printed to file descriptor 3305 <constant>STDERR_FILENO</constant>. Errors will result in the process 3306 dumping core. If the <link 3307 linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most 3308 warnings are treated as errors.</para> 3309 3310 <para>The <varname>malloc_message</varname> variable allows the programmer 3311 to override the function which emits the text strings forming the errors 3312 and warnings if for some reason the <constant>STDERR_FILENO</constant> file 3313 descriptor is not suitable for this. 3314 <function>malloc_message()</function> takes the 3315 <parameter>cbopaque</parameter> pointer argument that is 3316 <constant>NULL</constant> unless overridden by the arguments in a call to 3317 <function>malloc_stats_print()</function>, followed by a string 3318 pointer. Please note that doing anything which tries to allocate memory in 3319 this function is likely to result in a crash or deadlock.</para> 3320 3321 <para>All messages are prefixed by 3322 <quote><computeroutput><jemalloc>: </computeroutput></quote>.</para> 3323 </refsect1> 3324 <refsect1 id="return_values"> 3325 <title>RETURN VALUES</title> 3326 <refsect2> 3327 <title>Standard API</title> 3328 <para>The <function>malloc()</function> and 3329 <function>calloc()</function> functions return a pointer to the 3330 allocated memory if successful; otherwise a <constant>NULL</constant> 3331 pointer is returned and <varname>errno</varname> is set to 3332 <errorname>ENOMEM</errorname>.</para> 3333 3334 <para>The <function>posix_memalign()</function> function 3335 returns the value 0 if successful; otherwise it returns an error value. 3336 The <function>posix_memalign()</function> function will fail 3337 if: 3338 <variablelist> 3339 <varlistentry> 3340 <term><errorname>EINVAL</errorname></term> 3341 3342 <listitem><para>The <parameter>alignment</parameter> parameter is 3343 not a power of 2 at least as large as 3344 <code language="C">sizeof(<type>void *</type>)</code>. 3345 </para></listitem> 3346 </varlistentry> 3347 <varlistentry> 3348 <term><errorname>ENOMEM</errorname></term> 3349 3350 <listitem><para>Memory allocation error.</para></listitem> 3351 </varlistentry> 3352 </variablelist> 3353 </para> 3354 3355 <para>The <function>aligned_alloc()</function> function returns 3356 a pointer to the allocated memory if successful; otherwise a 3357 <constant>NULL</constant> pointer is returned and 3358 <varname>errno</varname> is set. The 3359 <function>aligned_alloc()</function> function will fail if: 3360 <variablelist> 3361 <varlistentry> 3362 <term><errorname>EINVAL</errorname></term> 3363 3364 <listitem><para>The <parameter>alignment</parameter> parameter is 3365 not a power of 2. 3366 </para></listitem> 3367 </varlistentry> 3368 <varlistentry> 3369 <term><errorname>ENOMEM</errorname></term> 3370 3371 <listitem><para>Memory allocation error.</para></listitem> 3372 </varlistentry> 3373 </variablelist> 3374 </para> 3375 3376 <para>The <function>realloc()</function> function returns a 3377 pointer, possibly identical to <parameter>ptr</parameter>, to the 3378 allocated memory if successful; otherwise a <constant>NULL</constant> 3379 pointer is returned, and <varname>errno</varname> is set to 3380 <errorname>ENOMEM</errorname> if the error was the result of an 3381 allocation failure. The <function>realloc()</function> 3382 function always leaves the original buffer intact when an error occurs. 3383 </para> 3384 3385 <para>The <function>free()</function> function returns no 3386 value.</para> 3387 </refsect2> 3388 <refsect2> 3389 <title>Non-standard API</title> 3390 <para>The <function>mallocx()</function> and 3391 <function>rallocx()</function> functions return a pointer to 3392 the allocated memory if successful; otherwise a <constant>NULL</constant> 3393 pointer is returned to indicate insufficient contiguous memory was 3394 available to service the allocation request. </para> 3395 3396 <para>The <function>xallocx()</function> function returns the 3397 real size of the resulting resized allocation pointed to by 3398 <parameter>ptr</parameter>, which is a value less than 3399 <parameter>size</parameter> if the allocation could not be adequately 3400 grown in place. </para> 3401 3402 <para>The <function>sallocx()</function> function returns the 3403 real size of the allocation pointed to by <parameter>ptr</parameter>. 3404 </para> 3405 3406 <para>The <function>nallocx()</function> returns the real size 3407 that would result from a successful equivalent 3408 <function>mallocx()</function> function call, or zero if 3409 insufficient memory is available to perform the size computation. </para> 3410 3411 <para>The <function>mallctl()</function>, 3412 <function>mallctlnametomib()</function>, and 3413 <function>mallctlbymib()</function> functions return 0 on 3414 success; otherwise they return an error value. The functions will fail 3415 if: 3416 <variablelist> 3417 <varlistentry> 3418 <term><errorname>EINVAL</errorname></term> 3419 3420 <listitem><para><parameter>newp</parameter> is not 3421 <constant>NULL</constant>, and <parameter>newlen</parameter> is too 3422 large or too small. Alternatively, <parameter>*oldlenp</parameter> 3423 is too large or too small; in this case as much data as possible 3424 are read despite the error.</para></listitem> 3425 </varlistentry> 3426 <varlistentry> 3427 <term><errorname>ENOENT</errorname></term> 3428 3429 <listitem><para><parameter>name</parameter> or 3430 <parameter>mib</parameter> specifies an unknown/invalid 3431 value.</para></listitem> 3432 </varlistentry> 3433 <varlistentry> 3434 <term><errorname>EPERM</errorname></term> 3435 3436 <listitem><para>Attempt to read or write void value, or attempt to 3437 write read-only value.</para></listitem> 3438 </varlistentry> 3439 <varlistentry> 3440 <term><errorname>EAGAIN</errorname></term> 3441 3442 <listitem><para>A memory allocation failure 3443 occurred.</para></listitem> 3444 </varlistentry> 3445 <varlistentry> 3446 <term><errorname>EFAULT</errorname></term> 3447 3448 <listitem><para>An interface with side effects failed in some way 3449 not directly related to <function>mallctl*()</function> 3450 read/write processing.</para></listitem> 3451 </varlistentry> 3452 </variablelist> 3453 </para> 3454 3455 <para>The <function>malloc_usable_size()</function> function 3456 returns the usable size of the allocation pointed to by 3457 <parameter>ptr</parameter>. </para> 3458 </refsect2> 3459 </refsect1> 3460 <refsect1 id="environment"> 3461 <title>ENVIRONMENT</title> 3462 <para>The following environment variable affects the execution of the 3463 allocation functions: 3464 <variablelist> 3465 <varlistentry> 3466 <term><envar>MALLOC_CONF</envar></term> 3467 3468 <listitem><para>If the environment variable 3469 <envar>MALLOC_CONF</envar> is set, the characters it contains 3470 will be interpreted as options.</para></listitem> 3471 </varlistentry> 3472 </variablelist> 3473 </para> 3474 </refsect1> 3475 <refsect1 id="examples"> 3476 <title>EXAMPLES</title> 3477 <para>To dump core whenever a problem occurs: 3478 <screen>ln -s 'abort:true' /etc/malloc.conf</screen> 3479 </para> 3480 <para>To specify in the source that only one arena should be automatically 3481 created: 3482 <programlisting language="C"><![CDATA[ 3483malloc_conf = "narenas:1";]]></programlisting></para> 3484 </refsect1> 3485 <refsect1 id="see_also"> 3486 <title>SEE ALSO</title> 3487 <para><citerefentry><refentrytitle>madvise</refentrytitle> 3488 <manvolnum>2</manvolnum></citerefentry>, 3489 <citerefentry><refentrytitle>mmap</refentrytitle> 3490 <manvolnum>2</manvolnum></citerefentry>, 3491 <citerefentry><refentrytitle>sbrk</refentrytitle> 3492 <manvolnum>2</manvolnum></citerefentry>, 3493 <citerefentry><refentrytitle>utrace</refentrytitle> 3494 <manvolnum>2</manvolnum></citerefentry>, 3495 <citerefentry><refentrytitle>alloca</refentrytitle> 3496 <manvolnum>3</manvolnum></citerefentry>, 3497 <citerefentry><refentrytitle>atexit</refentrytitle> 3498 <manvolnum>3</manvolnum></citerefentry>, 3499 <citerefentry><refentrytitle>getpagesize</refentrytitle> 3500 <manvolnum>3</manvolnum></citerefentry></para> 3501 </refsect1> 3502 <refsect1 id="standards"> 3503 <title>STANDARDS</title> 3504 <para>The <function>malloc()</function>, 3505 <function>calloc()</function>, 3506 <function>realloc()</function>, and 3507 <function>free()</function> functions conform to ISO/IEC 3508 9899:1990 (<quote>ISO C90</quote>).</para> 3509 3510 <para>The <function>posix_memalign()</function> function conforms 3511 to IEEE Std 1003.1-2001 (<quote>POSIX.1</quote>).</para> 3512 </refsect1> 3513</refentry> 3514