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, 56 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.cache_oblivious"> 940 <term> 941 <mallctl>opt.cache_oblivious</mallctl> 942 (<type>bool</type>) 943 <literal>r-</literal> 944 </term> 945 <listitem><para>Enable / Disable cache-oblivious large allocation 946 alignment, for large requests with no alignment constraints. If this 947 feature is disabled, all large allocations are page-aligned as an 948 implementation artifact, which can severely harm CPU cache utilization. 949 However, the cache-oblivious layout comes at the cost of one extra page 950 per large allocation, which in the most extreme case increases physical 951 memory usage for the 16 KiB size class to 20 KiB. This option is enabled 952 by default.</para></listitem> 953 </varlistentry> 954 955 <varlistentry id="opt.metadata_thp"> 956 <term> 957 <mallctl>opt.metadata_thp</mallctl> 958 (<type>const char *</type>) 959 <literal>r-</literal> 960 </term> 961 <listitem><para>Controls whether to allow jemalloc to use transparent 962 huge page (THP) for internal metadata (see <link 963 linkend="stats.metadata">stats.metadata</link>). <quote>always</quote> 964 allows such usage. <quote>auto</quote> uses no THP initially, but may 965 begin to do so when metadata usage reaches certain level. The default 966 is <quote>disabled</quote>.</para></listitem> 967 </varlistentry> 968 969 <varlistentry id="opt.trust_madvise"> 970 <term> 971 <mallctl>opt.trust_madvise</mallctl> 972 (<type>bool</type>) 973 <literal>r-</literal> 974 </term> 975 <listitem><para>If true, do not perform runtime check for MADV_DONTNEED, 976 to check that it actually zeros pages. The default is disabled on Linux 977 and enabled elsewhere.</para></listitem> 978 </varlistentry> 979 980 <varlistentry id="opt.retain"> 981 <term> 982 <mallctl>opt.retain</mallctl> 983 (<type>bool</type>) 984 <literal>r-</literal> 985 </term> 986 <listitem><para>If true, retain unused virtual memory for later reuse 987 rather than discarding it by calling 988 <citerefentry><refentrytitle>munmap</refentrytitle> 989 <manvolnum>2</manvolnum></citerefentry> or equivalent (see <link 990 linkend="stats.retained">stats.retained</link> for related details). 991 It also makes jemalloc use <citerefentry> 992 <refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum> 993 </citerefentry> or equivalent in a more greedy way, mapping larger 994 chunks in one go. This option is disabled by default unless discarding 995 virtual memory is known to trigger platform-specific performance 996 problems, namely 1) for [64-bit] Linux, which has a quirk in its virtual 997 memory allocation algorithm that causes semi-permanent VM map holes 998 under normal jemalloc operation; and 2) for [64-bit] Windows, which 999 disallows split / merged regions with 1000 <parameter><constant>MEM_RELEASE</constant></parameter>. Although the 1001 same issues may present on 32-bit platforms as well, retaining virtual 1002 memory for 32-bit Linux and Windows is disabled by default due to the 1003 practical possibility of address space exhaustion. </para></listitem> 1004 </varlistentry> 1005 1006 <varlistentry id="opt.dss"> 1007 <term> 1008 <mallctl>opt.dss</mallctl> 1009 (<type>const char *</type>) 1010 <literal>r-</literal> 1011 </term> 1012 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 1013 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 1014 related to <citerefentry><refentrytitle>mmap</refentrytitle> 1015 <manvolnum>2</manvolnum></citerefentry> allocation. The following 1016 settings are supported if 1017 <citerefentry><refentrytitle>sbrk</refentrytitle> 1018 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 1019 system: <quote>disabled</quote>, <quote>primary</quote>, and 1020 <quote>secondary</quote>; otherwise only <quote>disabled</quote> is 1021 supported. The default is <quote>secondary</quote> if 1022 <citerefentry><refentrytitle>sbrk</refentrytitle> 1023 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 1024 system; <quote>disabled</quote> otherwise. 1025 </para></listitem> 1026 </varlistentry> 1027 1028 <varlistentry id="opt.narenas"> 1029 <term> 1030 <mallctl>opt.narenas</mallctl> 1031 (<type>unsigned</type>) 1032 <literal>r-</literal> 1033 </term> 1034 <listitem><para>Maximum number of arenas to use for automatic 1035 multiplexing of threads and arenas. The default is four times the 1036 number of CPUs, or one if there is a single CPU.</para></listitem> 1037 </varlistentry> 1038 1039 <varlistentry id="opt.oversize_threshold"> 1040 <term> 1041 <mallctl>opt.oversize_threshold</mallctl> 1042 (<type>size_t</type>) 1043 <literal>r-</literal> 1044 </term> 1045 <listitem><para>The threshold in bytes of which requests are considered 1046 oversize. Allocation requests with greater sizes are fulfilled from a 1047 dedicated arena (automatically managed, however not within 1048 <literal>narenas</literal>), in order to reduce fragmentation by not 1049 mixing huge allocations with small ones. In addition, the decay API 1050 guarantees on the extents greater than the specified threshold may be 1051 overridden. Note that requests with arena index specified via 1052 <constant>MALLOCX_ARENA</constant>, or threads associated with explicit 1053 arenas will not be considered. The default threshold is 8MiB. Values 1054 not within large size classes disables this feature.</para></listitem> 1055 </varlistentry> 1056 1057 <varlistentry id="opt.percpu_arena"> 1058 <term> 1059 <mallctl>opt.percpu_arena</mallctl> 1060 (<type>const char *</type>) 1061 <literal>r-</literal> 1062 </term> 1063 <listitem><para>Per CPU arena mode. Use the <quote>percpu</quote> 1064 setting to enable this feature, which uses number of CPUs to determine 1065 number of arenas, and bind threads to arenas dynamically based on the 1066 CPU the thread runs on currently. <quote>phycpu</quote> setting uses 1067 one arena per physical CPU, which means the two hyper threads on the 1068 same CPU share one arena. Note that no runtime checking regarding the 1069 availability of hyper threading is done at the moment. When set to 1070 <quote>disabled</quote>, narenas and thread to arena association will 1071 not be impacted by this option. The default is <quote>disabled</quote>. 1072 </para></listitem> 1073 </varlistentry> 1074 1075 <varlistentry id="opt.background_thread"> 1076 <term> 1077 <mallctl>opt.background_thread</mallctl> 1078 (<type>bool</type>) 1079 <literal>r-</literal> 1080 </term> 1081 <listitem><para>Internal background worker threads enabled/disabled. 1082 Because of potential circular dependencies, enabling background thread 1083 using this option may cause crash or deadlock during initialization. For 1084 a reliable way to use this feature, see <link 1085 linkend="background_thread">background_thread</link> for dynamic control 1086 options and details. This option is disabled by 1087 default.</para></listitem> 1088 </varlistentry> 1089 1090 <varlistentry id="opt.max_background_threads"> 1091 <term> 1092 <mallctl>opt.max_background_threads</mallctl> 1093 (<type>size_t</type>) 1094 <literal>r-</literal> 1095 </term> 1096 <listitem><para>Maximum number of background threads that will be created 1097 if <link linkend="background_thread">background_thread</link> is set. 1098 Defaults to number of cpus.</para></listitem> 1099 </varlistentry> 1100 1101 <varlistentry id="opt.dirty_decay_ms"> 1102 <term> 1103 <mallctl>opt.dirty_decay_ms</mallctl> 1104 (<type>ssize_t</type>) 1105 <literal>r-</literal> 1106 </term> 1107 <listitem><para>Approximate time in milliseconds from the creation of a 1108 set of unused dirty pages until an equivalent set of unused dirty pages 1109 is purged (i.e. converted to muzzy via e.g. 1110 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function> 1111 if supported by the operating system, or converted to clean otherwise) 1112 and/or reused. Dirty pages are defined as previously having been 1113 potentially written to by the application, and therefore consuming 1114 physical memory, yet having no current use. The pages are incrementally 1115 purged according to a sigmoidal decay curve that starts and ends with 1116 zero purge rate. A decay time of 0 causes all unused dirty pages to be 1117 purged immediately upon creation. A decay time of -1 disables purging. 1118 The default decay time is 10 seconds. See <link 1119 linkend="arenas.dirty_decay_ms"><mallctl>arenas.dirty_decay_ms</mallctl></link> 1120 and <link 1121 linkend="arena.i.dirty_decay_ms"><mallctl>arena.<i>.dirty_decay_ms</mallctl></link> 1122 for related dynamic control options. See <link 1123 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 1124 for a description of muzzy pages.for a description of muzzy pages. Note 1125 that when the <link 1126 linkend="opt.oversize_threshold"><mallctl>oversize_threshold</mallctl></link> 1127 feature is enabled, the arenas reserved for oversize requests may have 1128 its own default decay settings.</para></listitem> 1129 </varlistentry> 1130 1131 <varlistentry id="opt.muzzy_decay_ms"> 1132 <term> 1133 <mallctl>opt.muzzy_decay_ms</mallctl> 1134 (<type>ssize_t</type>) 1135 <literal>r-</literal> 1136 </term> 1137 <listitem><para>Approximate time in milliseconds from the creation of a 1138 set of unused muzzy pages until an equivalent set of unused muzzy pages 1139 is purged (i.e. converted to clean) and/or reused. Muzzy pages are 1140 defined as previously having been unused dirty pages that were 1141 subsequently purged in a manner that left them subject to the 1142 reclamation whims of the operating system (e.g. 1143 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function>), 1144 and therefore in an indeterminate state. The pages are incrementally 1145 purged according to a sigmoidal decay curve that starts and ends with 1146 zero purge rate. A decay time of 0 causes all unused muzzy pages to be 1147 purged immediately upon creation. A decay time of -1 disables purging. 1148 The default decay time is 10 seconds. See <link 1149 linkend="arenas.muzzy_decay_ms"><mallctl>arenas.muzzy_decay_ms</mallctl></link> 1150 and <link 1151 linkend="arena.i.muzzy_decay_ms"><mallctl>arena.<i>.muzzy_decay_ms</mallctl></link> 1152 for related dynamic control options.</para></listitem> 1153 </varlistentry> 1154 1155 <varlistentry id="opt.lg_extent_max_active_fit"> 1156 <term> 1157 <mallctl>opt.lg_extent_max_active_fit</mallctl> 1158 (<type>size_t</type>) 1159 <literal>r-</literal> 1160 </term> 1161 <listitem><para>When reusing dirty extents, this determines the (log 1162 base 2 of the) maximum ratio between the size of the active extent 1163 selected (to split off from) and the size of the requested allocation. 1164 This prevents the splitting of large active extents for smaller 1165 allocations, which can reduce fragmentation over the long run 1166 (especially for non-active extents). Lower value may reduce 1167 fragmentation, at the cost of extra active extents. The default value 1168 is 6, which gives a maximum ratio of 64 (2^6).</para></listitem> 1169 </varlistentry> 1170 1171 <varlistentry id="opt.stats_print"> 1172 <term> 1173 <mallctl>opt.stats_print</mallctl> 1174 (<type>bool</type>) 1175 <literal>r-</literal> 1176 </term> 1177 <listitem><para>Enable/disable statistics printing at exit. If 1178 enabled, the <function>malloc_stats_print()</function> 1179 function is called at program exit via an 1180 <citerefentry><refentrytitle>atexit</refentrytitle> 1181 <manvolnum>3</manvolnum></citerefentry> function. <link 1182 linkend="opt.stats_print_opts"><mallctl>opt.stats_print_opts</mallctl></link> 1183 can be combined to specify output options. If 1184 <option>--enable-stats</option> is specified during configuration, this 1185 has the potential to cause deadlock for a multi-threaded process that 1186 exits while one or more threads are executing in the memory allocation 1187 functions. Furthermore, <function>atexit()</function> may 1188 allocate memory during application initialization and then deadlock 1189 internally when jemalloc in turn calls 1190 <function>atexit()</function>, so this option is not 1191 universally usable (though the application can register its own 1192 <function>atexit()</function> function with equivalent 1193 functionality). Therefore, this option should only be used with care; 1194 it is primarily intended as a performance tuning aid during application 1195 development. This option is disabled by default.</para></listitem> 1196 </varlistentry> 1197 1198 <varlistentry id="opt.stats_print_opts"> 1199 <term> 1200 <mallctl>opt.stats_print_opts</mallctl> 1201 (<type>const char *</type>) 1202 <literal>r-</literal> 1203 </term> 1204 <listitem><para>Options (the <parameter>opts</parameter> string) to pass 1205 to the <function>malloc_stats_print()</function> at exit (enabled 1206 through <link 1207 linkend="opt.stats_print"><mallctl>opt.stats_print</mallctl></link>). See 1208 available options in <link 1209 linkend="malloc_stats_print_opts"><function>malloc_stats_print()</function></link>. 1210 Has no effect unless <link 1211 linkend="opt.stats_print"><mallctl>opt.stats_print</mallctl></link> is 1212 enabled. The default is <quote></quote>.</para></listitem> 1213 </varlistentry> 1214 1215 <varlistentry id="opt.stats_interval"> 1216 <term> 1217 <mallctl>opt.stats_interval</mallctl> 1218 (<type>int64_t</type>) 1219 <literal>r-</literal> 1220 </term> 1221 <listitem><para>Average interval between statistics outputs, as measured 1222 in bytes of allocation activity. The actual interval may be sporadic 1223 because decentralized event counters are used to avoid synchronization 1224 bottlenecks. The output may be triggered on any thread, which then 1225 calls <function>malloc_stats_print()</function>. <link 1226 linkend="opt.stats_interval_opts"><mallctl>opt.stats_interval_opts</mallctl></link> 1227 can be combined to specify output options. By default, 1228 interval-triggered stats output is disabled (encoded as 1229 -1).</para></listitem> 1230 </varlistentry> 1231 1232 <varlistentry id="opt.stats_interval_opts"> 1233 <term> 1234 <mallctl>opt.stats_interval_opts</mallctl> 1235 (<type>const char *</type>) 1236 <literal>r-</literal> 1237 </term> 1238 <listitem><para>Options (the <parameter>opts</parameter> string) to pass 1239 to the <function>malloc_stats_print()</function> for interval based 1240 statistics printing (enabled 1241 through <link 1242 linkend="opt.stats_interval"><mallctl>opt.stats_interval</mallctl></link>). See 1243 available options in <link 1244 linkend="malloc_stats_print_opts"><function>malloc_stats_print()</function></link>. 1245 Has no effect unless <link 1246 linkend="opt.stats_interval"><mallctl>opt.stats_interval</mallctl></link> is 1247 enabled. The default is <quote></quote>.</para></listitem> 1248 </varlistentry> 1249 1250 <varlistentry id="opt.junk"> 1251 <term> 1252 <mallctl>opt.junk</mallctl> 1253 (<type>const char *</type>) 1254 <literal>r-</literal> 1255 [<option>--enable-fill</option>] 1256 </term> 1257 <listitem><para>Junk filling. If set to <quote>alloc</quote>, each byte 1258 of uninitialized allocated memory will be initialized to 1259 <literal>0xa5</literal>. If set to <quote>free</quote>, all deallocated 1260 memory will be initialized to <literal>0x5a</literal>. If set to 1261 <quote>true</quote>, both allocated and deallocated memory will be 1262 initialized, and if set to <quote>false</quote>, junk filling be 1263 disabled entirely. This is intended for debugging and will impact 1264 performance negatively. This option is <quote>false</quote> by default 1265 unless <option>--enable-debug</option> is specified during 1266 configuration, in which case it is <quote>true</quote> by 1267 default.</para></listitem> 1268 </varlistentry> 1269 1270 <varlistentry id="opt.zero"> 1271 <term> 1272 <mallctl>opt.zero</mallctl> 1273 (<type>bool</type>) 1274 <literal>r-</literal> 1275 [<option>--enable-fill</option>] 1276 </term> 1277 <listitem><para>Zero filling enabled/disabled. If enabled, each byte 1278 of uninitialized allocated memory will be initialized to 0. Note that 1279 this initialization only happens once for each byte, so 1280 <function>realloc()</function> and 1281 <function>rallocx()</function> calls do not zero memory that 1282 was previously allocated. This is intended for debugging and will 1283 impact performance negatively. This option is disabled by default. 1284 </para></listitem> 1285 </varlistentry> 1286 1287 <varlistentry id="opt.utrace"> 1288 <term> 1289 <mallctl>opt.utrace</mallctl> 1290 (<type>bool</type>) 1291 <literal>r-</literal> 1292 [<option>--enable-utrace</option>] 1293 </term> 1294 <listitem><para>Allocation tracing based on 1295 <citerefentry><refentrytitle>utrace</refentrytitle> 1296 <manvolnum>2</manvolnum></citerefentry> enabled/disabled. This option 1297 is disabled by default.</para></listitem> 1298 </varlistentry> 1299 1300 <varlistentry id="opt.xmalloc"> 1301 <term> 1302 <mallctl>opt.xmalloc</mallctl> 1303 (<type>bool</type>) 1304 <literal>r-</literal> 1305 [<option>--enable-xmalloc</option>] 1306 </term> 1307 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled, 1308 rather than returning failure for any allocation function, display a 1309 diagnostic message on <constant>STDERR_FILENO</constant> and cause the 1310 program to drop core (using 1311 <citerefentry><refentrytitle>abort</refentrytitle> 1312 <manvolnum>3</manvolnum></citerefentry>). If an application is 1313 designed to depend on this behavior, set the option at compile time by 1314 including the following in the source code: 1315 <programlisting language="C"><![CDATA[ 1316malloc_conf = "xmalloc:true";]]></programlisting> 1317 This option is disabled by default.</para></listitem> 1318 </varlistentry> 1319 1320 <varlistentry id="opt.tcache"> 1321 <term> 1322 <mallctl>opt.tcache</mallctl> 1323 (<type>bool</type>) 1324 <literal>r-</literal> 1325 </term> 1326 <listitem><para>Thread-specific caching (tcache) enabled/disabled. When 1327 there are multiple threads, each thread uses a tcache for objects up to 1328 a certain size. Thread-specific caching allows many allocations to be 1329 satisfied without performing any thread synchronization, at the cost of 1330 increased memory use. See the <link 1331 linkend="opt.tcache_max"><mallctl>opt.tcache_max</mallctl></link> 1332 option for related tuning information. This option is enabled by 1333 default.</para></listitem> 1334 </varlistentry> 1335 1336 <varlistentry id="opt.tcache_max"> 1337 <term> 1338 <mallctl>opt.tcache_max</mallctl> 1339 (<type>size_t</type>) 1340 <literal>r-</literal> 1341 </term> 1342 <listitem><para>Maximum size class to cache in the thread-specific cache 1343 (tcache). At a minimum, the first size class is cached; and at a 1344 maximum, size classes up to 8 MiB can be cached. The default maximum is 1345 32 KiB (2^15). As a convenience, this may also be set by specifying 1346 lg_tcache_max, which will be taken to be the base-2 logarithm of the 1347 setting of tcache_max.</para></listitem> 1348 </varlistentry> 1349 1350 <varlistentry id="opt.thp"> 1351 <term> 1352 <mallctl>opt.thp</mallctl> 1353 (<type>const char *</type>) 1354 <literal>r-</literal> 1355 </term> 1356 <listitem><para>Transparent hugepage (THP) mode. Settings "always", 1357 "never" and "default" are available if THP is supported by the operating 1358 system. The "always" setting enables transparent hugepage for all user 1359 memory mappings with 1360 <parameter><constant>MADV_HUGEPAGE</constant></parameter>; "never" 1361 ensures no transparent hugepage with 1362 <parameter><constant>MADV_NOHUGEPAGE</constant></parameter>; the default 1363 setting "default" makes no changes. Note that: this option does not 1364 affect THP for jemalloc internal metadata (see <link 1365 linkend="opt.metadata_thp"><mallctl>opt.metadata_thp</mallctl></link>); 1366 in addition, for arenas with customized <link 1367 linkend="arena.i.extent_hooks"><mallctl>extent_hooks</mallctl></link>, 1368 this option is bypassed as it is implemented as part of the default 1369 extent hooks.</para></listitem> 1370 </varlistentry> 1371 1372 <varlistentry id="opt.prof"> 1373 <term> 1374 <mallctl>opt.prof</mallctl> 1375 (<type>bool</type>) 1376 <literal>r-</literal> 1377 [<option>--enable-prof</option>] 1378 </term> 1379 <listitem><para>Memory profiling enabled/disabled. If enabled, profile 1380 memory allocation activity. See the <link 1381 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 1382 option for on-the-fly activation/deactivation. See the <link 1383 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 1384 option for probabilistic sampling control. See the <link 1385 linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> 1386 option for control of cumulative sample reporting. See the <link 1387 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 1388 option for information on interval-triggered profile dumping, the <link 1389 linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link> 1390 option for information on high-water-triggered profile dumping, and the 1391 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link> 1392 option for final profile dumping. Profile output is compatible with 1393 the <command>jeprof</command> command, which is based on the 1394 <command>pprof</command> that is developed as part of the <ulink 1395 url="http://code.google.com/p/gperftools/">gperftools 1396 package</ulink>. See <link linkend="heap_profile_format">HEAP PROFILE 1397 FORMAT</link> for heap profile format documentation.</para></listitem> 1398 </varlistentry> 1399 1400 <varlistentry id="opt.prof_prefix"> 1401 <term> 1402 <mallctl>opt.prof_prefix</mallctl> 1403 (<type>const char *</type>) 1404 <literal>r-</literal> 1405 [<option>--enable-prof</option>] 1406 </term> 1407 <listitem><para>Filename prefix for profile dumps. If the prefix is 1408 set to the empty string, no automatic dumps will occur; this is 1409 primarily useful for disabling the automatic final heap dump (which 1410 also disables leak reporting, if enabled). The default prefix is 1411 <filename>jeprof</filename>. This prefix value can be overridden by 1412 <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link>. 1413 </para></listitem> 1414 </varlistentry> 1415 1416 <varlistentry id="opt.prof_active"> 1417 <term> 1418 <mallctl>opt.prof_active</mallctl> 1419 (<type>bool</type>) 1420 <literal>r-</literal> 1421 [<option>--enable-prof</option>] 1422 </term> 1423 <listitem><para>Profiling activated/deactivated. This is a secondary 1424 control mechanism that makes it possible to start the application with 1425 profiling enabled (see the <link 1426 linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but 1427 inactive, then toggle profiling at any time during program execution 1428 with the <link 1429 linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl. 1430 This option is enabled by default.</para></listitem> 1431 </varlistentry> 1432 1433 <varlistentry id="opt.prof_thread_active_init"> 1434 <term> 1435 <mallctl>opt.prof_thread_active_init</mallctl> 1436 (<type>bool</type>) 1437 <literal>r-</literal> 1438 [<option>--enable-prof</option>] 1439 </term> 1440 <listitem><para>Initial setting for <link 1441 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 1442 in newly created threads. The initial setting for newly created threads 1443 can also be changed during execution via the <link 1444 linkend="prof.thread_active_init"><mallctl>prof.thread_active_init</mallctl></link> 1445 mallctl. This option is enabled by default.</para></listitem> 1446 </varlistentry> 1447 1448 <varlistentry id="opt.lg_prof_sample"> 1449 <term> 1450 <mallctl>opt.lg_prof_sample</mallctl> 1451 (<type>size_t</type>) 1452 <literal>r-</literal> 1453 [<option>--enable-prof</option>] 1454 </term> 1455 <listitem><para>Average interval (log base 2) between allocation 1456 samples, as measured in bytes of allocation activity. Increasing the 1457 sampling interval decreases profile fidelity, but also decreases the 1458 computational overhead. The default sample interval is 512 KiB (2^19 1459 B).</para></listitem> 1460 </varlistentry> 1461 1462 <varlistentry id="opt.prof_accum"> 1463 <term> 1464 <mallctl>opt.prof_accum</mallctl> 1465 (<type>bool</type>) 1466 <literal>r-</literal> 1467 [<option>--enable-prof</option>] 1468 </term> 1469 <listitem><para>Reporting of cumulative object/byte counts in profile 1470 dumps enabled/disabled. If this option is enabled, every unique 1471 backtrace must be stored for the duration of execution. Depending on 1472 the application, this can impose a large memory overhead, and the 1473 cumulative counts are not always of interest. This option is disabled 1474 by default.</para></listitem> 1475 </varlistentry> 1476 1477 <varlistentry id="opt.lg_prof_interval"> 1478 <term> 1479 <mallctl>opt.lg_prof_interval</mallctl> 1480 (<type>ssize_t</type>) 1481 <literal>r-</literal> 1482 [<option>--enable-prof</option>] 1483 </term> 1484 <listitem><para>Average interval (log base 2) between memory profile 1485 dumps, as measured in bytes of allocation activity. The actual 1486 interval between dumps may be sporadic because decentralized allocation 1487 counters are used to avoid synchronization bottlenecks. Profiles are 1488 dumped to files named according to the pattern 1489 <filename><prefix>.<pid>.<seq>.i<iseq>.heap</filename>, 1490 where <literal><prefix></literal> is controlled by the 1491 <link 1492 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> and 1493 <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link> 1494 options. By default, interval-triggered profile dumping is disabled 1495 (encoded as -1). 1496 </para></listitem> 1497 </varlistentry> 1498 1499 <varlistentry id="opt.prof_gdump"> 1500 <term> 1501 <mallctl>opt.prof_gdump</mallctl> 1502 (<type>bool</type>) 1503 <literal>r-</literal> 1504 [<option>--enable-prof</option>] 1505 </term> 1506 <listitem><para>Set the initial state of <link 1507 linkend="prof.gdump"><mallctl>prof.gdump</mallctl></link>, which when 1508 enabled triggers a memory profile dump every time the total virtual 1509 memory exceeds the previous maximum. This option is disabled by 1510 default.</para></listitem> 1511 </varlistentry> 1512 1513 <varlistentry id="opt.prof_final"> 1514 <term> 1515 <mallctl>opt.prof_final</mallctl> 1516 (<type>bool</type>) 1517 <literal>r-</literal> 1518 [<option>--enable-prof</option>] 1519 </term> 1520 <listitem><para>Use an 1521 <citerefentry><refentrytitle>atexit</refentrytitle> 1522 <manvolnum>3</manvolnum></citerefentry> function to dump final memory 1523 usage to a file named according to the pattern 1524 <filename><prefix>.<pid>.<seq>.f.heap</filename>, 1525 where <literal><prefix></literal> is controlled by the <link 1526 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> and 1527 <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link> 1528 options. Note that <function>atexit()</function> may allocate 1529 memory during application initialization and then deadlock internally 1530 when jemalloc in turn calls <function>atexit()</function>, so 1531 this option is not universally usable (though the application can 1532 register its own <function>atexit()</function> function with 1533 equivalent functionality). This option is disabled by 1534 default.</para></listitem> 1535 </varlistentry> 1536 1537 <varlistentry id="opt.prof_leak"> 1538 <term> 1539 <mallctl>opt.prof_leak</mallctl> 1540 (<type>bool</type>) 1541 <literal>r-</literal> 1542 [<option>--enable-prof</option>] 1543 </term> 1544 <listitem><para>Leak reporting enabled/disabled. If enabled, use an 1545 <citerefentry><refentrytitle>atexit</refentrytitle> 1546 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks 1547 detected by allocation sampling. See the 1548 <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for 1549 information on analyzing heap profile output. Works only when combined 1550 with <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl> 1551 </link>, otherwise does nothing. This option is disabled by default. 1552 </para></listitem> 1553 </varlistentry> 1554 1555 <varlistentry id="opt.prof_leak_error"> 1556 <term> 1557 <mallctl>opt.prof_leak_error</mallctl> 1558 (<type>bool</type>) 1559 <literal>r-</literal> 1560 [<option>--enable-prof</option>] 1561 </term> 1562 <listitem><para>Similar to <link linkend="opt.prof_leak"><mallctl> 1563 opt.prof_leak</mallctl></link>, but makes the process exit with error 1564 code 1 if a memory leak is detected. This option supersedes 1565 <link linkend="opt.prof_leak"><mallctl>opt.prof_leak</mallctl></link>, 1566 meaning that if both are specified, this option takes precedence. When 1567 enabled, also enables <link linkend="opt.prof_leak"><mallctl> 1568 opt.prof_leak</mallctl></link>. Works only when combined with 1569 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link>, 1570 otherwise does nothing. This option is disabled by default. 1571 </para></listitem> 1572 </varlistentry> 1573 1574 <varlistentry id="opt.zero_realloc"> 1575 <term> 1576 <mallctl>opt.zero_realloc</mallctl> 1577 (<type>const char *</type>) 1578 <literal>r-</literal> 1579 </term> 1580 <listitem><para> Determines the behavior of 1581 <function>realloc()</function> when passed a value of zero for the new 1582 size. <quote>alloc</quote> treats this as an allocation of size zero 1583 (and returns a non-null result except in case of resource exhaustion). 1584 <quote>free</quote> treats this as a deallocation of the pointer, and 1585 returns <constant>NULL</constant> without setting 1586 <varname>errno</varname>. <quote>abort</quote> aborts the process if 1587 zero is passed. The default is <quote>free</quote> on Linux and 1588 Windows, and <quote>alloc</quote> elsewhere.</para> 1589 1590 <para>There is considerable divergence of behaviors across 1591 implementations in handling this case. Many have the behavior of 1592 <quote>free</quote>. This can introduce security vulnerabilities, since 1593 a <constant>NULL</constant> return value indicates failure, and the 1594 continued validity of the passed-in pointer (per POSIX and C11). 1595 <quote>alloc</quote> is safe, but can cause leaks in programs that 1596 expect the common behavior. Programs intended to be portable and 1597 leak-free cannot assume either behavior, and must therefore never call 1598 realloc with a size of 0. The <quote>abort</quote> option enables these 1599 testing this behavior.</para></listitem> 1600 </varlistentry> 1601 1602 <varlistentry id="thread.arena"> 1603 <term> 1604 <mallctl>thread.arena</mallctl> 1605 (<type>unsigned</type>) 1606 <literal>rw</literal> 1607 </term> 1608 <listitem><para>Get or set the arena associated with the calling 1609 thread. If the specified arena was not initialized beforehand (see the 1610 <link 1611 linkend="arena.i.initialized"><mallctl>arena.i.initialized</mallctl></link> 1612 mallctl), it will be automatically initialized as a side effect of 1613 calling this interface.</para></listitem> 1614 </varlistentry> 1615 1616 <varlistentry id="thread.allocated"> 1617 <term> 1618 <mallctl>thread.allocated</mallctl> 1619 (<type>uint64_t</type>) 1620 <literal>r-</literal> 1621 [<option>--enable-stats</option>] 1622 </term> 1623 <listitem><para>Get the total number of bytes ever allocated by the 1624 calling thread. This counter has the potential to wrap around; it is 1625 up to the application to appropriately interpret the counter in such 1626 cases.</para></listitem> 1627 </varlistentry> 1628 1629 <varlistentry id="thread.allocatedp"> 1630 <term> 1631 <mallctl>thread.allocatedp</mallctl> 1632 (<type>uint64_t *</type>) 1633 <literal>r-</literal> 1634 [<option>--enable-stats</option>] 1635 </term> 1636 <listitem><para>Get a pointer to the the value that is returned by the 1637 <link 1638 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 1639 mallctl. This is useful for avoiding the overhead of repeated 1640 <function>mallctl*()</function> calls. Note that the underlying counter 1641 should not be modified by the application.</para></listitem> 1642 </varlistentry> 1643 1644 <varlistentry id="thread.deallocated"> 1645 <term> 1646 <mallctl>thread.deallocated</mallctl> 1647 (<type>uint64_t</type>) 1648 <literal>r-</literal> 1649 [<option>--enable-stats</option>] 1650 </term> 1651 <listitem><para>Get the total number of bytes ever deallocated by the 1652 calling thread. This counter has the potential to wrap around; it is 1653 up to the application to appropriately interpret the counter in such 1654 cases.</para></listitem> 1655 </varlistentry> 1656 1657 <varlistentry id="thread.deallocatedp"> 1658 <term> 1659 <mallctl>thread.deallocatedp</mallctl> 1660 (<type>uint64_t *</type>) 1661 <literal>r-</literal> 1662 [<option>--enable-stats</option>] 1663 </term> 1664 <listitem><para>Get a pointer to the the value that is returned by the 1665 <link 1666 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link> 1667 mallctl. This is useful for avoiding the overhead of repeated 1668 <function>mallctl*()</function> calls. Note that the underlying counter 1669 should not be modified by the application.</para></listitem> 1670 </varlistentry> 1671 1672 <varlistentry id="thread.peak.read"> 1673 <term> 1674 <mallctl>thread.peak.read</mallctl> 1675 (<type>uint64_t</type>) 1676 <literal>r-</literal> 1677 [<option>--enable-stats</option>] 1678 </term> 1679 <listitem><para>Get an approximation of the maximum value of the 1680 difference between the number of bytes allocated and the number of bytes 1681 deallocated by the calling thread since the last call to <link 1682 linkend="thread.peak.reset"><mallctl>thread.peak.reset</mallctl></link>, 1683 or since the thread's creation if it has not called <link 1684 linkend="thread.peak.reset"><mallctl>thread.peak.reset</mallctl></link>. 1685 No guarantees are made about the quality of the approximation, but 1686 jemalloc currently endeavors to maintain accuracy to within one hundred 1687 kilobytes. 1688 </para></listitem> 1689 </varlistentry> 1690 1691 <varlistentry id="thread.peak.reset"> 1692 <term> 1693 <mallctl>thread.peak.reset</mallctl> 1694 (<type>void</type>) 1695 <literal>--</literal> 1696 [<option>--enable-stats</option>] 1697 </term> 1698 <listitem><para>Resets the counter for net bytes allocated in the calling 1699 thread to zero. This affects subsequent calls to <link 1700 linkend="thread.peak.read"><mallctl>thread.peak.read</mallctl></link>, 1701 but not the values returned by <link 1702 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 1703 or <link 1704 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link>. 1705 </para></listitem> 1706 </varlistentry> 1707 1708 <varlistentry id="thread.tcache.enabled"> 1709 <term> 1710 <mallctl>thread.tcache.enabled</mallctl> 1711 (<type>bool</type>) 1712 <literal>rw</literal> 1713 </term> 1714 <listitem><para>Enable/disable calling thread's tcache. The tcache is 1715 implicitly flushed as a side effect of becoming 1716 disabled (see <link 1717 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>). 1718 </para></listitem> 1719 </varlistentry> 1720 1721 <varlistentry id="thread.tcache.flush"> 1722 <term> 1723 <mallctl>thread.tcache.flush</mallctl> 1724 (<type>void</type>) 1725 <literal>--</literal> 1726 </term> 1727 <listitem><para>Flush calling thread's thread-specific cache (tcache). 1728 This interface releases all cached objects and internal data structures 1729 associated with the calling thread's tcache. Ordinarily, this interface 1730 need not be called, since automatic periodic incremental garbage 1731 collection occurs, and the thread cache is automatically discarded when 1732 a thread exits. However, garbage collection is triggered by allocation 1733 activity, so it is possible for a thread that stops 1734 allocating/deallocating to retain its cache indefinitely, in which case 1735 the developer may find manual flushing useful.</para></listitem> 1736 </varlistentry> 1737 1738 <varlistentry id="thread.prof.name"> 1739 <term> 1740 <mallctl>thread.prof.name</mallctl> 1741 (<type>const char *</type>) 1742 <literal>r-</literal> or 1743 <literal>-w</literal> 1744 [<option>--enable-prof</option>] 1745 </term> 1746 <listitem><para>Get/set the descriptive name associated with the calling 1747 thread in memory profile dumps. An internal copy of the name string is 1748 created, so the input string need not be maintained after this interface 1749 completes execution. The output string of this interface should be 1750 copied for non-ephemeral uses, because multiple implementation details 1751 can cause asynchronous string deallocation. Furthermore, each 1752 invocation of this interface can only read or write; simultaneous 1753 read/write is not supported due to string lifetime limitations. The 1754 name string must be nil-terminated and comprised only of characters in 1755 the sets recognized 1756 by <citerefentry><refentrytitle>isgraph</refentrytitle> 1757 <manvolnum>3</manvolnum></citerefentry> and 1758 <citerefentry><refentrytitle>isblank</refentrytitle> 1759 <manvolnum>3</manvolnum></citerefentry>.</para></listitem> 1760 </varlistentry> 1761 1762 <varlistentry id="thread.prof.active"> 1763 <term> 1764 <mallctl>thread.prof.active</mallctl> 1765 (<type>bool</type>) 1766 <literal>rw</literal> 1767 [<option>--enable-prof</option>] 1768 </term> 1769 <listitem><para>Control whether sampling is currently active for the 1770 calling thread. This is an activation mechanism in addition to <link 1771 linkend="prof.active"><mallctl>prof.active</mallctl></link>; both must 1772 be active for the calling thread to sample. This flag is enabled by 1773 default.</para></listitem> 1774 </varlistentry> 1775 1776 <varlistentry id="thread.idle"> 1777 <term> 1778 <mallctl>thread.idle</mallctl> 1779 (<type>void</type>) 1780 <literal>--</literal> 1781 </term> 1782 <listitem><para>Hints to jemalloc that the calling thread will be idle 1783 for some nontrivial period of time (say, on the order of seconds), and 1784 that doing some cleanup operations may be beneficial. There are no 1785 guarantees as to what specific operations will be performed; currently 1786 this flushes the caller's tcache and may (according to some heuristic) 1787 purge its associated arena.</para> 1788 <para>This is not intended to be a general-purpose background activity 1789 mechanism, and threads should not wake up multiple times solely to call 1790 it. Rather, a thread waiting for a task should do a timed wait first, 1791 call <link linkend="thread.idle"><mallctl>thread.idle</mallctl></link> 1792 if no task appears in the timeout interval, and then do an untimed wait. 1793 For such a background activity mechanism, see 1794 <link linkend="background_thread"><mallctl>background_thread</mallctl></link>. 1795 </para></listitem> 1796 </varlistentry> 1797 1798 <varlistentry id="tcache.create"> 1799 <term> 1800 <mallctl>tcache.create</mallctl> 1801 (<type>unsigned</type>) 1802 <literal>r-</literal> 1803 </term> 1804 <listitem><para>Create an explicit thread-specific cache (tcache) and 1805 return an identifier that can be passed to the <link 1806 linkend="MALLOCX_TCACHE"><constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant></link> 1807 macro to explicitly use the specified cache rather than the 1808 automatically managed one that is used by default. Each explicit cache 1809 can be used by only one thread at a time; the application must assure 1810 that this constraint holds. 1811 </para> 1812 1813 <para>If the amount of space supplied for storing the thread-specific 1814 cache identifier does not equal 1815 <code language="C">sizeof(<type>unsigned</type>)</code>, no 1816 thread-specific cache will be created, no data will be written to the 1817 space pointed by <parameter>oldp</parameter>, and 1818 <parameter>*oldlenp</parameter> will be set to 0. 1819 </para></listitem> 1820 1821 </varlistentry> 1822 1823 <varlistentry id="tcache.flush"> 1824 <term> 1825 <mallctl>tcache.flush</mallctl> 1826 (<type>unsigned</type>) 1827 <literal>-w</literal> 1828 </term> 1829 <listitem><para>Flush the specified thread-specific cache (tcache). The 1830 same considerations apply to this interface as to <link 1831 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>, 1832 except that the tcache will never be automatically discarded. 1833 </para></listitem> 1834 </varlistentry> 1835 1836 <varlistentry id="tcache.destroy"> 1837 <term> 1838 <mallctl>tcache.destroy</mallctl> 1839 (<type>unsigned</type>) 1840 <literal>-w</literal> 1841 </term> 1842 <listitem><para>Flush the specified thread-specific cache (tcache) and 1843 make the identifier available for use during a future tcache creation. 1844 </para></listitem> 1845 </varlistentry> 1846 1847 <varlistentry id="arena.i.initialized"> 1848 <term> 1849 <mallctl>arena.<i>.initialized</mallctl> 1850 (<type>bool</type>) 1851 <literal>r-</literal> 1852 </term> 1853 <listitem><para>Get whether the specified arena's statistics are 1854 initialized (i.e. the arena was initialized prior to the current epoch). 1855 This interface can also be nominally used to query whether the merged 1856 statistics corresponding to <constant>MALLCTL_ARENAS_ALL</constant> are 1857 initialized (always true).</para></listitem> 1858 </varlistentry> 1859 1860 <varlistentry id="arena.i.decay"> 1861 <term> 1862 <mallctl>arena.<i>.decay</mallctl> 1863 (<type>void</type>) 1864 <literal>--</literal> 1865 </term> 1866 <listitem><para>Trigger decay-based purging of unused dirty/muzzy pages 1867 for arena <i>, or for all arenas if <i> equals 1868 <constant>MALLCTL_ARENAS_ALL</constant>. The proportion of unused 1869 dirty/muzzy pages to be purged depends on the current time; see <link 1870 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 1871 and <link 1872 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzy_decay_ms</mallctl></link> 1873 for details.</para></listitem> 1874 </varlistentry> 1875 1876 <varlistentry id="arena.i.purge"> 1877 <term> 1878 <mallctl>arena.<i>.purge</mallctl> 1879 (<type>void</type>) 1880 <literal>--</literal> 1881 </term> 1882 <listitem><para>Purge all unused dirty pages for arena <i>, or for 1883 all arenas if <i> equals <constant>MALLCTL_ARENAS_ALL</constant>. 1884 </para></listitem> 1885 </varlistentry> 1886 1887 <varlistentry id="arena.i.reset"> 1888 <term> 1889 <mallctl>arena.<i>.reset</mallctl> 1890 (<type>void</type>) 1891 <literal>--</literal> 1892 </term> 1893 <listitem><para>Discard all of the arena's extant allocations. This 1894 interface can only be used with arenas explicitly created via <link 1895 linkend="arenas.create"><mallctl>arenas.create</mallctl></link>. None 1896 of the arena's discarded/cached allocations may accessed afterward. As 1897 part of this requirement, all thread caches which were used to 1898 allocate/deallocate in conjunction with the arena must be flushed 1899 beforehand.</para></listitem> 1900 </varlistentry> 1901 1902 <varlistentry id="arena.i.destroy"> 1903 <term> 1904 <mallctl>arena.<i>.destroy</mallctl> 1905 (<type>void</type>) 1906 <literal>--</literal> 1907 </term> 1908 <listitem><para>Destroy the arena. Discard all of the arena's extant 1909 allocations using the same mechanism as for <link 1910 linkend="arena.i.reset"><mallctl>arena.<i>.reset</mallctl></link> 1911 (with all the same constraints and side effects), merge the arena stats 1912 into those accessible at arena index 1913 <constant>MALLCTL_ARENAS_DESTROYED</constant>, and then completely 1914 discard all metadata associated with the arena. Future calls to <link 1915 linkend="arenas.create"><mallctl>arenas.create</mallctl></link> may 1916 recycle the arena index. Destruction will fail if any threads are 1917 currently associated with the arena as a result of calls to <link 1918 linkend="thread.arena"><mallctl>thread.arena</mallctl></link>.</para></listitem> 1919 </varlistentry> 1920 1921 <varlistentry id="arena.i.dss"> 1922 <term> 1923 <mallctl>arena.<i>.dss</mallctl> 1924 (<type>const char *</type>) 1925 <literal>rw</literal> 1926 </term> 1927 <listitem><para>Set the precedence of dss allocation as related to mmap 1928 allocation for arena <i>, or for all arenas if <i> equals 1929 <constant>MALLCTL_ARENAS_ALL</constant>. See <link 1930 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for supported 1931 settings.</para></listitem> 1932 </varlistentry> 1933 1934 <varlistentry id="arena.i.dirty_decay_ms"> 1935 <term> 1936 <mallctl>arena.<i>.dirty_decay_ms</mallctl> 1937 (<type>ssize_t</type>) 1938 <literal>rw</literal> 1939 </term> 1940 <listitem><para>Current per-arena approximate time in milliseconds from 1941 the creation of a set of unused dirty pages until an equivalent set of 1942 unused dirty pages is purged and/or reused. Each time this interface is 1943 set, all currently unused dirty pages are considered to have fully 1944 decayed, which causes immediate purging of all unused dirty pages unless 1945 the decay time is set to -1 (i.e. purging disabled). See <link 1946 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 1947 for additional information.</para></listitem> 1948 </varlistentry> 1949 1950 <varlistentry id="arena.i.muzzy_decay_ms"> 1951 <term> 1952 <mallctl>arena.<i>.muzzy_decay_ms</mallctl> 1953 (<type>ssize_t</type>) 1954 <literal>rw</literal> 1955 </term> 1956 <listitem><para>Current per-arena approximate time in milliseconds from 1957 the creation of a set of unused muzzy pages until an equivalent set of 1958 unused muzzy pages is purged and/or reused. Each time this interface is 1959 set, all currently unused muzzy pages are considered to have fully 1960 decayed, which causes immediate purging of all unused muzzy pages unless 1961 the decay time is set to -1 (i.e. purging disabled). See <link 1962 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 1963 for additional information.</para></listitem> 1964 </varlistentry> 1965 1966 <varlistentry id="arena.i.retain_grow_limit"> 1967 <term> 1968 <mallctl>arena.<i>.retain_grow_limit</mallctl> 1969 (<type>size_t</type>) 1970 <literal>rw</literal> 1971 </term> 1972 <listitem><para>Maximum size to grow retained region (only relevant when 1973 <link linkend="opt.retain"><mallctl>opt.retain</mallctl></link> is 1974 enabled). This controls the maximum increment to expand virtual memory, 1975 or allocation through <link 1976 linkend="arena.i.extent_hooks"><mallctl>arena.<i>extent_hooks</mallctl></link>. 1977 In particular, if customized extent hooks reserve physical memory 1978 (e.g. 1G huge pages), this is useful to control the allocation hook's 1979 input size. The default is no limit.</para></listitem> 1980 </varlistentry> 1981 1982 <varlistentry id="arena.i.extent_hooks"> 1983 <term> 1984 <mallctl>arena.<i>.extent_hooks</mallctl> 1985 (<type>extent_hooks_t *</type>) 1986 <literal>rw</literal> 1987 </term> 1988 <listitem><para>Get or set the extent management hook functions for 1989 arena <i>. The functions must be capable of operating on all 1990 extant extents associated with arena <i>, usually by passing 1991 unknown extents to the replaced functions. In practice, it is feasible 1992 to control allocation for arenas explicitly created via <link 1993 linkend="arenas.create"><mallctl>arenas.create</mallctl></link> such 1994 that all extents originate from an application-supplied extent allocator 1995 (by specifying the custom extent hook functions during arena creation). 1996 However, the API guarantees for the automatically created arenas may be 1997 relaxed -- hooks set there may be called in a "best effort" fashion; in 1998 addition there may be extents created prior to the application having an 1999 opportunity to take over extent allocation.</para> 2000 2001 <programlisting language="C"><![CDATA[ 2002typedef extent_hooks_s extent_hooks_t; 2003struct extent_hooks_s { 2004 extent_alloc_t *alloc; 2005 extent_dalloc_t *dalloc; 2006 extent_destroy_t *destroy; 2007 extent_commit_t *commit; 2008 extent_decommit_t *decommit; 2009 extent_purge_t *purge_lazy; 2010 extent_purge_t *purge_forced; 2011 extent_split_t *split; 2012 extent_merge_t *merge; 2013};]]></programlisting> 2014 <para>The <type>extent_hooks_t</type> structure comprises function 2015 pointers which are described individually below. jemalloc uses these 2016 functions to manage extent lifetime, which starts off with allocation of 2017 mapped committed memory, in the simplest case followed by deallocation. 2018 However, there are performance and platform reasons to retain extents 2019 for later reuse. Cleanup attempts cascade from deallocation to decommit 2020 to forced purging to lazy purging, which gives the extent management 2021 functions opportunities to reject the most permanent cleanup operations 2022 in favor of less permanent (and often less costly) operations. All 2023 operations except allocation can be universally opted out of by setting 2024 the hook pointers to <constant>NULL</constant>, or selectively opted out 2025 of by returning failure. Note that once the extent hook is set, the 2026 structure is accessed directly by the associated arenas, so it must 2027 remain valid for the entire lifetime of the arenas.</para> 2028 2029 <funcsynopsis><funcprototype> 2030 <funcdef>typedef void *<function>(extent_alloc_t)</function></funcdef> 2031 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2032 <paramdef>void *<parameter>new_addr</parameter></paramdef> 2033 <paramdef>size_t <parameter>size</parameter></paramdef> 2034 <paramdef>size_t <parameter>alignment</parameter></paramdef> 2035 <paramdef>bool *<parameter>zero</parameter></paramdef> 2036 <paramdef>bool *<parameter>commit</parameter></paramdef> 2037 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2038 </funcprototype></funcsynopsis> 2039 <literallayout></literallayout> 2040 <para>An extent allocation function conforms to the 2041 <type>extent_alloc_t</type> type and upon success returns a pointer to 2042 <parameter>size</parameter> bytes of mapped memory on behalf of arena 2043 <parameter>arena_ind</parameter> such that the extent's base address is 2044 a multiple of <parameter>alignment</parameter>, as well as setting 2045 <parameter>*zero</parameter> to indicate whether the extent is zeroed 2046 and <parameter>*commit</parameter> to indicate whether the extent is 2047 committed. Upon error the function returns <constant>NULL</constant> 2048 and leaves <parameter>*zero</parameter> and 2049 <parameter>*commit</parameter> unmodified. The 2050 <parameter>size</parameter> parameter is always a multiple of the page 2051 size. The <parameter>alignment</parameter> parameter is always a power 2052 of two at least as large as the page size. Zeroing is mandatory if 2053 <parameter>*zero</parameter> is true upon function entry. Committing is 2054 mandatory if <parameter>*commit</parameter> is true upon function entry. 2055 If <parameter>new_addr</parameter> is not <constant>NULL</constant>, the 2056 returned pointer must be <parameter>new_addr</parameter> on success or 2057 <constant>NULL</constant> on error. Committed memory may be committed 2058 in absolute terms as on a system that does not overcommit, or in 2059 implicit terms as on a system that overcommits and satisfies physical 2060 memory needs on demand via soft page faults. Note that replacing the 2061 default extent allocation function makes the arena's <link 2062 linkend="arena.i.dss"><mallctl>arena.<i>.dss</mallctl></link> 2063 setting irrelevant.</para> 2064 2065 <funcsynopsis><funcprototype> 2066 <funcdef>typedef bool <function>(extent_dalloc_t)</function></funcdef> 2067 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2068 <paramdef>void *<parameter>addr</parameter></paramdef> 2069 <paramdef>size_t <parameter>size</parameter></paramdef> 2070 <paramdef>bool <parameter>committed</parameter></paramdef> 2071 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2072 </funcprototype></funcsynopsis> 2073 <literallayout></literallayout> 2074 <para> 2075 An extent deallocation function conforms to the 2076 <type>extent_dalloc_t</type> type and deallocates an extent at given 2077 <parameter>addr</parameter> and <parameter>size</parameter> with 2078 <parameter>committed</parameter>/decommited memory as indicated, on 2079 behalf of arena <parameter>arena_ind</parameter>, returning false upon 2080 success. If the function returns true, this indicates opt-out from 2081 deallocation; the virtual memory mapping associated with the extent 2082 remains mapped, in the same commit state, and available for future use, 2083 in which case it will be automatically retained for later reuse.</para> 2084 2085 <funcsynopsis><funcprototype> 2086 <funcdef>typedef void <function>(extent_destroy_t)</function></funcdef> 2087 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2088 <paramdef>void *<parameter>addr</parameter></paramdef> 2089 <paramdef>size_t <parameter>size</parameter></paramdef> 2090 <paramdef>bool <parameter>committed</parameter></paramdef> 2091 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2092 </funcprototype></funcsynopsis> 2093 <literallayout></literallayout> 2094 <para> 2095 An extent destruction function conforms to the 2096 <type>extent_destroy_t</type> type and unconditionally destroys an 2097 extent at given <parameter>addr</parameter> and 2098 <parameter>size</parameter> with 2099 <parameter>committed</parameter>/decommited memory as indicated, on 2100 behalf of arena <parameter>arena_ind</parameter>. This function may be 2101 called to destroy retained extents during arena destruction (see <link 2102 linkend="arena.i.destroy"><mallctl>arena.<i>.destroy</mallctl></link>).</para> 2103 2104 <funcsynopsis><funcprototype> 2105 <funcdef>typedef bool <function>(extent_commit_t)</function></funcdef> 2106 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2107 <paramdef>void *<parameter>addr</parameter></paramdef> 2108 <paramdef>size_t <parameter>size</parameter></paramdef> 2109 <paramdef>size_t <parameter>offset</parameter></paramdef> 2110 <paramdef>size_t <parameter>length</parameter></paramdef> 2111 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2112 </funcprototype></funcsynopsis> 2113 <literallayout></literallayout> 2114 <para>An extent commit function conforms to the 2115 <type>extent_commit_t</type> type and commits zeroed physical memory to 2116 back pages within an extent at given <parameter>addr</parameter> and 2117 <parameter>size</parameter> at <parameter>offset</parameter> bytes, 2118 extending for <parameter>length</parameter> on behalf of arena 2119 <parameter>arena_ind</parameter>, returning false upon success. 2120 Committed memory may be committed in absolute terms as on a system that 2121 does not overcommit, or in implicit terms as on a system that 2122 overcommits and satisfies physical memory needs on demand via soft page 2123 faults. If the function returns true, this indicates insufficient 2124 physical memory to satisfy the request.</para> 2125 2126 <funcsynopsis><funcprototype> 2127 <funcdef>typedef bool <function>(extent_decommit_t)</function></funcdef> 2128 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2129 <paramdef>void *<parameter>addr</parameter></paramdef> 2130 <paramdef>size_t <parameter>size</parameter></paramdef> 2131 <paramdef>size_t <parameter>offset</parameter></paramdef> 2132 <paramdef>size_t <parameter>length</parameter></paramdef> 2133 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2134 </funcprototype></funcsynopsis> 2135 <literallayout></literallayout> 2136 <para>An extent decommit function conforms to the 2137 <type>extent_decommit_t</type> type and decommits any physical memory 2138 that is backing pages within an extent at given 2139 <parameter>addr</parameter> and <parameter>size</parameter> at 2140 <parameter>offset</parameter> bytes, extending for 2141 <parameter>length</parameter> on behalf of arena 2142 <parameter>arena_ind</parameter>, returning false upon success, in which 2143 case the pages will be committed via the extent commit function before 2144 being reused. If the function returns true, this indicates opt-out from 2145 decommit; the memory remains committed and available for future use, in 2146 which case it will be automatically retained for later reuse.</para> 2147 2148 <funcsynopsis><funcprototype> 2149 <funcdef>typedef bool <function>(extent_purge_t)</function></funcdef> 2150 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2151 <paramdef>void *<parameter>addr</parameter></paramdef> 2152 <paramdef>size_t <parameter>size</parameter></paramdef> 2153 <paramdef>size_t <parameter>offset</parameter></paramdef> 2154 <paramdef>size_t <parameter>length</parameter></paramdef> 2155 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2156 </funcprototype></funcsynopsis> 2157 <literallayout></literallayout> 2158 <para>An extent purge function conforms to the 2159 <type>extent_purge_t</type> type and discards physical pages 2160 within the virtual memory mapping associated with an extent at given 2161 <parameter>addr</parameter> and <parameter>size</parameter> at 2162 <parameter>offset</parameter> bytes, extending for 2163 <parameter>length</parameter> on behalf of arena 2164 <parameter>arena_ind</parameter>. A lazy extent purge function (e.g. 2165 implemented via 2166 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function>) 2167 can delay purging indefinitely and leave the pages within the purged 2168 virtual memory range in an indeterminite state, whereas a forced extent 2169 purge function immediately purges, and the pages within the virtual 2170 memory range will be zero-filled the next time they are accessed. If 2171 the function returns true, this indicates failure to purge.</para> 2172 2173 <funcsynopsis><funcprototype> 2174 <funcdef>typedef bool <function>(extent_split_t)</function></funcdef> 2175 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2176 <paramdef>void *<parameter>addr</parameter></paramdef> 2177 <paramdef>size_t <parameter>size</parameter></paramdef> 2178 <paramdef>size_t <parameter>size_a</parameter></paramdef> 2179 <paramdef>size_t <parameter>size_b</parameter></paramdef> 2180 <paramdef>bool <parameter>committed</parameter></paramdef> 2181 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2182 </funcprototype></funcsynopsis> 2183 <literallayout></literallayout> 2184 <para>An extent split function conforms to the 2185 <type>extent_split_t</type> type and optionally splits an extent at 2186 given <parameter>addr</parameter> and <parameter>size</parameter> into 2187 two adjacent extents, the first of <parameter>size_a</parameter> bytes, 2188 and the second of <parameter>size_b</parameter> bytes, operating on 2189 <parameter>committed</parameter>/decommitted memory as indicated, on 2190 behalf of arena <parameter>arena_ind</parameter>, returning false upon 2191 success. If the function returns true, this indicates that the extent 2192 remains unsplit and therefore should continue to be operated on as a 2193 whole.</para> 2194 2195 <funcsynopsis><funcprototype> 2196 <funcdef>typedef bool <function>(extent_merge_t)</function></funcdef> 2197 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2198 <paramdef>void *<parameter>addr_a</parameter></paramdef> 2199 <paramdef>size_t <parameter>size_a</parameter></paramdef> 2200 <paramdef>void *<parameter>addr_b</parameter></paramdef> 2201 <paramdef>size_t <parameter>size_b</parameter></paramdef> 2202 <paramdef>bool <parameter>committed</parameter></paramdef> 2203 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2204 </funcprototype></funcsynopsis> 2205 <literallayout></literallayout> 2206 <para>An extent merge function conforms to the 2207 <type>extent_merge_t</type> type and optionally merges adjacent extents, 2208 at given <parameter>addr_a</parameter> and <parameter>size_a</parameter> 2209 with given <parameter>addr_b</parameter> and 2210 <parameter>size_b</parameter> into one contiguous extent, operating on 2211 <parameter>committed</parameter>/decommitted memory as indicated, on 2212 behalf of arena <parameter>arena_ind</parameter>, returning false upon 2213 success. If the function returns true, this indicates that the extents 2214 remain distinct mappings and therefore should continue to be operated on 2215 independently.</para> 2216 </listitem> 2217 </varlistentry> 2218 2219 <varlistentry id="arenas.narenas"> 2220 <term> 2221 <mallctl>arenas.narenas</mallctl> 2222 (<type>unsigned</type>) 2223 <literal>r-</literal> 2224 </term> 2225 <listitem><para>Current limit on number of arenas.</para></listitem> 2226 </varlistentry> 2227 2228 <varlistentry id="arenas.dirty_decay_ms"> 2229 <term> 2230 <mallctl>arenas.dirty_decay_ms</mallctl> 2231 (<type>ssize_t</type>) 2232 <literal>rw</literal> 2233 </term> 2234 <listitem><para>Current default per-arena approximate time in 2235 milliseconds from the creation of a set of unused dirty pages until an 2236 equivalent set of unused dirty pages is purged and/or reused, used to 2237 initialize <link 2238 linkend="arena.i.dirty_decay_ms"><mallctl>arena.<i>.dirty_decay_ms</mallctl></link> 2239 during arena creation. See <link 2240 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2241 for additional information.</para></listitem> 2242 </varlistentry> 2243 2244 <varlistentry id="arenas.muzzy_decay_ms"> 2245 <term> 2246 <mallctl>arenas.muzzy_decay_ms</mallctl> 2247 (<type>ssize_t</type>) 2248 <literal>rw</literal> 2249 </term> 2250 <listitem><para>Current default per-arena approximate time in 2251 milliseconds from the creation of a set of unused muzzy pages until an 2252 equivalent set of unused muzzy pages is purged and/or reused, used to 2253 initialize <link 2254 linkend="arena.i.muzzy_decay_ms"><mallctl>arena.<i>.muzzy_decay_ms</mallctl></link> 2255 during arena creation. See <link 2256 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2257 for additional information.</para></listitem> 2258 </varlistentry> 2259 2260 <varlistentry id="arenas.quantum"> 2261 <term> 2262 <mallctl>arenas.quantum</mallctl> 2263 (<type>size_t</type>) 2264 <literal>r-</literal> 2265 </term> 2266 <listitem><para>Quantum size.</para></listitem> 2267 </varlistentry> 2268 2269 <varlistentry id="arenas.page"> 2270 <term> 2271 <mallctl>arenas.page</mallctl> 2272 (<type>size_t</type>) 2273 <literal>r-</literal> 2274 </term> 2275 <listitem><para>Page size.</para></listitem> 2276 </varlistentry> 2277 2278 <varlistentry id="arenas.tcache_max"> 2279 <term> 2280 <mallctl>arenas.tcache_max</mallctl> 2281 (<type>size_t</type>) 2282 <literal>r-</literal> 2283 </term> 2284 <listitem><para>Maximum thread-cached size class.</para></listitem> 2285 </varlistentry> 2286 2287 <varlistentry id="arenas.nbins"> 2288 <term> 2289 <mallctl>arenas.nbins</mallctl> 2290 (<type>unsigned</type>) 2291 <literal>r-</literal> 2292 </term> 2293 <listitem><para>Number of bin size classes.</para></listitem> 2294 </varlistentry> 2295 2296 <varlistentry id="arenas.nhbins"> 2297 <term> 2298 <mallctl>arenas.nhbins</mallctl> 2299 (<type>unsigned</type>) 2300 <literal>r-</literal> 2301 </term> 2302 <listitem><para>Total number of thread cache bin size 2303 classes.</para></listitem> 2304 </varlistentry> 2305 2306 <varlistentry id="arenas.bin.i.size"> 2307 <term> 2308 <mallctl>arenas.bin.<i>.size</mallctl> 2309 (<type>size_t</type>) 2310 <literal>r-</literal> 2311 </term> 2312 <listitem><para>Maximum size supported by size class.</para></listitem> 2313 </varlistentry> 2314 2315 <varlistentry id="arenas.bin.i.nregs"> 2316 <term> 2317 <mallctl>arenas.bin.<i>.nregs</mallctl> 2318 (<type>uint32_t</type>) 2319 <literal>r-</literal> 2320 </term> 2321 <listitem><para>Number of regions per slab.</para></listitem> 2322 </varlistentry> 2323 2324 <varlistentry id="arenas.bin.i.slab_size"> 2325 <term> 2326 <mallctl>arenas.bin.<i>.slab_size</mallctl> 2327 (<type>size_t</type>) 2328 <literal>r-</literal> 2329 </term> 2330 <listitem><para>Number of bytes per slab.</para></listitem> 2331 </varlistentry> 2332 2333 <varlistentry id="arenas.nlextents"> 2334 <term> 2335 <mallctl>arenas.nlextents</mallctl> 2336 (<type>unsigned</type>) 2337 <literal>r-</literal> 2338 </term> 2339 <listitem><para>Total number of large size classes.</para></listitem> 2340 </varlistentry> 2341 2342 <varlistentry id="arenas.lextent.i.size"> 2343 <term> 2344 <mallctl>arenas.lextent.<i>.size</mallctl> 2345 (<type>size_t</type>) 2346 <literal>r-</literal> 2347 </term> 2348 <listitem><para>Maximum size supported by this large size 2349 class.</para></listitem> 2350 </varlistentry> 2351 2352 <varlistentry id="arenas.create"> 2353 <term> 2354 <mallctl>arenas.create</mallctl> 2355 (<type>unsigned</type>, <type>extent_hooks_t *</type>) 2356 <literal>rw</literal> 2357 </term> 2358 <listitem><para>Explicitly create a new arena outside the range of 2359 automatically managed arenas, with optionally specified extent hooks, 2360 and return the new arena index.</para> 2361 2362 <para>If the amount of space supplied for storing the arena index does 2363 not equal <code language="C">sizeof(<type>unsigned</type>)</code>, no 2364 arena will be created, no data will be written to the space pointed by 2365 <parameter>oldp</parameter>, and <parameter>*oldlenp</parameter> will 2366 be set to 0. 2367 </para></listitem> 2368 </varlistentry> 2369 2370 <varlistentry id="arenas.lookup"> 2371 <term> 2372 <mallctl>arenas.lookup</mallctl> 2373 (<type>unsigned</type>, <type>void*</type>) 2374 <literal>rw</literal> 2375 </term> 2376 <listitem><para>Index of the arena to which an allocation belongs to.</para></listitem> 2377 </varlistentry> 2378 2379 <varlistentry id="prof.thread_active_init"> 2380 <term> 2381 <mallctl>prof.thread_active_init</mallctl> 2382 (<type>bool</type>) 2383 <literal>rw</literal> 2384 [<option>--enable-prof</option>] 2385 </term> 2386 <listitem><para>Control the initial setting for <link 2387 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 2388 in newly created threads. See the <link 2389 linkend="opt.prof_thread_active_init"><mallctl>opt.prof_thread_active_init</mallctl></link> 2390 option for additional information.</para></listitem> 2391 </varlistentry> 2392 2393 <varlistentry id="prof.active"> 2394 <term> 2395 <mallctl>prof.active</mallctl> 2396 (<type>bool</type>) 2397 <literal>rw</literal> 2398 [<option>--enable-prof</option>] 2399 </term> 2400 <listitem><para>Control whether sampling is currently active. See the 2401 <link 2402 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 2403 option for additional information, as well as the interrelated <link 2404 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 2405 mallctl.</para></listitem> 2406 </varlistentry> 2407 2408 <varlistentry id="prof.dump"> 2409 <term> 2410 <mallctl>prof.dump</mallctl> 2411 (<type>const char *</type>) 2412 <literal>-w</literal> 2413 [<option>--enable-prof</option>] 2414 </term> 2415 <listitem><para>Dump a memory profile to the specified file, or if NULL 2416 is specified, to a file according to the pattern 2417 <filename><prefix>.<pid>.<seq>.m<mseq>.heap</filename>, 2418 where <literal><prefix></literal> is controlled by the 2419 <link linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 2420 and <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link> 2421 options.</para></listitem> 2422 </varlistentry> 2423 2424 <varlistentry id="prof.prefix"> 2425 <term> 2426 <mallctl>prof.prefix</mallctl> 2427 (<type>const char *</type>) 2428 <literal>-w</literal> 2429 [<option>--enable-prof</option>] 2430 </term> 2431 <listitem><para>Set the filename prefix for profile dumps. See 2432 <link 2433 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 2434 for the default setting. This can be useful to differentiate profile 2435 dumps such as from forked processes. 2436 </para></listitem> 2437 </varlistentry> 2438 2439 <varlistentry id="prof.gdump"> 2440 <term> 2441 <mallctl>prof.gdump</mallctl> 2442 (<type>bool</type>) 2443 <literal>rw</literal> 2444 [<option>--enable-prof</option>] 2445 </term> 2446 <listitem><para>When enabled, trigger a memory profile dump every time 2447 the total virtual memory exceeds the previous maximum. Profiles are 2448 dumped to files named according to the pattern 2449 <filename><prefix>.<pid>.<seq>.u<useq>.heap</filename>, 2450 where <literal><prefix></literal> is controlled by the <link 2451 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> and 2452 <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link> 2453 options.</para></listitem> 2454 </varlistentry> 2455 2456 <varlistentry id="prof.reset"> 2457 <term> 2458 <mallctl>prof.reset</mallctl> 2459 (<type>size_t</type>) 2460 <literal>-w</literal> 2461 [<option>--enable-prof</option>] 2462 </term> 2463 <listitem><para>Reset all memory profile statistics, and optionally 2464 update the sample rate (see <link 2465 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 2466 and <link 2467 linkend="prof.lg_sample"><mallctl>prof.lg_sample</mallctl></link>). 2468 </para></listitem> 2469 </varlistentry> 2470 2471 <varlistentry id="prof.lg_sample"> 2472 <term> 2473 <mallctl>prof.lg_sample</mallctl> 2474 (<type>size_t</type>) 2475 <literal>r-</literal> 2476 [<option>--enable-prof</option>] 2477 </term> 2478 <listitem><para>Get the current sample rate (see <link 2479 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link>). 2480 </para></listitem> 2481 </varlistentry> 2482 2483 <varlistentry id="prof.interval"> 2484 <term> 2485 <mallctl>prof.interval</mallctl> 2486 (<type>uint64_t</type>) 2487 <literal>r-</literal> 2488 [<option>--enable-prof</option>] 2489 </term> 2490 <listitem><para>Average number of bytes allocated between 2491 interval-based profile dumps. See the 2492 <link 2493 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 2494 option for additional information.</para></listitem> 2495 </varlistentry> 2496 2497 <varlistentry id="stats.allocated"> 2498 <term> 2499 <mallctl>stats.allocated</mallctl> 2500 (<type>size_t</type>) 2501 <literal>r-</literal> 2502 [<option>--enable-stats</option>] 2503 </term> 2504 <listitem><para>Total number of bytes allocated by the 2505 application.</para></listitem> 2506 </varlistentry> 2507 2508 <varlistentry id="stats.active"> 2509 <term> 2510 <mallctl>stats.active</mallctl> 2511 (<type>size_t</type>) 2512 <literal>r-</literal> 2513 [<option>--enable-stats</option>] 2514 </term> 2515 <listitem><para>Total number of bytes in active pages allocated by the 2516 application. This is a multiple of the page size, and greater than or 2517 equal to <link 2518 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>. 2519 This does not include <link linkend="stats.arenas.i.pdirty"> 2520 <mallctl>stats.arenas.<i>.pdirty</mallctl></link>, 2521 <link linkend="stats.arenas.i.pmuzzy"> 2522 <mallctl>stats.arenas.<i>.pmuzzy</mallctl></link>, nor pages 2523 entirely devoted to allocator metadata.</para></listitem> 2524 </varlistentry> 2525 2526 <varlistentry id="stats.metadata"> 2527 <term> 2528 <mallctl>stats.metadata</mallctl> 2529 (<type>size_t</type>) 2530 <literal>r-</literal> 2531 [<option>--enable-stats</option>] 2532 </term> 2533 <listitem><para>Total number of bytes dedicated to metadata, which 2534 comprise base allocations used for bootstrap-sensitive allocator 2535 metadata structures (see <link 2536 linkend="stats.arenas.i.base"><mallctl>stats.arenas.<i>.base</mallctl></link>) 2537 and internal allocations (see <link 2538 linkend="stats.arenas.i.internal"><mallctl>stats.arenas.<i>.internal</mallctl></link>). 2539 Transparent huge page (enabled with <link 2540 linkend="opt.metadata_thp">opt.metadata_thp</link>) usage is not 2541 considered.</para></listitem> 2542 </varlistentry> 2543 2544 <varlistentry id="stats.metadata_thp"> 2545 <term> 2546 <mallctl>stats.metadata_thp</mallctl> 2547 (<type>size_t</type>) 2548 <literal>r-</literal> 2549 [<option>--enable-stats</option>] 2550 </term> 2551 <listitem><para>Number of transparent huge pages (THP) used for 2552 metadata. See <link 2553 linkend="stats.metadata"><mallctl>stats.metadata</mallctl></link> and 2554 <link linkend="opt.metadata_thp">opt.metadata_thp</link>) for 2555 details.</para></listitem> 2556 </varlistentry> 2557 2558 <varlistentry id="stats.resident"> 2559 <term> 2560 <mallctl>stats.resident</mallctl> 2561 (<type>size_t</type>) 2562 <literal>r-</literal> 2563 [<option>--enable-stats</option>] 2564 </term> 2565 <listitem><para>Maximum number of bytes in physically resident data 2566 pages mapped by the allocator, comprising all pages dedicated to 2567 allocator metadata, pages backing active allocations, and unused dirty 2568 pages. This is a maximum rather than precise because pages may not 2569 actually be physically resident if they correspond to demand-zeroed 2570 virtual memory that has not yet been touched. This is a multiple of the 2571 page size, and is larger than <link 2572 linkend="stats.active"><mallctl>stats.active</mallctl></link>.</para></listitem> 2573 </varlistentry> 2574 2575 <varlistentry id="stats.mapped"> 2576 <term> 2577 <mallctl>stats.mapped</mallctl> 2578 (<type>size_t</type>) 2579 <literal>r-</literal> 2580 [<option>--enable-stats</option>] 2581 </term> 2582 <listitem><para>Total number of bytes in active extents mapped by the 2583 allocator. This is larger than <link 2584 linkend="stats.active"><mallctl>stats.active</mallctl></link>. This 2585 does not include inactive extents, even those that contain unused dirty 2586 pages, which means that there is no strict ordering between this and 2587 <link 2588 linkend="stats.resident"><mallctl>stats.resident</mallctl></link>.</para></listitem> 2589 </varlistentry> 2590 2591 <varlistentry id="stats.retained"> 2592 <term> 2593 <mallctl>stats.retained</mallctl> 2594 (<type>size_t</type>) 2595 <literal>r-</literal> 2596 [<option>--enable-stats</option>] 2597 </term> 2598 <listitem><para>Total number of bytes in virtual memory mappings that 2599 were retained rather than being returned to the operating system via 2600 e.g. <citerefentry><refentrytitle>munmap</refentrytitle> 2601 <manvolnum>2</manvolnum></citerefentry> or similar. Retained virtual 2602 memory is typically untouched, decommitted, or purged, so it has no 2603 strongly associated physical memory (see <link 2604 linkend="arena.i.extent_hooks">extent hooks</link> for details). 2605 Retained memory is excluded from mapped memory statistics, e.g. <link 2606 linkend="stats.mapped"><mallctl>stats.mapped</mallctl></link>. 2607 </para></listitem> 2608 </varlistentry> 2609 2610 <varlistentry id="stats.zero_reallocs"> 2611 <term> 2612 <mallctl>stats.zero_reallocs</mallctl> 2613 (<type>size_t</type>) 2614 <literal>r-</literal> 2615 [<option>--enable-stats</option>] 2616 </term> 2617 <listitem><para>Number of times that the <function>realloc()</function> 2618 was called with a non-<constant>NULL</constant> pointer argument and a 2619 <constant>0</constant> size argument. This is a fundamentally unsafe 2620 pattern in portable programs; see <link linkend="opt.zero_realloc"> 2621 <mallctl>opt.zero_realloc</mallctl></link> for details. 2622 </para></listitem> 2623 </varlistentry> 2624 2625 <varlistentry id="stats.background_thread.num_threads"> 2626 <term> 2627 <mallctl>stats.background_thread.num_threads</mallctl> 2628 (<type>size_t</type>) 2629 <literal>r-</literal> 2630 [<option>--enable-stats</option>] 2631 </term> 2632 <listitem><para> Number of <link linkend="background_thread">background 2633 threads</link> running currently.</para></listitem> 2634 </varlistentry> 2635 2636 <varlistentry id="stats.background_thread.num_runs"> 2637 <term> 2638 <mallctl>stats.background_thread.num_runs</mallctl> 2639 (<type>uint64_t</type>) 2640 <literal>r-</literal> 2641 [<option>--enable-stats</option>] 2642 </term> 2643 <listitem><para> Total number of runs from all <link 2644 linkend="background_thread">background threads</link>.</para></listitem> 2645 </varlistentry> 2646 2647 <varlistentry id="stats.background_thread.run_interval"> 2648 <term> 2649 <mallctl>stats.background_thread.run_interval</mallctl> 2650 (<type>uint64_t</type>) 2651 <literal>r-</literal> 2652 [<option>--enable-stats</option>] 2653 </term> 2654 <listitem><para> Average run interval in nanoseconds of <link 2655 linkend="background_thread">background threads</link>.</para></listitem> 2656 </varlistentry> 2657 2658 <varlistentry id="stats.mutexes.ctl"> 2659 <term> 2660 <mallctl>stats.mutexes.ctl.{counter};</mallctl> 2661 (<type>counter specific type</type>) 2662 <literal>r-</literal> 2663 [<option>--enable-stats</option>] 2664 </term> 2665 <listitem><para>Statistics on <varname>ctl</varname> mutex (global 2666 scope; mallctl related). <mallctl>{counter}</mallctl> is one of the 2667 counters below:</para> 2668 <varlistentry id="mutex_counters"> 2669 <listitem><para><varname>num_ops</varname> (<type>uint64_t</type>): 2670 Total number of lock acquisition operations on this mutex.</para> 2671 2672 <para><varname>num_spin_acq</varname> (<type>uint64_t</type>): Number 2673 of times the mutex was spin-acquired. When the mutex is currently 2674 locked and cannot be acquired immediately, a short period of 2675 spin-retry within jemalloc will be performed. Acquired through spin 2676 generally means the contention was lightweight and not causing context 2677 switches.</para> 2678 2679 <para><varname>num_wait</varname> (<type>uint64_t</type>): Number of 2680 times the mutex was wait-acquired, which means the mutex contention 2681 was not solved by spin-retry, and blocking operation was likely 2682 involved in order to acquire the mutex. This event generally implies 2683 higher cost / longer delay, and should be investigated if it happens 2684 often.</para> 2685 2686 <para><varname>max_wait_time</varname> (<type>uint64_t</type>): 2687 Maximum length of time in nanoseconds spent on a single wait-acquired 2688 lock operation. Note that to avoid profiling overhead on the common 2689 path, this does not consider spin-acquired cases.</para> 2690 2691 <para><varname>total_wait_time</varname> (<type>uint64_t</type>): 2692 Cumulative time in nanoseconds spent on wait-acquired lock operations. 2693 Similarly, spin-acquired cases are not considered.</para> 2694 2695 <para><varname>max_num_thds</varname> (<type>uint32_t</type>): Maximum 2696 number of threads waiting on this mutex simultaneously. Similarly, 2697 spin-acquired cases are not considered.</para> 2698 2699 <para><varname>num_owner_switch</varname> (<type>uint64_t</type>): 2700 Number of times the current mutex owner is different from the previous 2701 one. This event does not generally imply an issue; rather it is an 2702 indicator of how often the protected data are accessed by different 2703 threads. 2704 </para> 2705 </listitem> 2706 </varlistentry> 2707 </listitem> 2708 </varlistentry> 2709 2710 <varlistentry id="stats.mutexes.background_thread"> 2711 <term> 2712 <mallctl>stats.mutexes.background_thread.{counter}</mallctl> 2713 (<type>counter specific type</type>) <literal>r-</literal> 2714 [<option>--enable-stats</option>] 2715 </term> 2716 <listitem><para>Statistics on <varname>background_thread</varname> mutex 2717 (global scope; <link 2718 linkend="background_thread"><mallctl>background_thread</mallctl></link> 2719 related). <mallctl>{counter}</mallctl> is one of the counters in <link 2720 linkend="mutex_counters">mutex profiling 2721 counters</link>.</para></listitem> 2722 </varlistentry> 2723 2724 <varlistentry id="stats.mutexes.prof"> 2725 <term> 2726 <mallctl>stats.mutexes.prof.{counter}</mallctl> 2727 (<type>counter specific type</type>) <literal>r-</literal> 2728 [<option>--enable-stats</option>] 2729 </term> 2730 <listitem><para>Statistics on <varname>prof</varname> mutex (global 2731 scope; profiling related). <mallctl>{counter}</mallctl> is one of the 2732 counters in <link linkend="mutex_counters">mutex profiling 2733 counters</link>.</para></listitem> 2734 </varlistentry> 2735 2736 <varlistentry id="stats.mutexes.prof_thds_data"> 2737 <term> 2738 <mallctl>stats.mutexes.prof_thds_data.{counter}</mallctl> 2739 (<type>counter specific type</type>) <literal>r-</literal> 2740 [<option>--enable-stats</option>] 2741 </term> 2742 <listitem><para>Statistics on <varname>prof</varname> threads data mutex 2743 (global scope; profiling related). <mallctl>{counter}</mallctl> is one 2744 of the counters in <link linkend="mutex_counters">mutex profiling 2745 counters</link>.</para></listitem> 2746 </varlistentry> 2747 2748 <varlistentry id="stats.mutexes.prof_dump"> 2749 <term> 2750 <mallctl>stats.mutexes.prof_dump.{counter}</mallctl> 2751 (<type>counter specific type</type>) <literal>r-</literal> 2752 [<option>--enable-stats</option>] 2753 </term> 2754 <listitem><para>Statistics on <varname>prof</varname> dumping mutex 2755 (global scope; profiling related). <mallctl>{counter}</mallctl> is one 2756 of the counters in <link linkend="mutex_counters">mutex profiling 2757 counters</link>.</para></listitem> 2758 </varlistentry> 2759 2760 <varlistentry id="stats.mutexes.reset"> 2761 <term> 2762 <mallctl>stats.mutexes.reset</mallctl> 2763 (<type>void</type>) <literal>--</literal> 2764 [<option>--enable-stats</option>] 2765 </term> 2766 <listitem><para>Reset all mutex profile statistics, including global 2767 mutexes, arena mutexes and bin mutexes.</para></listitem> 2768 </varlistentry> 2769 2770 <varlistentry id="stats.arenas.i.dss"> 2771 <term> 2772 <mallctl>stats.arenas.<i>.dss</mallctl> 2773 (<type>const char *</type>) 2774 <literal>r-</literal> 2775 </term> 2776 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 2777 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 2778 related to <citerefentry><refentrytitle>mmap</refentrytitle> 2779 <manvolnum>2</manvolnum></citerefentry> allocation. See <link 2780 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for details. 2781 </para></listitem> 2782 </varlistentry> 2783 2784 <varlistentry id="stats.arenas.i.dirty_decay_ms"> 2785 <term> 2786 <mallctl>stats.arenas.<i>.dirty_decay_ms</mallctl> 2787 (<type>ssize_t</type>) 2788 <literal>r-</literal> 2789 </term> 2790 <listitem><para>Approximate time in milliseconds from the creation of a 2791 set of unused dirty pages until an equivalent set of unused dirty pages 2792 is purged and/or reused. See <link 2793 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2794 for details.</para></listitem> 2795 </varlistentry> 2796 2797 <varlistentry id="stats.arenas.i.muzzy_decay_ms"> 2798 <term> 2799 <mallctl>stats.arenas.<i>.muzzy_decay_ms</mallctl> 2800 (<type>ssize_t</type>) 2801 <literal>r-</literal> 2802 </term> 2803 <listitem><para>Approximate time in milliseconds from the creation of a 2804 set of unused muzzy pages until an equivalent set of unused muzzy pages 2805 is purged and/or reused. See <link 2806 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2807 for details.</para></listitem> 2808 </varlistentry> 2809 2810 <varlistentry id="stats.arenas.i.nthreads"> 2811 <term> 2812 <mallctl>stats.arenas.<i>.nthreads</mallctl> 2813 (<type>unsigned</type>) 2814 <literal>r-</literal> 2815 </term> 2816 <listitem><para>Number of threads currently assigned to 2817 arena.</para></listitem> 2818 </varlistentry> 2819 2820 <varlistentry id="stats.arenas.i.uptime"> 2821 <term> 2822 <mallctl>stats.arenas.<i>.uptime</mallctl> 2823 (<type>uint64_t</type>) 2824 <literal>r-</literal> 2825 </term> 2826 <listitem><para>Time elapsed (in nanoseconds) since the arena was 2827 created. If <i> equals <constant>0</constant> or 2828 <constant>MALLCTL_ARENAS_ALL</constant>, this is the uptime since malloc 2829 initialization.</para></listitem> 2830 </varlistentry> 2831 2832 <varlistentry id="stats.arenas.i.pactive"> 2833 <term> 2834 <mallctl>stats.arenas.<i>.pactive</mallctl> 2835 (<type>size_t</type>) 2836 <literal>r-</literal> 2837 </term> 2838 <listitem><para>Number of pages in active extents.</para></listitem> 2839 </varlistentry> 2840 2841 <varlistentry id="stats.arenas.i.pdirty"> 2842 <term> 2843 <mallctl>stats.arenas.<i>.pdirty</mallctl> 2844 (<type>size_t</type>) 2845 <literal>r-</literal> 2846 </term> 2847 <listitem><para>Number of pages within unused extents that are 2848 potentially dirty, and for which <function>madvise()</function> or 2849 similar has not been called. See <link 2850 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2851 for a description of dirty pages.</para></listitem> 2852 </varlistentry> 2853 2854 <varlistentry id="stats.arenas.i.pmuzzy"> 2855 <term> 2856 <mallctl>stats.arenas.<i>.pmuzzy</mallctl> 2857 (<type>size_t</type>) 2858 <literal>r-</literal> 2859 </term> 2860 <listitem><para>Number of pages within unused extents that are muzzy. 2861 See <link 2862 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2863 for a description of muzzy pages.</para></listitem> 2864 </varlistentry> 2865 2866 <varlistentry id="stats.arenas.i.mapped"> 2867 <term> 2868 <mallctl>stats.arenas.<i>.mapped</mallctl> 2869 (<type>size_t</type>) 2870 <literal>r-</literal> 2871 [<option>--enable-stats</option>] 2872 </term> 2873 <listitem><para>Number of mapped bytes.</para></listitem> 2874 </varlistentry> 2875 2876 <varlistentry id="stats.arenas.i.retained"> 2877 <term> 2878 <mallctl>stats.arenas.<i>.retained</mallctl> 2879 (<type>size_t</type>) 2880 <literal>r-</literal> 2881 [<option>--enable-stats</option>] 2882 </term> 2883 <listitem><para>Number of retained bytes. See <link 2884 linkend="stats.retained"><mallctl>stats.retained</mallctl></link> for 2885 details.</para></listitem> 2886 </varlistentry> 2887 2888 <varlistentry id="stats.arenas.i.extent_avail"> 2889 <term> 2890 <mallctl>stats.arenas.<i>.extent_avail</mallctl> 2891 (<type>size_t</type>) 2892 <literal>r-</literal> 2893 [<option>--enable-stats</option>] 2894 </term> 2895 <listitem><para>Number of allocated (but unused) extent structs in this 2896 arena.</para></listitem> 2897 </varlistentry> 2898 2899 <varlistentry id="stats.arenas.i.base"> 2900 <term> 2901 <mallctl>stats.arenas.<i>.base</mallctl> 2902 (<type>size_t</type>) 2903 <literal>r-</literal> 2904 [<option>--enable-stats</option>] 2905 </term> 2906 <listitem><para> 2907 Number of bytes dedicated to bootstrap-sensitive allocator metadata 2908 structures.</para></listitem> 2909 </varlistentry> 2910 2911 <varlistentry id="stats.arenas.i.internal"> 2912 <term> 2913 <mallctl>stats.arenas.<i>.internal</mallctl> 2914 (<type>size_t</type>) 2915 <literal>r-</literal> 2916 [<option>--enable-stats</option>] 2917 </term> 2918 <listitem><para>Number of bytes dedicated to internal allocations. 2919 Internal allocations differ from application-originated allocations in 2920 that they are for internal use, and that they are omitted from heap 2921 profiles.</para></listitem> 2922 </varlistentry> 2923 2924 <varlistentry id="stats.arenas.i.metadata_thp"> 2925 <term> 2926 <mallctl>stats.arenas.<i>.metadata_thp</mallctl> 2927 (<type>size_t</type>) 2928 <literal>r-</literal> 2929 [<option>--enable-stats</option>] 2930 </term> 2931 <listitem><para>Number of transparent huge pages (THP) used for 2932 metadata. See <link linkend="opt.metadata_thp">opt.metadata_thp</link> 2933 for details.</para></listitem> 2934 </varlistentry> 2935 2936 <varlistentry id="stats.arenas.i.resident"> 2937 <term> 2938 <mallctl>stats.arenas.<i>.resident</mallctl> 2939 (<type>size_t</type>) 2940 <literal>r-</literal> 2941 [<option>--enable-stats</option>] 2942 </term> 2943 <listitem><para>Maximum number of bytes in physically resident data 2944 pages mapped by the arena, comprising all pages dedicated to allocator 2945 metadata, pages backing active allocations, and unused dirty pages. 2946 This is a maximum rather than precise because pages may not actually be 2947 physically resident if they correspond to demand-zeroed virtual memory 2948 that has not yet been touched. This is a multiple of the page 2949 size.</para></listitem> 2950 </varlistentry> 2951 2952 <varlistentry id="stats.arenas.i.dirty_npurge"> 2953 <term> 2954 <mallctl>stats.arenas.<i>.dirty_npurge</mallctl> 2955 (<type>uint64_t</type>) 2956 <literal>r-</literal> 2957 [<option>--enable-stats</option>] 2958 </term> 2959 <listitem><para>Number of dirty page purge sweeps performed. 2960 </para></listitem> 2961 </varlistentry> 2962 2963 <varlistentry id="stats.arenas.i.dirty_nmadvise"> 2964 <term> 2965 <mallctl>stats.arenas.<i>.dirty_nmadvise</mallctl> 2966 (<type>uint64_t</type>) 2967 <literal>r-</literal> 2968 [<option>--enable-stats</option>] 2969 </term> 2970 <listitem><para>Number of <function>madvise()</function> or similar 2971 calls made to purge dirty pages.</para></listitem> 2972 </varlistentry> 2973 2974 <varlistentry id="stats.arenas.i.dirty_purged"> 2975 <term> 2976 <mallctl>stats.arenas.<i>.dirty_purged</mallctl> 2977 (<type>uint64_t</type>) 2978 <literal>r-</literal> 2979 [<option>--enable-stats</option>] 2980 </term> 2981 <listitem><para>Number of dirty pages purged.</para></listitem> 2982 </varlistentry> 2983 2984 <varlistentry id="stats.arenas.i.muzzy_npurge"> 2985 <term> 2986 <mallctl>stats.arenas.<i>.muzzy_npurge</mallctl> 2987 (<type>uint64_t</type>) 2988 <literal>r-</literal> 2989 [<option>--enable-stats</option>] 2990 </term> 2991 <listitem><para>Number of muzzy page purge sweeps performed. 2992 </para></listitem> 2993 </varlistentry> 2994 2995 <varlistentry id="stats.arenas.i.muzzy_nmadvise"> 2996 <term> 2997 <mallctl>stats.arenas.<i>.muzzy_nmadvise</mallctl> 2998 (<type>uint64_t</type>) 2999 <literal>r-</literal> 3000 [<option>--enable-stats</option>] 3001 </term> 3002 <listitem><para>Number of <function>madvise()</function> or similar 3003 calls made to purge muzzy pages.</para></listitem> 3004 </varlistentry> 3005 3006 <varlistentry id="stats.arenas.i.muzzy_purged"> 3007 <term> 3008 <mallctl>stats.arenas.<i>.muzzy_purged</mallctl> 3009 (<type>uint64_t</type>) 3010 <literal>r-</literal> 3011 [<option>--enable-stats</option>] 3012 </term> 3013 <listitem><para>Number of muzzy pages purged.</para></listitem> 3014 </varlistentry> 3015 3016 <varlistentry id="stats.arenas.i.small.allocated"> 3017 <term> 3018 <mallctl>stats.arenas.<i>.small.allocated</mallctl> 3019 (<type>size_t</type>) 3020 <literal>r-</literal> 3021 [<option>--enable-stats</option>] 3022 </term> 3023 <listitem><para>Number of bytes currently allocated by small objects. 3024 </para></listitem> 3025 </varlistentry> 3026 3027 <varlistentry id="stats.arenas.i.small.nmalloc"> 3028 <term> 3029 <mallctl>stats.arenas.<i>.small.nmalloc</mallctl> 3030 (<type>uint64_t</type>) 3031 <literal>r-</literal> 3032 [<option>--enable-stats</option>] 3033 </term> 3034 <listitem><para>Cumulative number of times a small allocation was 3035 requested from the arena's bins, whether to fill the relevant tcache if 3036 <link linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is 3037 enabled, or to directly satisfy an allocation request 3038 otherwise.</para></listitem> 3039 </varlistentry> 3040 3041 <varlistentry id="stats.arenas.i.small.ndalloc"> 3042 <term> 3043 <mallctl>stats.arenas.<i>.small.ndalloc</mallctl> 3044 (<type>uint64_t</type>) 3045 <literal>r-</literal> 3046 [<option>--enable-stats</option>] 3047 </term> 3048 <listitem><para>Cumulative number of times a small allocation was 3049 returned to the arena's bins, whether to flush the relevant tcache if 3050 <link linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is 3051 enabled, or to directly deallocate an allocation 3052 otherwise.</para></listitem> 3053 </varlistentry> 3054 3055 <varlistentry id="stats.arenas.i.small.nrequests"> 3056 <term> 3057 <mallctl>stats.arenas.<i>.small.nrequests</mallctl> 3058 (<type>uint64_t</type>) 3059 <literal>r-</literal> 3060 [<option>--enable-stats</option>] 3061 </term> 3062 <listitem><para>Cumulative number of allocation requests satisfied by 3063 all bin size classes.</para></listitem> 3064 </varlistentry> 3065 3066 <varlistentry id="stats.arenas.i.small.nfills"> 3067 <term> 3068 <mallctl>stats.arenas.<i>.small.nfills</mallctl> 3069 (<type>uint64_t</type>) 3070 <literal>r-</literal> 3071 [<option>--enable-stats</option>] 3072 </term> 3073 <listitem><para>Cumulative number of tcache fills by all small size 3074 classes.</para></listitem> 3075 </varlistentry> 3076 3077 <varlistentry id="stats.arenas.i.small.nflushes"> 3078 <term> 3079 <mallctl>stats.arenas.<i>.small.nflushes</mallctl> 3080 (<type>uint64_t</type>) 3081 <literal>r-</literal> 3082 [<option>--enable-stats</option>] 3083 </term> 3084 <listitem><para>Cumulative number of tcache flushes by all small size 3085 classes.</para></listitem> 3086 </varlistentry> 3087 3088 <varlistentry id="stats.arenas.i.large.allocated"> 3089 <term> 3090 <mallctl>stats.arenas.<i>.large.allocated</mallctl> 3091 (<type>size_t</type>) 3092 <literal>r-</literal> 3093 [<option>--enable-stats</option>] 3094 </term> 3095 <listitem><para>Number of bytes currently allocated by large objects. 3096 </para></listitem> 3097 </varlistentry> 3098 3099 <varlistentry id="stats.arenas.i.large.nmalloc"> 3100 <term> 3101 <mallctl>stats.arenas.<i>.large.nmalloc</mallctl> 3102 (<type>uint64_t</type>) 3103 <literal>r-</literal> 3104 [<option>--enable-stats</option>] 3105 </term> 3106 <listitem><para>Cumulative number of times a large extent was allocated 3107 from the arena, whether to fill the relevant tcache if <link 3108 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3109 the size class is within the range being cached, or to directly satisfy 3110 an allocation request otherwise.</para></listitem> 3111 </varlistentry> 3112 3113 <varlistentry id="stats.arenas.i.large.ndalloc"> 3114 <term> 3115 <mallctl>stats.arenas.<i>.large.ndalloc</mallctl> 3116 (<type>uint64_t</type>) 3117 <literal>r-</literal> 3118 [<option>--enable-stats</option>] 3119 </term> 3120 <listitem><para>Cumulative number of times a large extent was returned 3121 to the arena, whether to flush the relevant tcache if <link 3122 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3123 the size class is within the range being cached, or to directly 3124 deallocate an allocation otherwise.</para></listitem> 3125 </varlistentry> 3126 3127 <varlistentry id="stats.arenas.i.large.nrequests"> 3128 <term> 3129 <mallctl>stats.arenas.<i>.large.nrequests</mallctl> 3130 (<type>uint64_t</type>) 3131 <literal>r-</literal> 3132 [<option>--enable-stats</option>] 3133 </term> 3134 <listitem><para>Cumulative number of allocation requests satisfied by 3135 all large size classes.</para></listitem> 3136 </varlistentry> 3137 3138 <varlistentry id="stats.arenas.i.large.nfills"> 3139 <term> 3140 <mallctl>stats.arenas.<i>.large.nfills</mallctl> 3141 (<type>uint64_t</type>) 3142 <literal>r-</literal> 3143 [<option>--enable-stats</option>] 3144 </term> 3145 <listitem><para>Cumulative number of tcache fills by all large size 3146 classes.</para></listitem> 3147 </varlistentry> 3148 3149 <varlistentry id="stats.arenas.i.large.nflushes"> 3150 <term> 3151 <mallctl>stats.arenas.<i>.large.nflushes</mallctl> 3152 (<type>uint64_t</type>) 3153 <literal>r-</literal> 3154 [<option>--enable-stats</option>] 3155 </term> 3156 <listitem><para>Cumulative number of tcache flushes by all large size 3157 classes.</para></listitem> 3158 </varlistentry> 3159 3160 <varlistentry id="stats.arenas.i.bins.j.nmalloc"> 3161 <term> 3162 <mallctl>stats.arenas.<i>.bins.<j>.nmalloc</mallctl> 3163 (<type>uint64_t</type>) 3164 <literal>r-</literal> 3165 [<option>--enable-stats</option>] 3166 </term> 3167 <listitem><para>Cumulative number of times a bin region of the 3168 corresponding size class was allocated from the arena, whether to fill 3169 the relevant tcache if <link 3170 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled, or 3171 to directly satisfy an allocation request otherwise.</para></listitem> 3172 </varlistentry> 3173 3174 <varlistentry id="stats.arenas.i.bins.j.ndalloc"> 3175 <term> 3176 <mallctl>stats.arenas.<i>.bins.<j>.ndalloc</mallctl> 3177 (<type>uint64_t</type>) 3178 <literal>r-</literal> 3179 [<option>--enable-stats</option>] 3180 </term> 3181 <listitem><para>Cumulative number of times a bin region of the 3182 corresponding size class was returned to the arena, whether to flush the 3183 relevant tcache if <link 3184 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled, or 3185 to directly deallocate an allocation otherwise.</para></listitem> 3186 </varlistentry> 3187 3188 <varlistentry id="stats.arenas.i.bins.j.nrequests"> 3189 <term> 3190 <mallctl>stats.arenas.<i>.bins.<j>.nrequests</mallctl> 3191 (<type>uint64_t</type>) 3192 <literal>r-</literal> 3193 [<option>--enable-stats</option>] 3194 </term> 3195 <listitem><para>Cumulative number of allocation requests satisfied by 3196 bin regions of the corresponding size class.</para></listitem> 3197 </varlistentry> 3198 3199 <varlistentry id="stats.arenas.i.bins.j.curregs"> 3200 <term> 3201 <mallctl>stats.arenas.<i>.bins.<j>.curregs</mallctl> 3202 (<type>size_t</type>) 3203 <literal>r-</literal> 3204 [<option>--enable-stats</option>] 3205 </term> 3206 <listitem><para>Current number of regions for this size 3207 class.</para></listitem> 3208 </varlistentry> 3209 3210 <varlistentry id="stats.arenas.i.bins.j.nfills"> 3211 <term> 3212 <mallctl>stats.arenas.<i>.bins.<j>.nfills</mallctl> 3213 (<type>uint64_t</type>) 3214 <literal>r-</literal> 3215 </term> 3216 <listitem><para>Cumulative number of tcache fills.</para></listitem> 3217 </varlistentry> 3218 3219 <varlistentry id="stats.arenas.i.bins.j.nflushes"> 3220 <term> 3221 <mallctl>stats.arenas.<i>.bins.<j>.nflushes</mallctl> 3222 (<type>uint64_t</type>) 3223 <literal>r-</literal> 3224 </term> 3225 <listitem><para>Cumulative number of tcache flushes.</para></listitem> 3226 </varlistentry> 3227 3228 <varlistentry id="stats.arenas.i.bins.j.nslabs"> 3229 <term> 3230 <mallctl>stats.arenas.<i>.bins.<j>.nslabs</mallctl> 3231 (<type>uint64_t</type>) 3232 <literal>r-</literal> 3233 [<option>--enable-stats</option>] 3234 </term> 3235 <listitem><para>Cumulative number of slabs created.</para></listitem> 3236 </varlistentry> 3237 3238 <varlistentry id="stats.arenas.i.bins.j.nreslabs"> 3239 <term> 3240 <mallctl>stats.arenas.<i>.bins.<j>.nreslabs</mallctl> 3241 (<type>uint64_t</type>) 3242 <literal>r-</literal> 3243 [<option>--enable-stats</option>] 3244 </term> 3245 <listitem><para>Cumulative number of times the current slab from which 3246 to allocate changed.</para></listitem> 3247 </varlistentry> 3248 3249 <varlistentry id="stats.arenas.i.bins.j.curslabs"> 3250 <term> 3251 <mallctl>stats.arenas.<i>.bins.<j>.curslabs</mallctl> 3252 (<type>size_t</type>) 3253 <literal>r-</literal> 3254 [<option>--enable-stats</option>] 3255 </term> 3256 <listitem><para>Current number of slabs.</para></listitem> 3257 </varlistentry> 3258 3259 3260 <varlistentry id="stats.arenas.i.bins.j.nonfull_slabs"> 3261 <term> 3262 <mallctl>stats.arenas.<i>.bins.<j>.nonfull_slabs</mallctl> 3263 (<type>size_t</type>) 3264 <literal>r-</literal> 3265 [<option>--enable-stats</option>] 3266 </term> 3267 <listitem><para>Current number of nonfull slabs.</para></listitem> 3268 </varlistentry> 3269 3270 <varlistentry id="stats.arenas.i.bins.mutex"> 3271 <term> 3272 <mallctl>stats.arenas.<i>.bins.<j>.mutex.{counter}</mallctl> 3273 (<type>counter specific type</type>) <literal>r-</literal> 3274 [<option>--enable-stats</option>] 3275 </term> 3276 <listitem><para>Statistics on 3277 <varname>arena.<i>.bins.<j></varname> mutex (arena bin 3278 scope; bin operation related). <mallctl>{counter}</mallctl> is one of 3279 the counters in <link linkend="mutex_counters">mutex profiling 3280 counters</link>.</para></listitem> 3281 </varlistentry> 3282 3283 <varlistentry id="stats.arenas.i.extents.n"> 3284 <term> 3285 <mallctl>stats.arenas.<i>.extents.<j>.n{extent_type}</mallctl> 3286 (<type>size_t</type>) 3287 <literal>r-</literal> 3288 [<option>--enable-stats</option>] 3289 </term> 3290 <listitem><para> Number of extents of the given type in this arena in 3291 the bucket corresponding to page size index <j>. The extent type 3292 is one of dirty, muzzy, or retained.</para></listitem> 3293 </varlistentry> 3294 3295 <varlistentry id="stats.arenas.i.extents.bytes"> 3296 <term> 3297 <mallctl>stats.arenas.<i>.extents.<j>.{extent_type}_bytes</mallctl> 3298 (<type>size_t</type>) 3299 <literal>r-</literal> 3300 [<option>--enable-stats</option>] 3301 </term> 3302 <listitem><para> Sum of the bytes managed by extents of the given type 3303 in this arena in the bucket corresponding to page size index <j>. 3304 The extent type is one of dirty, muzzy, or retained.</para></listitem> 3305 </varlistentry> 3306 3307 <varlistentry id="stats.arenas.i.lextents.j.nmalloc"> 3308 <term> 3309 <mallctl>stats.arenas.<i>.lextents.<j>.nmalloc</mallctl> 3310 (<type>uint64_t</type>) 3311 <literal>r-</literal> 3312 [<option>--enable-stats</option>] 3313 </term> 3314 <listitem><para>Cumulative number of times a large extent of the 3315 corresponding size class was allocated from the arena, whether to fill 3316 the relevant tcache if <link 3317 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3318 the size class is within the range being cached, or to directly satisfy 3319 an allocation request otherwise.</para></listitem> 3320 </varlistentry> 3321 3322 <varlistentry id="stats.arenas.i.lextents.j.ndalloc"> 3323 <term> 3324 <mallctl>stats.arenas.<i>.lextents.<j>.ndalloc</mallctl> 3325 (<type>uint64_t</type>) 3326 <literal>r-</literal> 3327 [<option>--enable-stats</option>] 3328 </term> 3329 <listitem><para>Cumulative number of times a large extent of the 3330 corresponding size class was returned to the arena, whether to flush the 3331 relevant tcache if <link 3332 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3333 the size class is within the range being cached, or to directly 3334 deallocate an allocation otherwise.</para></listitem> 3335 </varlistentry> 3336 3337 <varlistentry id="stats.arenas.i.lextents.j.nrequests"> 3338 <term> 3339 <mallctl>stats.arenas.<i>.lextents.<j>.nrequests</mallctl> 3340 (<type>uint64_t</type>) 3341 <literal>r-</literal> 3342 [<option>--enable-stats</option>] 3343 </term> 3344 <listitem><para>Cumulative number of allocation requests satisfied by 3345 large extents of the corresponding size class.</para></listitem> 3346 </varlistentry> 3347 3348 <varlistentry id="stats.arenas.i.lextents.j.curlextents"> 3349 <term> 3350 <mallctl>stats.arenas.<i>.lextents.<j>.curlextents</mallctl> 3351 (<type>size_t</type>) 3352 <literal>r-</literal> 3353 [<option>--enable-stats</option>] 3354 </term> 3355 <listitem><para>Current number of large allocations for this size class. 3356 </para></listitem> 3357 </varlistentry> 3358 3359 <varlistentry id="stats.arenas.i.mutexes.large"> 3360 <term> 3361 <mallctl>stats.arenas.<i>.mutexes.large.{counter}</mallctl> 3362 (<type>counter specific type</type>) <literal>r-</literal> 3363 [<option>--enable-stats</option>] 3364 </term> 3365 <listitem><para>Statistics on <varname>arena.<i>.large</varname> 3366 mutex (arena scope; large allocation related). 3367 <mallctl>{counter}</mallctl> is one of the counters in <link 3368 linkend="mutex_counters">mutex profiling 3369 counters</link>.</para></listitem> 3370 </varlistentry> 3371 3372 <varlistentry id="stats.arenas.i.mutexes.extent_avail"> 3373 <term> 3374 <mallctl>stats.arenas.<i>.mutexes.extent_avail.{counter}</mallctl> 3375 (<type>counter specific type</type>) <literal>r-</literal> 3376 [<option>--enable-stats</option>] 3377 </term> 3378 <listitem><para>Statistics on <varname>arena.<i>.extent_avail 3379 </varname> mutex (arena scope; extent avail related). 3380 <mallctl>{counter}</mallctl> is one of the counters in <link 3381 linkend="mutex_counters">mutex profiling 3382 counters</link>.</para></listitem> 3383 </varlistentry> 3384 3385 <varlistentry id="stats.arenas.i.mutexes.extents_dirty"> 3386 <term> 3387 <mallctl>stats.arenas.<i>.mutexes.extents_dirty.{counter}</mallctl> 3388 (<type>counter specific type</type>) <literal>r-</literal> 3389 [<option>--enable-stats</option>] 3390 </term> 3391 <listitem><para>Statistics on <varname>arena.<i>.extents_dirty 3392 </varname> mutex (arena scope; dirty extents related). 3393 <mallctl>{counter}</mallctl> is one of the counters in <link 3394 linkend="mutex_counters">mutex profiling 3395 counters</link>.</para></listitem> 3396 </varlistentry> 3397 3398 <varlistentry id="stats.arenas.i.mutexes.extents_muzzy"> 3399 <term> 3400 <mallctl>stats.arenas.<i>.mutexes.extents_muzzy.{counter}</mallctl> 3401 (<type>counter specific type</type>) <literal>r-</literal> 3402 [<option>--enable-stats</option>] 3403 </term> 3404 <listitem><para>Statistics on <varname>arena.<i>.extents_muzzy 3405 </varname> mutex (arena scope; muzzy extents related). 3406 <mallctl>{counter}</mallctl> is one of the counters in <link 3407 linkend="mutex_counters">mutex profiling 3408 counters</link>.</para></listitem> 3409 </varlistentry> 3410 3411 <varlistentry id="stats.arenas.i.mutexes.extents_retained"> 3412 <term> 3413 <mallctl>stats.arenas.<i>.mutexes.extents_retained.{counter}</mallctl> 3414 (<type>counter specific type</type>) <literal>r-</literal> 3415 [<option>--enable-stats</option>] 3416 </term> 3417 <listitem><para>Statistics on <varname>arena.<i>.extents_retained 3418 </varname> mutex (arena scope; retained extents related). 3419 <mallctl>{counter}</mallctl> is one of the counters in <link 3420 linkend="mutex_counters">mutex profiling 3421 counters</link>.</para></listitem> 3422 </varlistentry> 3423 3424 <varlistentry id="stats.arenas.i.mutexes.decay_dirty"> 3425 <term> 3426 <mallctl>stats.arenas.<i>.mutexes.decay_dirty.{counter}</mallctl> 3427 (<type>counter specific type</type>) <literal>r-</literal> 3428 [<option>--enable-stats</option>] 3429 </term> 3430 <listitem><para>Statistics on <varname>arena.<i>.decay_dirty 3431 </varname> mutex (arena scope; decay for dirty pages related). 3432 <mallctl>{counter}</mallctl> is one of the counters in <link 3433 linkend="mutex_counters">mutex profiling 3434 counters</link>.</para></listitem> 3435 </varlistentry> 3436 3437 <varlistentry id="stats.arenas.i.mutexes.decay_muzzy"> 3438 <term> 3439 <mallctl>stats.arenas.<i>.mutexes.decay_muzzy.{counter}</mallctl> 3440 (<type>counter specific type</type>) <literal>r-</literal> 3441 [<option>--enable-stats</option>] 3442 </term> 3443 <listitem><para>Statistics on <varname>arena.<i>.decay_muzzy 3444 </varname> mutex (arena scope; decay for muzzy pages related). 3445 <mallctl>{counter}</mallctl> is one of the counters in <link 3446 linkend="mutex_counters">mutex profiling 3447 counters</link>.</para></listitem> 3448 </varlistentry> 3449 3450 <varlistentry id="stats.arenas.i.mutexes.base"> 3451 <term> 3452 <mallctl>stats.arenas.<i>.mutexes.base.{counter}</mallctl> 3453 (<type>counter specific type</type>) <literal>r-</literal> 3454 [<option>--enable-stats</option>] 3455 </term> 3456 <listitem><para>Statistics on <varname>arena.<i>.base</varname> 3457 mutex (arena scope; base allocator related). 3458 <mallctl>{counter}</mallctl> is one of the counters in <link 3459 linkend="mutex_counters">mutex profiling 3460 counters</link>.</para></listitem> 3461 </varlistentry> 3462 3463 <varlistentry id="stats.arenas.i.mutexes.tcache_list"> 3464 <term> 3465 <mallctl>stats.arenas.<i>.mutexes.tcache_list.{counter}</mallctl> 3466 (<type>counter specific type</type>) <literal>r-</literal> 3467 [<option>--enable-stats</option>] 3468 </term> 3469 <listitem><para>Statistics on 3470 <varname>arena.<i>.tcache_list</varname> mutex (arena scope; 3471 tcache to arena association related). This mutex is expected to be 3472 accessed less often. <mallctl>{counter}</mallctl> is one of the 3473 counters in <link linkend="mutex_counters">mutex profiling 3474 counters</link>.</para></listitem> 3475 </varlistentry> 3476 3477 </variablelist> 3478 </refsect1> 3479 <refsect1 id="heap_profile_format"> 3480 <title>HEAP PROFILE FORMAT</title> 3481 <para>Although the heap profiling functionality was originally designed to 3482 be compatible with the 3483 <command>pprof</command> command that is developed as part of the <ulink 3484 url="http://code.google.com/p/gperftools/">gperftools 3485 package</ulink>, the addition of per thread heap profiling functionality 3486 required a different heap profile format. The <command>jeprof</command> 3487 command is derived from <command>pprof</command>, with enhancements to 3488 support the heap profile format described here.</para> 3489 3490 <para>In the following hypothetical heap profile, <constant>[...]</constant> 3491 indicates elision for the sake of compactness. <programlisting><![CDATA[ 3492heap_v2/524288 3493 t*: 28106: 56637512 [0: 0] 3494 [...] 3495 t3: 352: 16777344 [0: 0] 3496 [...] 3497 t99: 17754: 29341640 [0: 0] 3498 [...] 3499@ 0x5f86da8 0x5f5a1dc [...] 0x29e4d4e 0xa200316 0xabb2988 [...] 3500 t*: 13: 6688 [0: 0] 3501 t3: 12: 6496 [0: 0] 3502 t99: 1: 192 [0: 0] 3503[...] 3504 3505MAPPED_LIBRARIES: 3506[...]]]></programlisting> The following matches the above heap profile, but most 3507tokens are replaced with <constant><description></constant> to indicate 3508descriptions of the corresponding fields. <programlisting><![CDATA[ 3509<heap_profile_format_version>/<mean_sample_interval> 3510 <aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3511 [...] 3512 <thread_3_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3513 [...] 3514 <thread_99_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3515 [...] 3516@ <top_frame> <frame> [...] <frame> <frame> <frame> [...] 3517 <backtrace_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3518 <backtrace_thread_3>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3519 <backtrace_thread_99>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3520[...] 3521 3522MAPPED_LIBRARIES: 3523</proc/<pid>/maps>]]></programlisting></para> 3524 </refsect1> 3525 3526 <refsect1 id="debugging_malloc_problems"> 3527 <title>DEBUGGING MALLOC PROBLEMS</title> 3528 <para>When debugging, it is a good idea to configure/build jemalloc with 3529 the <option>--enable-debug</option> and <option>--enable-fill</option> 3530 options, and recompile the program with suitable options and symbols for 3531 debugger support. When so configured, jemalloc incorporates a wide variety 3532 of run-time assertions that catch application errors such as double-free, 3533 write-after-free, etc.</para> 3534 3535 <para>Programs often accidentally depend on <quote>uninitialized</quote> 3536 memory actually being filled with zero bytes. Junk filling 3537 (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> 3538 option) tends to expose such bugs in the form of obviously incorrect 3539 results and/or coredumps. Conversely, zero 3540 filling (see the <link 3541 linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates 3542 the symptoms of such bugs. Between these two options, it is usually 3543 possible to quickly detect, diagnose, and eliminate such bugs.</para> 3544 3545 <para>This implementation does not provide much detail about the problems 3546 it detects, because the performance impact for storing such information 3547 would be prohibitive.</para> 3548 </refsect1> 3549 <refsect1 id="diagnostic_messages"> 3550 <title>DIAGNOSTIC MESSAGES</title> 3551 <para>If any of the memory allocation/deallocation functions detect an 3552 error or warning condition, a message will be printed to file descriptor 3553 <constant>STDERR_FILENO</constant>. Errors will result in the process 3554 dumping core. If the <link 3555 linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most 3556 warnings are treated as errors.</para> 3557 3558 <para>The <varname>malloc_message</varname> variable allows the programmer 3559 to override the function which emits the text strings forming the errors 3560 and warnings if for some reason the <constant>STDERR_FILENO</constant> file 3561 descriptor is not suitable for this. 3562 <function>malloc_message()</function> takes the 3563 <parameter>cbopaque</parameter> pointer argument that is 3564 <constant>NULL</constant> unless overridden by the arguments in a call to 3565 <function>malloc_stats_print()</function>, followed by a string 3566 pointer. Please note that doing anything which tries to allocate memory in 3567 this function is likely to result in a crash or deadlock.</para> 3568 3569 <para>All messages are prefixed by 3570 <quote><computeroutput><jemalloc>: </computeroutput></quote>.</para> 3571 </refsect1> 3572 <refsect1 id="return_values"> 3573 <title>RETURN VALUES</title> 3574 <refsect2> 3575 <title>Standard API</title> 3576 <para>The <function>malloc()</function> and 3577 <function>calloc()</function> functions return a pointer to the 3578 allocated memory if successful; otherwise a <constant>NULL</constant> 3579 pointer is returned and <varname>errno</varname> is set to 3580 <errorname>ENOMEM</errorname>.</para> 3581 3582 <para>The <function>posix_memalign()</function> function 3583 returns the value 0 if successful; otherwise it returns an error value. 3584 The <function>posix_memalign()</function> function will fail 3585 if: 3586 <variablelist> 3587 <varlistentry> 3588 <term><errorname>EINVAL</errorname></term> 3589 3590 <listitem><para>The <parameter>alignment</parameter> parameter is 3591 not a power of 2 at least as large as 3592 <code language="C">sizeof(<type>void *</type>)</code>. 3593 </para></listitem> 3594 </varlistentry> 3595 <varlistentry> 3596 <term><errorname>ENOMEM</errorname></term> 3597 3598 <listitem><para>Memory allocation error.</para></listitem> 3599 </varlistentry> 3600 </variablelist> 3601 </para> 3602 3603 <para>The <function>aligned_alloc()</function> function returns 3604 a pointer to the allocated memory if successful; otherwise a 3605 <constant>NULL</constant> pointer is returned and 3606 <varname>errno</varname> is set. The 3607 <function>aligned_alloc()</function> function will fail if: 3608 <variablelist> 3609 <varlistentry> 3610 <term><errorname>EINVAL</errorname></term> 3611 3612 <listitem><para>The <parameter>alignment</parameter> parameter is 3613 not a power of 2. 3614 </para></listitem> 3615 </varlistentry> 3616 <varlistentry> 3617 <term><errorname>ENOMEM</errorname></term> 3618 3619 <listitem><para>Memory allocation error.</para></listitem> 3620 </varlistentry> 3621 </variablelist> 3622 </para> 3623 3624 <para>The <function>realloc()</function> function returns a 3625 pointer, possibly identical to <parameter>ptr</parameter>, to the 3626 allocated memory if successful; otherwise a <constant>NULL</constant> 3627 pointer is returned, and <varname>errno</varname> is set to 3628 <errorname>ENOMEM</errorname> if the error was the result of an 3629 allocation failure. The <function>realloc()</function> 3630 function always leaves the original buffer intact when an error occurs. 3631 </para> 3632 3633 <para>The <function>free()</function> function returns no 3634 value.</para> 3635 </refsect2> 3636 <refsect2> 3637 <title>Non-standard API</title> 3638 <para>The <function>mallocx()</function> and 3639 <function>rallocx()</function> functions return a pointer to 3640 the allocated memory if successful; otherwise a <constant>NULL</constant> 3641 pointer is returned to indicate insufficient contiguous memory was 3642 available to service the allocation request. </para> 3643 3644 <para>The <function>xallocx()</function> function returns the 3645 real size of the resulting resized allocation pointed to by 3646 <parameter>ptr</parameter>, which is a value less than 3647 <parameter>size</parameter> if the allocation could not be adequately 3648 grown in place. </para> 3649 3650 <para>The <function>sallocx()</function> function returns the 3651 real size of the allocation pointed to by <parameter>ptr</parameter>. 3652 </para> 3653 3654 <para>The <function>nallocx()</function> returns the real size 3655 that would result from a successful equivalent 3656 <function>mallocx()</function> function call, or zero if 3657 insufficient memory is available to perform the size computation. </para> 3658 3659 <para>The <function>mallctl()</function>, 3660 <function>mallctlnametomib()</function>, and 3661 <function>mallctlbymib()</function> functions return 0 on 3662 success; otherwise they return an error value. The functions will fail 3663 if: 3664 <variablelist> 3665 <varlistentry> 3666 <term><errorname>EINVAL</errorname></term> 3667 3668 <listitem><para><parameter>newp</parameter> is not 3669 <constant>NULL</constant>, and <parameter>newlen</parameter> is too 3670 large or too small. Alternatively, <parameter>*oldlenp</parameter> 3671 is too large or too small; when it happens, except for a very few 3672 cases explicitly documented otherwise, as much data as possible 3673 are read despite the error, with the amount of data read being 3674 recorded in <parameter>*oldlenp</parameter>.</para></listitem> 3675 </varlistentry> 3676 <varlistentry> 3677 <term><errorname>ENOENT</errorname></term> 3678 3679 <listitem><para><parameter>name</parameter> or 3680 <parameter>mib</parameter> specifies an unknown/invalid 3681 value.</para></listitem> 3682 </varlistentry> 3683 <varlistentry> 3684 <term><errorname>EPERM</errorname></term> 3685 3686 <listitem><para>Attempt to read or write void value, or attempt to 3687 write read-only value.</para></listitem> 3688 </varlistentry> 3689 <varlistentry> 3690 <term><errorname>EAGAIN</errorname></term> 3691 3692 <listitem><para>A memory allocation failure 3693 occurred.</para></listitem> 3694 </varlistentry> 3695 <varlistentry> 3696 <term><errorname>EFAULT</errorname></term> 3697 3698 <listitem><para>An interface with side effects failed in some way 3699 not directly related to <function>mallctl*()</function> 3700 read/write processing.</para></listitem> 3701 </varlistentry> 3702 </variablelist> 3703 </para> 3704 3705 <para>The <function>malloc_usable_size()</function> function 3706 returns the usable size of the allocation pointed to by 3707 <parameter>ptr</parameter>. </para> 3708 </refsect2> 3709 </refsect1> 3710 <refsect1 id="environment"> 3711 <title>ENVIRONMENT</title> 3712 <para>The following environment variable affects the execution of the 3713 allocation functions: 3714 <variablelist> 3715 <varlistentry> 3716 <term><envar>MALLOC_CONF</envar></term> 3717 3718 <listitem><para>If the environment variable 3719 <envar>MALLOC_CONF</envar> is set, the characters it contains 3720 will be interpreted as options.</para></listitem> 3721 </varlistentry> 3722 </variablelist> 3723 </para> 3724 </refsect1> 3725 <refsect1 id="examples"> 3726 <title>EXAMPLES</title> 3727 <para>To dump core whenever a problem occurs: 3728 <screen>ln -s 'abort:true' /etc/malloc.conf</screen> 3729 </para> 3730 <para>To specify in the source that only one arena should be automatically 3731 created: 3732 <programlisting language="C"><![CDATA[ 3733malloc_conf = "narenas:1";]]></programlisting></para> 3734 </refsect1> 3735 <refsect1 id="see_also"> 3736 <title>SEE ALSO</title> 3737 <para><citerefentry><refentrytitle>madvise</refentrytitle> 3738 <manvolnum>2</manvolnum></citerefentry>, 3739 <citerefentry><refentrytitle>mmap</refentrytitle> 3740 <manvolnum>2</manvolnum></citerefentry>, 3741 <citerefentry><refentrytitle>sbrk</refentrytitle> 3742 <manvolnum>2</manvolnum></citerefentry>, 3743 <citerefentry><refentrytitle>utrace</refentrytitle> 3744 <manvolnum>2</manvolnum></citerefentry>, 3745 <citerefentry><refentrytitle>alloca</refentrytitle> 3746 <manvolnum>3</manvolnum></citerefentry>, 3747 <citerefentry><refentrytitle>atexit</refentrytitle> 3748 <manvolnum>3</manvolnum></citerefentry>, 3749 <citerefentry><refentrytitle>getpagesize</refentrytitle> 3750 <manvolnum>3</manvolnum></citerefentry></para> 3751 </refsect1> 3752 <refsect1 id="standards"> 3753 <title>STANDARDS</title> 3754 <para>The <function>malloc()</function>, 3755 <function>calloc()</function>, 3756 <function>realloc()</function>, and 3757 <function>free()</function> functions conform to ISO/IEC 3758 9899:1990 (<quote>ISO C90</quote>).</para> 3759 3760 <para>The <function>posix_memalign()</function> function conforms 3761 to IEEE Std 1003.1-2001 (<quote>POSIX.1</quote>).</para> 3762 </refsect1> 3763</refentry> 3764