1<<<<<<< HEAD 2<?xml version='1.0' encoding='UTF-8'?> 3<?xml-stylesheet type="text/xsl" 4 href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?> 5<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 6 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ 7]> 8 9<refentry> 10 <refentryinfo> 11 <title>User Manual</title> 12 <productname>jemalloc</productname> 13 <releaseinfo role="version">@jemalloc_version@</releaseinfo> 14 <authorgroup> 15 <author> 16 <firstname>Jason</firstname> 17 <surname>Evans</surname> 18 <personblurb>Author</personblurb> 19 </author> 20 </authorgroup> 21 </refentryinfo> 22 <refmeta> 23 <refentrytitle>JEMALLOC</refentrytitle> 24 <manvolnum>3</manvolnum> 25 </refmeta> 26 <refnamediv> 27 <refdescriptor>jemalloc</refdescriptor> 28 <refname>jemalloc</refname> 29 <!-- Each refname causes a man page file to be created. Only if this were 30 the system malloc(3) implementation would these files be appropriate. 31 <refname>malloc</refname> 32 <refname>calloc</refname> 33 <refname>posix_memalign</refname> 34 <refname>aligned_alloc</refname> 35 <refname>realloc</refname> 36 <refname>free</refname> 37 <refname>mallocx</refname> 38 <refname>rallocx</refname> 39 <refname>xallocx</refname> 40 <refname>sallocx</refname> 41 <refname>dallocx</refname> 42 <refname>sdallocx</refname> 43 <refname>nallocx</refname> 44 <refname>mallctl</refname> 45 <refname>mallctlnametomib</refname> 46 <refname>mallctlbymib</refname> 47 <refname>malloc_stats_print</refname> 48 <refname>malloc_usable_size</refname> 49 --> 50 <refpurpose>general purpose memory allocation functions</refpurpose> 51 </refnamediv> 52 <refsect1 id="library"> 53 <title>LIBRARY</title> 54 <para>This manual describes jemalloc @jemalloc_version@. More information 55 can be found at the <ulink 56 url="http://jemalloc.net/">jemalloc website</ulink>.</para> 57 58 <para>The following configuration options are enabled in libc's built-in 59 jemalloc: <option>--enable-fill</option>, 60 <option>--enable-lazy-lock</option>, <option>--enable-stats</option>, 61 <option>--enable-utrace</option>, <option>--enable-xmalloc</option>, and 62 <option>--with-malloc-conf=abort_conf:false</option>. 63 Additionally, <option>--enable-debug</option> is enabled in development 64 versions of FreeBSD (controlled by the 65 <constant>MK_MALLOC_PRODUCTION</constant> make variable).</para> 66 67 </refsect1> 68 <refsynopsisdiv> 69 <title>SYNOPSIS</title> 70 <funcsynopsis> 71 <funcsynopsisinfo>#include <<filename class="headerfile">stdlib.h</filename>> 72#include <<filename class="headerfile">malloc_np.h</filename>></funcsynopsisinfo> 73 <refsect2> 74 <title>Standard API</title> 75 <funcprototype> 76 <funcdef>void *<function>malloc</function></funcdef> 77 <paramdef>size_t <parameter>size</parameter></paramdef> 78 </funcprototype> 79 <funcprototype> 80 <funcdef>void *<function>calloc</function></funcdef> 81 <paramdef>size_t <parameter>number</parameter></paramdef> 82 <paramdef>size_t <parameter>size</parameter></paramdef> 83 </funcprototype> 84 <funcprototype> 85 <funcdef>int <function>posix_memalign</function></funcdef> 86 <paramdef>void **<parameter>ptr</parameter></paramdef> 87 <paramdef>size_t <parameter>alignment</parameter></paramdef> 88 <paramdef>size_t <parameter>size</parameter></paramdef> 89 </funcprototype> 90 <funcprototype> 91 <funcdef>void *<function>aligned_alloc</function></funcdef> 92 <paramdef>size_t <parameter>alignment</parameter></paramdef> 93 <paramdef>size_t <parameter>size</parameter></paramdef> 94 </funcprototype> 95 <funcprototype> 96 <funcdef>void *<function>realloc</function></funcdef> 97 <paramdef>void *<parameter>ptr</parameter></paramdef> 98 <paramdef>size_t <parameter>size</parameter></paramdef> 99 </funcprototype> 100 <funcprototype> 101 <funcdef>void <function>free</function></funcdef> 102 <paramdef>void *<parameter>ptr</parameter></paramdef> 103 </funcprototype> 104 </refsect2> 105 <refsect2> 106 <title>Non-standard API</title> 107 <funcprototype> 108 <funcdef>void *<function>mallocx</function></funcdef> 109 <paramdef>size_t <parameter>size</parameter></paramdef> 110 <paramdef>int <parameter>flags</parameter></paramdef> 111 </funcprototype> 112 <funcprototype> 113 <funcdef>void *<function>rallocx</function></funcdef> 114 <paramdef>void *<parameter>ptr</parameter></paramdef> 115 <paramdef>size_t <parameter>size</parameter></paramdef> 116 <paramdef>int <parameter>flags</parameter></paramdef> 117 </funcprototype> 118 <funcprototype> 119 <funcdef>size_t <function>xallocx</function></funcdef> 120 <paramdef>void *<parameter>ptr</parameter></paramdef> 121 <paramdef>size_t <parameter>size</parameter></paramdef> 122 <paramdef>size_t <parameter>extra</parameter></paramdef> 123 <paramdef>int <parameter>flags</parameter></paramdef> 124 </funcprototype> 125 <funcprototype> 126 <funcdef>size_t <function>sallocx</function></funcdef> 127 <paramdef>void *<parameter>ptr</parameter></paramdef> 128 <paramdef>int <parameter>flags</parameter></paramdef> 129 </funcprototype> 130 <funcprototype> 131 <funcdef>void <function>dallocx</function></funcdef> 132 <paramdef>void *<parameter>ptr</parameter></paramdef> 133 <paramdef>int <parameter>flags</parameter></paramdef> 134 </funcprototype> 135 <funcprototype> 136 <funcdef>void <function>sdallocx</function></funcdef> 137 <paramdef>void *<parameter>ptr</parameter></paramdef> 138 <paramdef>size_t <parameter>size</parameter></paramdef> 139 <paramdef>int <parameter>flags</parameter></paramdef> 140 </funcprototype> 141 <funcprototype> 142 <funcdef>size_t <function>nallocx</function></funcdef> 143 <paramdef>size_t <parameter>size</parameter></paramdef> 144 <paramdef>int <parameter>flags</parameter></paramdef> 145 </funcprototype> 146 <funcprototype> 147 <funcdef>int <function>mallctl</function></funcdef> 148 <paramdef>const char *<parameter>name</parameter></paramdef> 149 <paramdef>void *<parameter>oldp</parameter></paramdef> 150 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 151 <paramdef>void *<parameter>newp</parameter></paramdef> 152 <paramdef>size_t <parameter>newlen</parameter></paramdef> 153 </funcprototype> 154 <funcprototype> 155 <funcdef>int <function>mallctlnametomib</function></funcdef> 156 <paramdef>const char *<parameter>name</parameter></paramdef> 157 <paramdef>size_t *<parameter>mibp</parameter></paramdef> 158 <paramdef>size_t *<parameter>miblenp</parameter></paramdef> 159 </funcprototype> 160 <funcprototype> 161 <funcdef>int <function>mallctlbymib</function></funcdef> 162 <paramdef>const size_t *<parameter>mib</parameter></paramdef> 163 <paramdef>size_t <parameter>miblen</parameter></paramdef> 164 <paramdef>void *<parameter>oldp</parameter></paramdef> 165 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 166 <paramdef>void *<parameter>newp</parameter></paramdef> 167 <paramdef>size_t <parameter>newlen</parameter></paramdef> 168 </funcprototype> 169 <funcprototype> 170 <funcdef>void <function>malloc_stats_print</function></funcdef> 171 <paramdef>void <parameter>(*write_cb)</parameter> 172 <funcparams>void *, const char *</funcparams> 173 </paramdef> 174 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 175 <paramdef>const char *<parameter>opts</parameter></paramdef> 176 </funcprototype> 177 <funcprototype> 178 <funcdef>size_t <function>malloc_usable_size</function></funcdef> 179 <paramdef>const void *<parameter>ptr</parameter></paramdef> 180 </funcprototype> 181 <funcprototype> 182 <funcdef>void <function>(*malloc_message)</function></funcdef> 183 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 184 <paramdef>const char *<parameter>s</parameter></paramdef> 185 </funcprototype> 186 <para><type>const char *</type><varname>malloc_conf</varname>;</para> 187 </refsect2> 188 </funcsynopsis> 189 </refsynopsisdiv> 190 <refsect1 id="description"> 191 <title>DESCRIPTION</title> 192 <refsect2> 193 <title>Standard API</title> 194 195 <para>The <function>malloc()</function> function allocates 196 <parameter>size</parameter> bytes of uninitialized memory. The allocated 197 space is suitably aligned (after possible pointer coercion) for storage 198 of any type of object.</para> 199 200 <para>The <function>calloc()</function> function allocates 201 space for <parameter>number</parameter> objects, each 202 <parameter>size</parameter> bytes in length. The result is identical to 203 calling <function>malloc()</function> with an argument of 204 <parameter>number</parameter> * <parameter>size</parameter>, with the 205 exception that the allocated memory is explicitly initialized to zero 206 bytes.</para> 207 208 <para>The <function>posix_memalign()</function> function 209 allocates <parameter>size</parameter> bytes of memory such that the 210 allocation's base address is a multiple of 211 <parameter>alignment</parameter>, and returns the allocation in the value 212 pointed to by <parameter>ptr</parameter>. The requested 213 <parameter>alignment</parameter> must be a power of 2 at least as large as 214 <code language="C">sizeof(<type>void *</type>)</code>.</para> 215 216 <para>The <function>aligned_alloc()</function> function 217 allocates <parameter>size</parameter> bytes of memory such that the 218 allocation's base address is a multiple of 219 <parameter>alignment</parameter>. The requested 220 <parameter>alignment</parameter> must be a power of 2. Behavior is 221 undefined if <parameter>size</parameter> is not an integral multiple of 222 <parameter>alignment</parameter>.</para> 223 224 <para>The <function>realloc()</function> function changes the 225 size of the previously allocated memory referenced by 226 <parameter>ptr</parameter> to <parameter>size</parameter> bytes. The 227 contents of the memory are unchanged up to the lesser of the new and old 228 sizes. If the new size is larger, the contents of the newly allocated 229 portion of the memory are undefined. Upon success, the memory referenced 230 by <parameter>ptr</parameter> is freed and a pointer to the newly 231 allocated memory is returned. Note that 232 <function>realloc()</function> may move the memory allocation, 233 resulting in a different return value than <parameter>ptr</parameter>. 234 If <parameter>ptr</parameter> is <constant>NULL</constant>, the 235 <function>realloc()</function> function behaves identically to 236 <function>malloc()</function> for the specified size.</para> 237 238 <para>The <function>free()</function> function causes the 239 allocated memory referenced by <parameter>ptr</parameter> to be made 240 available for future allocations. If <parameter>ptr</parameter> is 241 <constant>NULL</constant>, no action occurs.</para> 242 </refsect2> 243 <refsect2> 244 <title>Non-standard API</title> 245 <para>The <function>mallocx()</function>, 246 <function>rallocx()</function>, 247 <function>xallocx()</function>, 248 <function>sallocx()</function>, 249 <function>dallocx()</function>, 250 <function>sdallocx()</function>, and 251 <function>nallocx()</function> functions all have a 252 <parameter>flags</parameter> argument that can be used to specify 253 options. The functions only check the options that are contextually 254 relevant. Use bitwise or (<code language="C">|</code>) operations to 255 specify one or more of the following: 256 <variablelist> 257 <varlistentry id="MALLOCX_LG_ALIGN"> 258 <term><constant>MALLOCX_LG_ALIGN(<parameter>la</parameter>) 259 </constant></term> 260 261 <listitem><para>Align the memory allocation to start at an address 262 that is a multiple of <code language="C">(1 << 263 <parameter>la</parameter>)</code>. This macro does not validate 264 that <parameter>la</parameter> is within the valid 265 range.</para></listitem> 266 </varlistentry> 267 <varlistentry id="MALLOCX_ALIGN"> 268 <term><constant>MALLOCX_ALIGN(<parameter>a</parameter>) 269 </constant></term> 270 271 <listitem><para>Align the memory allocation to start at an address 272 that is a multiple of <parameter>a</parameter>, where 273 <parameter>a</parameter> is a power of two. This macro does not 274 validate that <parameter>a</parameter> is a power of 2. 275 </para></listitem> 276 </varlistentry> 277 <varlistentry id="MALLOCX_ZERO"> 278 <term><constant>MALLOCX_ZERO</constant></term> 279 280 <listitem><para>Initialize newly allocated memory to contain zero 281 bytes. In the growing reallocation case, the real size prior to 282 reallocation defines the boundary between untouched bytes and those 283 that are initialized to contain zero bytes. If this macro is 284 absent, newly allocated memory is uninitialized.</para></listitem> 285 </varlistentry> 286 <varlistentry id="MALLOCX_TCACHE"> 287 <term><constant>MALLOCX_TCACHE(<parameter>tc</parameter>) 288 </constant></term> 289 290 <listitem><para>Use the thread-specific cache (tcache) specified by 291 the identifier <parameter>tc</parameter>, which must have been 292 acquired via the <link 293 linkend="tcache.create"><mallctl>tcache.create</mallctl></link> 294 mallctl. This macro does not validate that 295 <parameter>tc</parameter> specifies a valid 296 identifier.</para></listitem> 297 </varlistentry> 298 <varlistentry id="MALLOC_TCACHE_NONE"> 299 <term><constant>MALLOCX_TCACHE_NONE</constant></term> 300 301 <listitem><para>Do not use a thread-specific cache (tcache). Unless 302 <constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant> or 303 <constant>MALLOCX_TCACHE_NONE</constant> is specified, an 304 automatically managed tcache will be used under many circumstances. 305 This macro cannot be used in the same <parameter>flags</parameter> 306 argument as 307 <constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant>.</para></listitem> 308 </varlistentry> 309 <varlistentry id="MALLOCX_ARENA"> 310 <term><constant>MALLOCX_ARENA(<parameter>a</parameter>) 311 </constant></term> 312 313 <listitem><para>Use the arena specified by the index 314 <parameter>a</parameter>. This macro has no effect for regions that 315 were allocated via an arena other than the one specified. This 316 macro does not validate that <parameter>a</parameter> specifies an 317 arena index in the valid range.</para></listitem> 318 </varlistentry> 319 </variablelist> 320 </para> 321 322 <para>The <function>mallocx()</function> function allocates at 323 least <parameter>size</parameter> bytes of memory, and returns a pointer 324 to the base address of the allocation. Behavior is undefined if 325 <parameter>size</parameter> is <constant>0</constant>.</para> 326 327 <para>The <function>rallocx()</function> function resizes the 328 allocation at <parameter>ptr</parameter> to be at least 329 <parameter>size</parameter> bytes, and returns a pointer to the base 330 address of the resulting allocation, which may or may not have moved from 331 its original location. Behavior is undefined if 332 <parameter>size</parameter> is <constant>0</constant>.</para> 333 334 <para>The <function>xallocx()</function> function resizes the 335 allocation at <parameter>ptr</parameter> in place to be at least 336 <parameter>size</parameter> bytes, and returns the real size of the 337 allocation. If <parameter>extra</parameter> is non-zero, an attempt is 338 made to resize the allocation to be at least <code 339 language="C">(<parameter>size</parameter> + 340 <parameter>extra</parameter>)</code> bytes, though inability to allocate 341 the extra byte(s) will not by itself result in failure to resize. 342 Behavior is undefined if <parameter>size</parameter> is 343 <constant>0</constant>, or if <code 344 language="C">(<parameter>size</parameter> + <parameter>extra</parameter> 345 > <constant>SIZE_T_MAX</constant>)</code>.</para> 346 347 <para>The <function>sallocx()</function> function returns the 348 real size of the allocation at <parameter>ptr</parameter>.</para> 349 350 <para>The <function>dallocx()</function> function causes the 351 memory referenced by <parameter>ptr</parameter> to be made available for 352 future allocations.</para> 353 354 <para>The <function>sdallocx()</function> function is an 355 extension of <function>dallocx()</function> with a 356 <parameter>size</parameter> parameter to allow the caller to pass in the 357 allocation size as an optimization. The minimum valid input size is the 358 original requested size of the allocation, and the maximum valid input 359 size is the corresponding value returned by 360 <function>nallocx()</function> or 361 <function>sallocx()</function>.</para> 362 363 <para>The <function>nallocx()</function> function allocates no 364 memory, but it performs the same size computation as the 365 <function>mallocx()</function> function, and returns the real 366 size of the allocation that would result from the equivalent 367 <function>mallocx()</function> function call, or 368 <constant>0</constant> if the inputs exceed the maximum supported size 369 class and/or alignment. Behavior is undefined if 370 <parameter>size</parameter> is <constant>0</constant>.</para> 371 372 <para>The <function>mallctl()</function> function provides a 373 general interface for introspecting the memory allocator, as well as 374 setting modifiable parameters and triggering actions. The 375 period-separated <parameter>name</parameter> argument specifies a 376 location in a tree-structured namespace; see the <xref 377 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for 378 documentation on the tree contents. To read a value, pass a pointer via 379 <parameter>oldp</parameter> to adequate space to contain the value, and a 380 pointer to its length via <parameter>oldlenp</parameter>; otherwise pass 381 <constant>NULL</constant> and <constant>NULL</constant>. Similarly, to 382 write a value, pass a pointer to the value via 383 <parameter>newp</parameter>, and its length via 384 <parameter>newlen</parameter>; otherwise pass <constant>NULL</constant> 385 and <constant>0</constant>.</para> 386 387 <para>The <function>mallctlnametomib()</function> function 388 provides a way to avoid repeated name lookups for applications that 389 repeatedly query the same portion of the namespace, by translating a name 390 to a <quote>Management Information Base</quote> (MIB) that can be passed 391 repeatedly to <function>mallctlbymib()</function>. Upon 392 successful return from <function>mallctlnametomib()</function>, 393 <parameter>mibp</parameter> contains an array of 394 <parameter>*miblenp</parameter> integers, where 395 <parameter>*miblenp</parameter> is the lesser of the number of components 396 in <parameter>name</parameter> and the input value of 397 <parameter>*miblenp</parameter>. Thus it is possible to pass a 398 <parameter>*miblenp</parameter> that is smaller than the number of 399 period-separated name components, which results in a partial MIB that can 400 be used as the basis for constructing a complete MIB. For name 401 components that are integers (e.g. the 2 in 402 <link 403 linkend="arenas.bin.i.size"><mallctl>arenas.bin.2.size</mallctl></link>), 404 the corresponding MIB component will always be that integer. Therefore, 405 it is legitimate to construct code like the following: <programlisting 406 language="C"><![CDATA[ 407unsigned nbins, i; 408size_t mib[4]; 409size_t len, miblen; 410 411len = sizeof(nbins); 412mallctl("arenas.nbins", &nbins, &len, NULL, 0); 413 414miblen = 4; 415mallctlnametomib("arenas.bin.0.size", mib, &miblen); 416for (i = 0; i < nbins; i++) { 417 size_t bin_size; 418 419 mib[2] = i; 420 len = sizeof(bin_size); 421 mallctlbymib(mib, miblen, (void *)&bin_size, &len, NULL, 0); 422 /* Do something with bin_size... */ 423}]]></programlisting></para> 424 425 <varlistentry id="malloc_stats_print_opts"> 426 </varlistentry> 427 <para>The <function>malloc_stats_print()</function> function writes 428 summary statistics via the <parameter>write_cb</parameter> callback 429 function pointer and <parameter>cbopaque</parameter> data passed to 430 <parameter>write_cb</parameter>, or <function>malloc_message()</function> 431 if <parameter>write_cb</parameter> is <constant>NULL</constant>. The 432 statistics are presented in human-readable form unless <quote>J</quote> is 433 specified as a character within the <parameter>opts</parameter> string, in 434 which case the statistics are presented in <ulink 435 url="http://www.json.org/">JSON format</ulink>. This function can be 436 called repeatedly. General information that never changes during 437 execution can be omitted by specifying <quote>g</quote> as a character 438 within the <parameter>opts</parameter> string. Note that 439 <function>malloc_stats_print()</function> uses the 440 <function>mallctl*()</function> functions internally, so inconsistent 441 statistics can be reported if multiple threads use these functions 442 simultaneously. If <option>--enable-stats</option> is specified during 443 configuration, <quote>m</quote>, <quote>d</quote>, and <quote>a</quote> 444 can be specified to omit merged arena, destroyed merged arena, and per 445 arena statistics, respectively; <quote>b</quote> and <quote>l</quote> can 446 be specified to omit per size class statistics for bins and large objects, 447 respectively; <quote>x</quote> can be specified to omit all mutex 448 statistics; <quote>e</quote> can be used to omit extent statistics. 449 Unrecognized characters are silently ignored. Note that thread caching 450 may prevent some statistics from being completely up to date, since extra 451 locking would be required to merge counters that track thread cache 452 operations.</para> 453 454 <para>The <function>malloc_usable_size()</function> function 455 returns the usable size of the allocation pointed to by 456 <parameter>ptr</parameter>. The return value may be larger than the size 457 that was requested during allocation. The 458 <function>malloc_usable_size()</function> function is not a 459 mechanism for in-place <function>realloc()</function>; rather 460 it is provided solely as a tool for introspection purposes. Any 461 discrepancy between the requested allocation size and the size reported 462 by <function>malloc_usable_size()</function> should not be 463 depended on, since such behavior is entirely implementation-dependent. 464 </para> 465 </refsect2> 466 </refsect1> 467 <refsect1 id="tuning"> 468 <title>TUNING</title> 469 <para>Once, when the first call is made to one of the memory allocation 470 routines, the allocator initializes its internals based in part on various 471 options that can be specified at compile- or run-time.</para> 472 473 <para>The string specified via <option>--with-malloc-conf</option>, the 474 string pointed to by the global variable <varname>malloc_conf</varname>, the 475 <quote>name</quote> of the file referenced by the symbolic link named 476 <filename class="symlink">/etc/malloc.conf</filename>, and the value of the 477 environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in 478 that order, from left to right as options. Note that 479 <varname>malloc_conf</varname> may be read before 480 <function>main()</function> is entered, so the declaration of 481 <varname>malloc_conf</varname> should specify an initializer that contains 482 the final value to be read by jemalloc. <option>--with-malloc-conf</option> 483 and <varname>malloc_conf</varname> are compile-time mechanisms, whereas 484 <filename class="symlink">/etc/malloc.conf</filename> and 485 <envar>MALLOC_CONF</envar> can be safely set any time prior to program 486 invocation.</para> 487 488 <para>An options string is a comma-separated list of option:value pairs. 489 There is one key corresponding to each <link 490 linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the <xref 491 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for options 492 documentation). For example, <literal>abort:true,narenas:1</literal> sets 493 the <link linkend="opt.abort"><mallctl>opt.abort</mallctl></link> and <link 494 linkend="opt.narenas"><mallctl>opt.narenas</mallctl></link> options. Some 495 options have boolean values (true/false), others have integer values (base 496 8, 10, or 16, depending on prefix), and yet others have raw string 497 values.</para> 498 </refsect1> 499 <refsect1 id="implementation_notes"> 500 <title>IMPLEMENTATION NOTES</title> 501 <para>Traditionally, allocators have used 502 <citerefentry><refentrytitle>sbrk</refentrytitle> 503 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is 504 suboptimal for several reasons, including race conditions, increased 505 fragmentation, and artificial limitations on maximum usable memory. If 506 <citerefentry><refentrytitle>sbrk</refentrytitle> 507 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 508 system, this allocator uses both 509 <citerefentry><refentrytitle>mmap</refentrytitle> 510 <manvolnum>2</manvolnum></citerefentry> and 511 <citerefentry><refentrytitle>sbrk</refentrytitle> 512 <manvolnum>2</manvolnum></citerefentry>, in that order of preference; 513 otherwise only <citerefentry><refentrytitle>mmap</refentrytitle> 514 <manvolnum>2</manvolnum></citerefentry> is used.</para> 515 516 <para>This allocator uses multiple arenas in order to reduce lock 517 contention for threaded programs on multi-processor systems. This works 518 well with regard to threading scalability, but incurs some costs. There is 519 a small fixed per-arena overhead, and additionally, arenas manage memory 520 completely independently of each other, which means a small fixed increase 521 in overall memory fragmentation. These overheads are not generally an 522 issue, given the number of arenas normally used. Note that using 523 substantially more arenas than the default is not likely to improve 524 performance, mainly due to reduced cache performance. However, it may make 525 sense to reduce the number of arenas if an application does not make much 526 use of the allocation functions.</para> 527 528 <para>In addition to multiple arenas, this allocator supports 529 thread-specific caching, in order to make it possible to completely avoid 530 synchronization for most allocation requests. Such caching allows very fast 531 allocation in the common case, but it increases memory usage and 532 fragmentation, since a bounded number of objects can remain allocated in 533 each thread cache.</para> 534 535 <para>Memory is conceptually broken into extents. Extents are always 536 aligned to multiples of the page size. This alignment makes it possible to 537 find metadata for user objects quickly. User objects are broken into two 538 categories according to size: small and large. Contiguous small objects 539 comprise a slab, which resides within a single extent, whereas large objects 540 each have their own extents backing them.</para> 541 542 <para>Small objects are managed in groups by slabs. Each slab maintains 543 a bitmap to track which regions are in use. Allocation requests that are no 544 more than half the quantum (8 or 16, depending on architecture) are rounded 545 up to the nearest power of two that is at least <code 546 language="C">sizeof(<type>double</type>)</code>. All other object size 547 classes are multiples of the quantum, spaced such that there are four size 548 classes for each doubling in size, which limits internal fragmentation to 549 approximately 20% for all but the smallest size classes. Small size classes 550 are smaller than four times the page size, and large size classes extend 551 from four times the page size up to the largest size class that does not 552 exceed <constant>PTRDIFF_MAX</constant>.</para> 553 554 <para>Allocations are packed tightly together, which can be an issue for 555 multi-threaded applications. If you need to assure that allocations do not 556 suffer from cacheline sharing, round your allocation requests up to the 557 nearest multiple of the cacheline size, or specify cacheline alignment when 558 allocating.</para> 559 560 <para>The <function>realloc()</function>, 561 <function>rallocx()</function>, and 562 <function>xallocx()</function> functions may resize allocations 563 without moving them under limited circumstances. Unlike the 564 <function>*allocx()</function> API, the standard API does not 565 officially round up the usable size of an allocation to the nearest size 566 class, so technically it is necessary to call 567 <function>realloc()</function> to grow e.g. a 9-byte allocation to 568 16 bytes, or shrink a 16-byte allocation to 9 bytes. Growth and shrinkage 569 trivially succeeds in place as long as the pre-size and post-size both round 570 up to the same size class. No other API guarantees are made regarding 571 in-place resizing, but the current implementation also tries to resize large 572 allocations in place, as long as the pre-size and post-size are both large. 573 For shrinkage to succeed, the extent allocator must support splitting (see 574 <link 575 linkend="arena.i.extent_hooks"><mallctl>arena.<i>.extent_hooks</mallctl></link>). 576 Growth only succeeds if the trailing memory is currently available, and the 577 extent allocator supports merging.</para> 578 579 <para>Assuming 4 KiB pages and a 16-byte quantum on a 64-bit system, the 580 size classes in each category are as shown in <xref linkend="size_classes" 581 xrefstyle="template:Table %n"/>.</para> 582 583 <table xml:id="size_classes" frame="all"> 584 <title>Size classes</title> 585 <tgroup cols="3" colsep="1" rowsep="1"> 586 <colspec colname="c1" align="left"/> 587 <colspec colname="c2" align="right"/> 588 <colspec colname="c3" align="left"/> 589 <thead> 590 <row> 591 <entry>Category</entry> 592 <entry>Spacing</entry> 593 <entry>Size</entry> 594 </row> 595 </thead> 596 <tbody> 597 <row> 598 <entry morerows="8">Small</entry> 599 <entry>lg</entry> 600 <entry>[8]</entry> 601 </row> 602 <row> 603 <entry>16</entry> 604 <entry>[16, 32, 48, 64, 80, 96, 112, 128]</entry> 605 </row> 606 <row> 607 <entry>32</entry> 608 <entry>[160, 192, 224, 256]</entry> 609 </row> 610 <row> 611 <entry>64</entry> 612 <entry>[320, 384, 448, 512]</entry> 613 </row> 614 <row> 615 <entry>128</entry> 616 <entry>[640, 768, 896, 1024]</entry> 617 </row> 618 <row> 619 <entry>256</entry> 620 <entry>[1280, 1536, 1792, 2048]</entry> 621 </row> 622 <row> 623 <entry>512</entry> 624 <entry>[2560, 3072, 3584, 4096]</entry> 625 </row> 626 <row> 627 <entry>1 KiB</entry> 628 <entry>[5 KiB, 6 KiB, 7 KiB, 8 KiB]</entry> 629 </row> 630 <row> 631 <entry>2 KiB</entry> 632 <entry>[10 KiB, 12 KiB, 14 KiB]</entry> 633 </row> 634 <row> 635 <entry morerows="15">Large</entry> 636 <entry>2 KiB</entry> 637 <entry>[16 KiB]</entry> 638 </row> 639 <row> 640 <entry>4 KiB</entry> 641 <entry>[20 KiB, 24 KiB, 28 KiB, 32 KiB]</entry> 642 </row> 643 <row> 644 <entry>8 KiB</entry> 645 <entry>[40 KiB, 48 KiB, 56 KiB, 64 KiB]</entry> 646 </row> 647 <row> 648 <entry>16 KiB</entry> 649 <entry>[80 KiB, 96 KiB, 112 KiB, 128 KiB]</entry> 650 </row> 651 <row> 652 <entry>32 KiB</entry> 653 <entry>[160 KiB, 192 KiB, 224 KiB, 256 KiB]</entry> 654 </row> 655 <row> 656 <entry>64 KiB</entry> 657 <entry>[320 KiB, 384 KiB, 448 KiB, 512 KiB]</entry> 658 </row> 659 <row> 660 <entry>128 KiB</entry> 661 <entry>[640 KiB, 768 KiB, 896 KiB, 1 MiB]</entry> 662 </row> 663 <row> 664 <entry>256 KiB</entry> 665 <entry>[1280 KiB, 1536 KiB, 1792 KiB, 2 MiB]</entry> 666 </row> 667 <row> 668 <entry>512 KiB</entry> 669 <entry>[2560 KiB, 3 MiB, 3584 KiB, 4 MiB]</entry> 670 </row> 671 <row> 672 <entry>1 MiB</entry> 673 <entry>[5 MiB, 6 MiB, 7 MiB, 8 MiB]</entry> 674 </row> 675 <row> 676 <entry>2 MiB</entry> 677 <entry>[10 MiB, 12 MiB, 14 MiB, 16 MiB]</entry> 678 </row> 679 <row> 680 <entry>4 MiB</entry> 681 <entry>[20 MiB, 24 MiB, 28 MiB, 32 MiB]</entry> 682 </row> 683 <row> 684 <entry>8 MiB</entry> 685 <entry>[40 MiB, 48 MiB, 56 MiB, 64 MiB]</entry> 686 </row> 687 <row> 688 <entry>...</entry> 689 <entry>...</entry> 690 </row> 691 <row> 692 <entry>512 PiB</entry> 693 <entry>[2560 PiB, 3 EiB, 3584 PiB, 4 EiB]</entry> 694 </row> 695 <row> 696 <entry>1 EiB</entry> 697 <entry>[5 EiB, 6 EiB, 7 EiB]</entry> 698 </row> 699 </tbody> 700 </tgroup> 701 </table> 702 </refsect1> 703 <refsect1 id="mallctl_namespace"> 704 <title>MALLCTL NAMESPACE</title> 705 <para>The following names are defined in the namespace accessible via the 706 <function>mallctl*()</function> functions. Value types are specified in 707 parentheses, their readable/writable statuses are encoded as 708 <literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or 709 <literal>--</literal>, and required build configuration flags follow, if 710 any. A name element encoded as <literal><i></literal> or 711 <literal><j></literal> indicates an integer component, where the 712 integer varies from 0 to some upper value that must be determined via 713 introspection. In the case of <mallctl>stats.arenas.<i>.*</mallctl> 714 and <mallctl>arena.<i>.{initialized,purge,decay,dss}</mallctl>, 715 <literal><i></literal> equal to 716 <constant>MALLCTL_ARENAS_ALL</constant> can be used to operate on all arenas 717 or access the summation of statistics from all arenas; similarly 718 <literal><i></literal> equal to 719 <constant>MALLCTL_ARENAS_DESTROYED</constant> can be used to access the 720 summation of statistics from all destroyed arenas. These constants can be 721 utilized either via <function>mallctlnametomib()</function> followed by 722 <function>mallctlbymib()</function>, or via code such as the following: 723 <programlisting language="C"><![CDATA[ 724#define STRINGIFY_HELPER(x) #x 725#define STRINGIFY(x) STRINGIFY_HELPER(x) 726 727mallctl("arena." STRINGIFY(MALLCTL_ARENAS_ALL) ".decay", 728 NULL, NULL, NULL, 0);]]></programlisting> 729 Take special note of the <link 730 linkend="epoch"><mallctl>epoch</mallctl></link> mallctl, which controls 731 refreshing of cached dynamic statistics.</para> 732 733 <variablelist> 734 <varlistentry id="version"> 735 <term> 736 <mallctl>version</mallctl> 737 (<type>const char *</type>) 738 <literal>r-</literal> 739 </term> 740 <listitem><para>Return the jemalloc version string.</para></listitem> 741 </varlistentry> 742 743 <varlistentry id="epoch"> 744 <term> 745 <mallctl>epoch</mallctl> 746 (<type>uint64_t</type>) 747 <literal>rw</literal> 748 </term> 749 <listitem><para>If a value is passed in, refresh the data from which 750 the <function>mallctl*()</function> functions report values, 751 and increment the epoch. Return the current epoch. This is useful for 752 detecting whether another thread caused a refresh.</para></listitem> 753 </varlistentry> 754 755 <varlistentry id="background_thread"> 756 <term> 757 <mallctl>background_thread</mallctl> 758 (<type>bool</type>) 759 <literal>rw</literal> 760 </term> 761 <listitem><para>Enable/disable internal background worker threads. When 762 set to true, background threads are created on demand (the number of 763 background threads will be no more than the number of CPUs or active 764 arenas). Threads run periodically, and handle <link 765 linkend="arena.i.decay">purging</link> asynchronously. When switching 766 off, background threads are terminated synchronously. Note that after 767 <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry> 768 function, the state in the child process will be disabled regardless 769 the state in parent process. See <link 770 linkend="stats.background_thread.num_threads"><mallctl>stats.background_thread</mallctl></link> 771 for related stats. <link 772 linkend="opt.background_thread"><mallctl>opt.background_thread</mallctl></link> 773 can be used to set the default option. This option is only available on 774 selected pthread-based platforms.</para></listitem> 775 </varlistentry> 776 777 <varlistentry id="max_background_threads"> 778 <term> 779 <mallctl>max_background_threads</mallctl> 780 (<type>size_t</type>) 781 <literal>rw</literal> 782 </term> 783 <listitem><para>Maximum number of background worker threads that will 784 be created. This value is capped at <link 785 linkend="opt.max_background_threads"><mallctl>opt.max_background_threads</mallctl></link> at 786 startup.</para></listitem> 787 </varlistentry> 788 789 <varlistentry id="config.cache_oblivious"> 790 <term> 791 <mallctl>config.cache_oblivious</mallctl> 792 (<type>bool</type>) 793 <literal>r-</literal> 794 </term> 795 <listitem><para><option>--enable-cache-oblivious</option> was specified 796 during build configuration.</para></listitem> 797 </varlistentry> 798 799 <varlistentry id="config.debug"> 800 <term> 801 <mallctl>config.debug</mallctl> 802 (<type>bool</type>) 803 <literal>r-</literal> 804 </term> 805 <listitem><para><option>--enable-debug</option> was specified during 806 build configuration.</para></listitem> 807 </varlistentry> 808 809 <varlistentry id="config.fill"> 810 <term> 811 <mallctl>config.fill</mallctl> 812 (<type>bool</type>) 813 <literal>r-</literal> 814 </term> 815 <listitem><para><option>--enable-fill</option> was specified during 816 build configuration.</para></listitem> 817 </varlistentry> 818 819 <varlistentry id="config.lazy_lock"> 820 <term> 821 <mallctl>config.lazy_lock</mallctl> 822 (<type>bool</type>) 823 <literal>r-</literal> 824 </term> 825 <listitem><para><option>--enable-lazy-lock</option> was specified 826 during build configuration.</para></listitem> 827 </varlistentry> 828 829 <varlistentry id="config.malloc_conf"> 830 <term> 831 <mallctl>config.malloc_conf</mallctl> 832 (<type>const char *</type>) 833 <literal>r-</literal> 834 </term> 835 <listitem><para>Embedded configure-time-specified run-time options 836 string, empty unless <option>--with-malloc-conf</option> was specified 837 during build configuration.</para></listitem> 838 </varlistentry> 839 840 <varlistentry id="config.prof"> 841 <term> 842 <mallctl>config.prof</mallctl> 843 (<type>bool</type>) 844 <literal>r-</literal> 845 </term> 846 <listitem><para><option>--enable-prof</option> was specified during 847 build configuration.</para></listitem> 848 </varlistentry> 849 850 <varlistentry id="config.prof_libgcc"> 851 <term> 852 <mallctl>config.prof_libgcc</mallctl> 853 (<type>bool</type>) 854 <literal>r-</literal> 855 </term> 856 <listitem><para><option>--disable-prof-libgcc</option> was not 857 specified during build configuration.</para></listitem> 858 </varlistentry> 859 860 <varlistentry id="config.prof_libunwind"> 861 <term> 862 <mallctl>config.prof_libunwind</mallctl> 863 (<type>bool</type>) 864 <literal>r-</literal> 865 </term> 866 <listitem><para><option>--enable-prof-libunwind</option> was specified 867 during build configuration.</para></listitem> 868 </varlistentry> 869 870 <varlistentry id="config.stats"> 871 <term> 872 <mallctl>config.stats</mallctl> 873 (<type>bool</type>) 874 <literal>r-</literal> 875 </term> 876 <listitem><para><option>--enable-stats</option> was specified during 877 build configuration.</para></listitem> 878 </varlistentry> 879 880 881 <varlistentry id="config.utrace"> 882 <term> 883 <mallctl>config.utrace</mallctl> 884 (<type>bool</type>) 885 <literal>r-</literal> 886 </term> 887 <listitem><para><option>--enable-utrace</option> was specified during 888 build configuration.</para></listitem> 889 </varlistentry> 890 891 <varlistentry id="config.xmalloc"> 892 <term> 893 <mallctl>config.xmalloc</mallctl> 894 (<type>bool</type>) 895 <literal>r-</literal> 896 </term> 897 <listitem><para><option>--enable-xmalloc</option> was specified during 898 build configuration.</para></listitem> 899 </varlistentry> 900 901 <varlistentry id="opt.abort"> 902 <term> 903 <mallctl>opt.abort</mallctl> 904 (<type>bool</type>) 905 <literal>r-</literal> 906 </term> 907 <listitem><para>Abort-on-warning enabled/disabled. If true, most 908 warnings are fatal. Note that runtime option warnings are not included 909 (see <link 910 linkend="opt.abort_conf"><mallctl>opt.abort_conf</mallctl></link> for 911 that). The process will call 912 <citerefentry><refentrytitle>abort</refentrytitle> 913 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 914 disabled by default unless <option>--enable-debug</option> is 915 specified during configuration, in which case it is enabled by default. 916 </para></listitem> 917 </varlistentry> 918 919 <varlistentry id="opt.confirm_conf"> 920 <term> 921 <mallctl>opt.confirm_conf</mallctl> 922 (<type>bool</type>) 923 <literal>r-</literal> 924 </term> 925 <listitem><para>Confirm-runtime-options-when-program-starts 926 enabled/disabled. If true, the string specified via 927 <option>--with-malloc-conf</option>, the string pointed to by the 928 global variable <varname>malloc_conf</varname>, the <quote>name</quote> 929 of the file referenced by the symbolic link named 930 <filename class="symlink">/etc/malloc.conf</filename>, and the value of 931 the environment variable <envar>MALLOC_CONF</envar>, will be printed in 932 order. Then, each option being set will be individually printed. This 933 option is disabled by default.</para></listitem> 934 </varlistentry> 935 936 <varlistentry id="opt.abort_conf"> 937 <term> 938 <mallctl>opt.abort_conf</mallctl> 939 (<type>bool</type>) 940 <literal>r-</literal> 941 </term> 942 <listitem><para>Abort-on-invalid-configuration enabled/disabled. If 943 true, invalid runtime options are fatal. The process will call 944 <citerefentry><refentrytitle>abort</refentrytitle> 945 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 946 disabled by default unless <option>--enable-debug</option> is 947 specified during configuration, in which case it is enabled by default. 948 </para></listitem> 949 </varlistentry> 950 951 <varlistentry id="opt.cache_oblivious"> 952 <term> 953 <mallctl>opt.cache_oblivious</mallctl> 954 (<type>bool</type>) 955 <literal>r-</literal> 956 </term> 957 <listitem><para>Enable / Disable cache-oblivious large allocation 958 alignment, for large requests with no alignment constraints. If this 959 feature is disabled, all large allocations are page-aligned as an 960 implementation artifact, which can severely harm CPU cache utilization. 961 However, the cache-oblivious layout comes at the cost of one extra page 962 per large allocation, which in the most extreme case increases physical 963 memory usage for the 16 KiB size class to 20 KiB. This option is enabled 964 by default.</para></listitem> 965 </varlistentry> 966 967 <varlistentry id="opt.metadata_thp"> 968 <term> 969 <mallctl>opt.metadata_thp</mallctl> 970 (<type>const char *</type>) 971 <literal>r-</literal> 972 </term> 973 <listitem><para>Controls whether to allow jemalloc to use transparent 974 huge page (THP) for internal metadata (see <link 975 linkend="stats.metadata">stats.metadata</link>). <quote>always</quote> 976 allows such usage. <quote>auto</quote> uses no THP initially, but may 977 begin to do so when metadata usage reaches certain level. The default 978 is <quote>disabled</quote>.</para></listitem> 979 </varlistentry> 980 981 <varlistentry id="opt.trust_madvise"> 982 <term> 983 <mallctl>opt.trust_madvise</mallctl> 984 (<type>bool</type>) 985 <literal>r-</literal> 986 </term> 987 <listitem><para>If true, do not perform runtime check for MADV_DONTNEED, 988 to check that it actually zeros pages. The default is disabled on Linux 989 and enabled elsewhere.</para></listitem> 990 </varlistentry> 991 992 <varlistentry id="opt.retain"> 993 <term> 994 <mallctl>opt.retain</mallctl> 995 (<type>bool</type>) 996 <literal>r-</literal> 997 </term> 998 <listitem><para>If true, retain unused virtual memory for later reuse 999 rather than discarding it by calling 1000 <citerefentry><refentrytitle>munmap</refentrytitle> 1001 <manvolnum>2</manvolnum></citerefentry> or equivalent (see <link 1002 linkend="stats.retained">stats.retained</link> for related details). 1003 It also makes jemalloc use <citerefentry> 1004 <refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum> 1005 </citerefentry> or equivalent in a more greedy way, mapping larger 1006 chunks in one go. This option is disabled by default unless discarding 1007 virtual memory is known to trigger platform-specific performance 1008 problems, namely 1) for [64-bit] Linux, which has a quirk in its virtual 1009 memory allocation algorithm that causes semi-permanent VM map holes 1010 under normal jemalloc operation; and 2) for [64-bit] Windows, which 1011 disallows split / merged regions with 1012 <parameter><constant>MEM_RELEASE</constant></parameter>. Although the 1013 same issues may present on 32-bit platforms as well, retaining virtual 1014 memory for 32-bit Linux and Windows is disabled by default due to the 1015 practical possibility of address space exhaustion. </para></listitem> 1016 </varlistentry> 1017 1018 <varlistentry id="opt.dss"> 1019 <term> 1020 <mallctl>opt.dss</mallctl> 1021 (<type>const char *</type>) 1022 <literal>r-</literal> 1023 </term> 1024 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 1025 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 1026 related to <citerefentry><refentrytitle>mmap</refentrytitle> 1027 <manvolnum>2</manvolnum></citerefentry> allocation. The following 1028 settings are supported if 1029 <citerefentry><refentrytitle>sbrk</refentrytitle> 1030 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 1031 system: <quote>disabled</quote>, <quote>primary</quote>, and 1032 <quote>secondary</quote>; otherwise only <quote>disabled</quote> is 1033 supported. The default is <quote>secondary</quote> if 1034 <citerefentry><refentrytitle>sbrk</refentrytitle> 1035 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 1036 system; <quote>disabled</quote> otherwise. 1037 </para></listitem> 1038 </varlistentry> 1039 1040 <varlistentry id="opt.narenas"> 1041 <term> 1042 <mallctl>opt.narenas</mallctl> 1043 (<type>unsigned</type>) 1044 <literal>r-</literal> 1045 </term> 1046 <listitem><para>Maximum number of arenas to use for automatic 1047 multiplexing of threads and arenas. The default is four times the 1048 number of CPUs, or one if there is a single CPU.</para></listitem> 1049 </varlistentry> 1050 1051 <varlistentry id="opt.oversize_threshold"> 1052 <term> 1053 <mallctl>opt.oversize_threshold</mallctl> 1054 (<type>size_t</type>) 1055 <literal>r-</literal> 1056 </term> 1057 <listitem><para>The threshold in bytes of which requests are considered 1058 oversize. Allocation requests with greater sizes are fulfilled from a 1059 dedicated arena (automatically managed, however not within 1060 <literal>narenas</literal>), in order to reduce fragmentation by not 1061 mixing huge allocations with small ones. In addition, the decay API 1062 guarantees on the extents greater than the specified threshold may be 1063 overridden. Note that requests with arena index specified via 1064 <constant>MALLOCX_ARENA</constant>, or threads associated with explicit 1065 arenas will not be considered. The default threshold is 8MiB. Values 1066 not within large size classes disables this feature.</para></listitem> 1067 </varlistentry> 1068 1069 <varlistentry id="opt.percpu_arena"> 1070 <term> 1071 <mallctl>opt.percpu_arena</mallctl> 1072 (<type>const char *</type>) 1073 <literal>r-</literal> 1074 </term> 1075 <listitem><para>Per CPU arena mode. Use the <quote>percpu</quote> 1076 setting to enable this feature, which uses number of CPUs to determine 1077 number of arenas, and bind threads to arenas dynamically based on the 1078 CPU the thread runs on currently. <quote>phycpu</quote> setting uses 1079 one arena per physical CPU, which means the two hyper threads on the 1080 same CPU share one arena. Note that no runtime checking regarding the 1081 availability of hyper threading is done at the moment. When set to 1082 <quote>disabled</quote>, narenas and thread to arena association will 1083 not be impacted by this option. The default is <quote>disabled</quote>. 1084 </para></listitem> 1085 </varlistentry> 1086 1087 <varlistentry id="opt.background_thread"> 1088 <term> 1089 <mallctl>opt.background_thread</mallctl> 1090 (<type>bool</type>) 1091 <literal>r-</literal> 1092 </term> 1093 <listitem><para>Internal background worker threads enabled/disabled. 1094 Because of potential circular dependencies, enabling background thread 1095 using this option may cause crash or deadlock during initialization. For 1096 a reliable way to use this feature, see <link 1097 linkend="background_thread">background_thread</link> for dynamic control 1098 options and details. This option is disabled by 1099 default.</para></listitem> 1100 </varlistentry> 1101 1102 <varlistentry id="opt.max_background_threads"> 1103 <term> 1104 <mallctl>opt.max_background_threads</mallctl> 1105 (<type>size_t</type>) 1106 <literal>r-</literal> 1107 </term> 1108 <listitem><para>Maximum number of background threads that will be created 1109 if <link linkend="background_thread">background_thread</link> is set. 1110 Defaults to number of cpus.</para></listitem> 1111 </varlistentry> 1112 1113 <varlistentry id="opt.dirty_decay_ms"> 1114 <term> 1115 <mallctl>opt.dirty_decay_ms</mallctl> 1116 (<type>ssize_t</type>) 1117 <literal>r-</literal> 1118 </term> 1119 <listitem><para>Approximate time in milliseconds from the creation of a 1120 set of unused dirty pages until an equivalent set of unused dirty pages 1121 is purged (i.e. converted to muzzy via e.g. 1122 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function> 1123 if supported by the operating system, or converted to clean otherwise) 1124 and/or reused. Dirty pages are defined as previously having been 1125 potentially written to by the application, and therefore consuming 1126 physical memory, yet having no current use. The pages are incrementally 1127 purged according to a sigmoidal decay curve that starts and ends with 1128 zero purge rate. A decay time of 0 causes all unused dirty pages to be 1129 purged immediately upon creation. A decay time of -1 disables purging. 1130 The default decay time is 10 seconds. See <link 1131 linkend="arenas.dirty_decay_ms"><mallctl>arenas.dirty_decay_ms</mallctl></link> 1132 and <link 1133 linkend="arena.i.dirty_decay_ms"><mallctl>arena.<i>.dirty_decay_ms</mallctl></link> 1134 for related dynamic control options. See <link 1135 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 1136 for a description of muzzy pages.for a description of muzzy pages. Note 1137 that when the <link 1138 linkend="opt.oversize_threshold"><mallctl>oversize_threshold</mallctl></link> 1139 feature is enabled, the arenas reserved for oversize requests may have 1140 its own default decay settings.</para></listitem> 1141 </varlistentry> 1142 1143 <varlistentry id="opt.muzzy_decay_ms"> 1144 <term> 1145 <mallctl>opt.muzzy_decay_ms</mallctl> 1146 (<type>ssize_t</type>) 1147 <literal>r-</literal> 1148 </term> 1149 <listitem><para>Approximate time in milliseconds from the creation of a 1150 set of unused muzzy pages until an equivalent set of unused muzzy pages 1151 is purged (i.e. converted to clean) and/or reused. Muzzy pages are 1152 defined as previously having been unused dirty pages that were 1153 subsequently purged in a manner that left them subject to the 1154 reclamation whims of the operating system (e.g. 1155 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function>), 1156 and therefore in an indeterminate state. The pages are incrementally 1157 purged according to a sigmoidal decay curve that starts and ends with 1158 zero purge rate. A decay time of 0 causes all unused muzzy pages to be 1159 purged immediately upon creation. A decay time of -1 disables purging. 1160 The default decay time is 10 seconds. See <link 1161 linkend="arenas.muzzy_decay_ms"><mallctl>arenas.muzzy_decay_ms</mallctl></link> 1162 and <link 1163 linkend="arena.i.muzzy_decay_ms"><mallctl>arena.<i>.muzzy_decay_ms</mallctl></link> 1164 for related dynamic control options.</para></listitem> 1165 </varlistentry> 1166 1167 <varlistentry id="opt.lg_extent_max_active_fit"> 1168 <term> 1169 <mallctl>opt.lg_extent_max_active_fit</mallctl> 1170 (<type>size_t</type>) 1171 <literal>r-</literal> 1172 </term> 1173 <listitem><para>When reusing dirty extents, this determines the (log 1174 base 2 of the) maximum ratio between the size of the active extent 1175 selected (to split off from) and the size of the requested allocation. 1176 This prevents the splitting of large active extents for smaller 1177 allocations, which can reduce fragmentation over the long run 1178 (especially for non-active extents). Lower value may reduce 1179 fragmentation, at the cost of extra active extents. The default value 1180 is 6, which gives a maximum ratio of 64 (2^6).</para></listitem> 1181 </varlistentry> 1182 1183 <varlistentry id="opt.stats_print"> 1184 <term> 1185 <mallctl>opt.stats_print</mallctl> 1186 (<type>bool</type>) 1187 <literal>r-</literal> 1188 </term> 1189 <listitem><para>Enable/disable statistics printing at exit. If 1190 enabled, the <function>malloc_stats_print()</function> 1191 function is called at program exit via an 1192 <citerefentry><refentrytitle>atexit</refentrytitle> 1193 <manvolnum>3</manvolnum></citerefentry> function. <link 1194 linkend="opt.stats_print_opts"><mallctl>opt.stats_print_opts</mallctl></link> 1195 can be combined to specify output options. If 1196 <option>--enable-stats</option> is specified during configuration, this 1197 has the potential to cause deadlock for a multi-threaded process that 1198 exits while one or more threads are executing in the memory allocation 1199 functions. Furthermore, <function>atexit()</function> may 1200 allocate memory during application initialization and then deadlock 1201 internally when jemalloc in turn calls 1202 <function>atexit()</function>, so this option is not 1203 universally usable (though the application can register its own 1204 <function>atexit()</function> function with equivalent 1205 functionality). Therefore, this option should only be used with care; 1206 it is primarily intended as a performance tuning aid during application 1207 development. This option is disabled by default.</para></listitem> 1208 </varlistentry> 1209 1210 <varlistentry id="opt.stats_print_opts"> 1211 <term> 1212 <mallctl>opt.stats_print_opts</mallctl> 1213 (<type>const char *</type>) 1214 <literal>r-</literal> 1215 </term> 1216 <listitem><para>Options (the <parameter>opts</parameter> string) to pass 1217 to the <function>malloc_stats_print()</function> at exit (enabled 1218 through <link 1219 linkend="opt.stats_print"><mallctl>opt.stats_print</mallctl></link>). See 1220 available options in <link 1221 linkend="malloc_stats_print_opts"><function>malloc_stats_print()</function></link>. 1222 Has no effect unless <link 1223 linkend="opt.stats_print"><mallctl>opt.stats_print</mallctl></link> is 1224 enabled. The default is <quote></quote>.</para></listitem> 1225 </varlistentry> 1226 1227 <varlistentry id="opt.stats_interval"> 1228 <term> 1229 <mallctl>opt.stats_interval</mallctl> 1230 (<type>int64_t</type>) 1231 <literal>r-</literal> 1232 </term> 1233 <listitem><para>Average interval between statistics outputs, as measured 1234 in bytes of allocation activity. The actual interval may be sporadic 1235 because decentralized event counters are used to avoid synchronization 1236 bottlenecks. The output may be triggered on any thread, which then 1237 calls <function>malloc_stats_print()</function>. <link 1238 linkend="opt.stats_interval_opts"><mallctl>opt.stats_interval_opts</mallctl></link> 1239 can be combined to specify output options. By default, 1240 interval-triggered stats output is disabled (encoded as 1241 -1).</para></listitem> 1242 </varlistentry> 1243 1244 <varlistentry id="opt.stats_interval_opts"> 1245 <term> 1246 <mallctl>opt.stats_interval_opts</mallctl> 1247 (<type>const char *</type>) 1248 <literal>r-</literal> 1249 </term> 1250 <listitem><para>Options (the <parameter>opts</parameter> string) to pass 1251 to the <function>malloc_stats_print()</function> for interval based 1252 statistics printing (enabled 1253 through <link 1254 linkend="opt.stats_interval"><mallctl>opt.stats_interval</mallctl></link>). See 1255 available options in <link 1256 linkend="malloc_stats_print_opts"><function>malloc_stats_print()</function></link>. 1257 Has no effect unless <link 1258 linkend="opt.stats_interval"><mallctl>opt.stats_interval</mallctl></link> is 1259 enabled. The default is <quote></quote>.</para></listitem> 1260 </varlistentry> 1261 1262 <varlistentry id="opt.junk"> 1263 <term> 1264 <mallctl>opt.junk</mallctl> 1265 (<type>const char *</type>) 1266 <literal>r-</literal> 1267 [<option>--enable-fill</option>] 1268 </term> 1269 <listitem><para>Junk filling. If set to <quote>alloc</quote>, each byte 1270 of uninitialized allocated memory will be initialized to 1271 <literal>0xa5</literal>. If set to <quote>free</quote>, all deallocated 1272 memory will be initialized to <literal>0x5a</literal>. If set to 1273 <quote>true</quote>, both allocated and deallocated memory will be 1274 initialized, and if set to <quote>false</quote>, junk filling be 1275 disabled entirely. This is intended for debugging and will impact 1276 performance negatively. This option is <quote>false</quote> by default 1277 unless <option>--enable-debug</option> is specified during 1278 configuration, in which case it is <quote>true</quote> by 1279 default.</para></listitem> 1280 </varlistentry> 1281 1282 <varlistentry id="opt.zero"> 1283 <term> 1284 <mallctl>opt.zero</mallctl> 1285 (<type>bool</type>) 1286 <literal>r-</literal> 1287 [<option>--enable-fill</option>] 1288 </term> 1289 <listitem><para>Zero filling enabled/disabled. If enabled, each byte 1290 of uninitialized allocated memory will be initialized to 0. Note that 1291 this initialization only happens once for each byte, so 1292 <function>realloc()</function> and 1293 <function>rallocx()</function> calls do not zero memory that 1294 was previously allocated. This is intended for debugging and will 1295 impact performance negatively. This option is disabled by default. 1296 </para></listitem> 1297 </varlistentry> 1298 1299 <varlistentry id="opt.utrace"> 1300 <term> 1301 <mallctl>opt.utrace</mallctl> 1302 (<type>bool</type>) 1303 <literal>r-</literal> 1304 [<option>--enable-utrace</option>] 1305 </term> 1306 <listitem><para>Allocation tracing based on 1307 <citerefentry><refentrytitle>utrace</refentrytitle> 1308 <manvolnum>2</manvolnum></citerefentry> enabled/disabled. This option 1309 is disabled by default.</para></listitem> 1310 </varlistentry> 1311 1312 <varlistentry id="opt.xmalloc"> 1313 <term> 1314 <mallctl>opt.xmalloc</mallctl> 1315 (<type>bool</type>) 1316 <literal>r-</literal> 1317 [<option>--enable-xmalloc</option>] 1318 </term> 1319 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled, 1320 rather than returning failure for any allocation function, display a 1321 diagnostic message on <constant>STDERR_FILENO</constant> and cause the 1322 program to drop core (using 1323 <citerefentry><refentrytitle>abort</refentrytitle> 1324 <manvolnum>3</manvolnum></citerefentry>). If an application is 1325 designed to depend on this behavior, set the option at compile time by 1326 including the following in the source code: 1327 <programlisting language="C"><![CDATA[ 1328malloc_conf = "xmalloc:true";]]></programlisting> 1329 This option is disabled by default.</para></listitem> 1330 </varlistentry> 1331 1332 <varlistentry id="opt.tcache"> 1333 <term> 1334 <mallctl>opt.tcache</mallctl> 1335 (<type>bool</type>) 1336 <literal>r-</literal> 1337 </term> 1338 <listitem><para>Thread-specific caching (tcache) enabled/disabled. When 1339 there are multiple threads, each thread uses a tcache for objects up to 1340 a certain size. Thread-specific caching allows many allocations to be 1341 satisfied without performing any thread synchronization, at the cost of 1342 increased memory use. See the <link 1343 linkend="opt.tcache_max"><mallctl>opt.tcache_max</mallctl></link> 1344 option for related tuning information. This option is enabled by 1345 default.</para></listitem> 1346 </varlistentry> 1347 1348 <varlistentry id="opt.tcache_max"> 1349 <term> 1350 <mallctl>opt.tcache_max</mallctl> 1351 (<type>size_t</type>) 1352 <literal>r-</literal> 1353 </term> 1354 <listitem><para>Maximum size class to cache in the thread-specific cache 1355 (tcache). At a minimum, the first size class is cached; and at a 1356 maximum, size classes up to 8 MiB can be cached. The default maximum is 1357 32 KiB (2^15). As a convenience, this may also be set by specifying 1358 lg_tcache_max, which will be taken to be the base-2 logarithm of the 1359 setting of tcache_max.</para></listitem> 1360 </varlistentry> 1361 1362 <varlistentry id="opt.thp"> 1363 <term> 1364 <mallctl>opt.thp</mallctl> 1365 (<type>const char *</type>) 1366 <literal>r-</literal> 1367 </term> 1368 <listitem><para>Transparent hugepage (THP) mode. Settings "always", 1369 "never" and "default" are available if THP is supported by the operating 1370 system. The "always" setting enables transparent hugepage for all user 1371 memory mappings with 1372 <parameter><constant>MADV_HUGEPAGE</constant></parameter>; "never" 1373 ensures no transparent hugepage with 1374 <parameter><constant>MADV_NOHUGEPAGE</constant></parameter>; the default 1375 setting "default" makes no changes. Note that: this option does not 1376 affect THP for jemalloc internal metadata (see <link 1377 linkend="opt.metadata_thp"><mallctl>opt.metadata_thp</mallctl></link>); 1378 in addition, for arenas with customized <link 1379 linkend="arena.i.extent_hooks"><mallctl>extent_hooks</mallctl></link>, 1380 this option is bypassed as it is implemented as part of the default 1381 extent hooks.</para></listitem> 1382 </varlistentry> 1383 1384 <varlistentry id="opt.prof"> 1385 <term> 1386 <mallctl>opt.prof</mallctl> 1387 (<type>bool</type>) 1388 <literal>r-</literal> 1389 [<option>--enable-prof</option>] 1390 </term> 1391 <listitem><para>Memory profiling enabled/disabled. If enabled, profile 1392 memory allocation activity. See the <link 1393 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 1394 option for on-the-fly activation/deactivation. See the <link 1395 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 1396 option for probabilistic sampling control. See the <link 1397 linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> 1398 option for control of cumulative sample reporting. See the <link 1399 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 1400 option for information on interval-triggered profile dumping, the <link 1401 linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link> 1402 option for information on high-water-triggered profile dumping, and the 1403 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link> 1404 option for final profile dumping. Profile output is compatible with 1405 the <command>jeprof</command> command, which is based on the 1406 <command>pprof</command> that is developed as part of the <ulink 1407 url="http://code.google.com/p/gperftools/">gperftools 1408 package</ulink>. See <link linkend="heap_profile_format">HEAP PROFILE 1409 FORMAT</link> for heap profile format documentation.</para></listitem> 1410 </varlistentry> 1411 1412 <varlistentry id="opt.prof_prefix"> 1413 <term> 1414 <mallctl>opt.prof_prefix</mallctl> 1415 (<type>const char *</type>) 1416 <literal>r-</literal> 1417 [<option>--enable-prof</option>] 1418 </term> 1419 <listitem><para>Filename prefix for profile dumps. If the prefix is 1420 set to the empty string, no automatic dumps will occur; this is 1421 primarily useful for disabling the automatic final heap dump (which 1422 also disables leak reporting, if enabled). The default prefix is 1423 <filename>jeprof</filename>. This prefix value can be overridden by 1424 <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link>. 1425 </para></listitem> 1426 </varlistentry> 1427 1428 <varlistentry id="opt.prof_active"> 1429 <term> 1430 <mallctl>opt.prof_active</mallctl> 1431 (<type>bool</type>) 1432 <literal>r-</literal> 1433 [<option>--enable-prof</option>] 1434 </term> 1435 <listitem><para>Profiling activated/deactivated. This is a secondary 1436 control mechanism that makes it possible to start the application with 1437 profiling enabled (see the <link 1438 linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but 1439 inactive, then toggle profiling at any time during program execution 1440 with the <link 1441 linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl. 1442 This option is enabled by default.</para></listitem> 1443 </varlistentry> 1444 1445 <varlistentry id="opt.prof_thread_active_init"> 1446 <term> 1447 <mallctl>opt.prof_thread_active_init</mallctl> 1448 (<type>bool</type>) 1449 <literal>r-</literal> 1450 [<option>--enable-prof</option>] 1451 </term> 1452 <listitem><para>Initial setting for <link 1453 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 1454 in newly created threads. The initial setting for newly created threads 1455 can also be changed during execution via the <link 1456 linkend="prof.thread_active_init"><mallctl>prof.thread_active_init</mallctl></link> 1457 mallctl. This option is enabled by default.</para></listitem> 1458 </varlistentry> 1459 1460 <varlistentry id="opt.lg_prof_sample"> 1461 <term> 1462 <mallctl>opt.lg_prof_sample</mallctl> 1463 (<type>size_t</type>) 1464 <literal>r-</literal> 1465 [<option>--enable-prof</option>] 1466 </term> 1467 <listitem><para>Average interval (log base 2) between allocation 1468 samples, as measured in bytes of allocation activity. Increasing the 1469 sampling interval decreases profile fidelity, but also decreases the 1470 computational overhead. The default sample interval is 512 KiB (2^19 1471 B).</para></listitem> 1472 </varlistentry> 1473 1474 <varlistentry id="opt.prof_accum"> 1475 <term> 1476 <mallctl>opt.prof_accum</mallctl> 1477 (<type>bool</type>) 1478 <literal>r-</literal> 1479 [<option>--enable-prof</option>] 1480 </term> 1481 <listitem><para>Reporting of cumulative object/byte counts in profile 1482 dumps enabled/disabled. If this option is enabled, every unique 1483 backtrace must be stored for the duration of execution. Depending on 1484 the application, this can impose a large memory overhead, and the 1485 cumulative counts are not always of interest. This option is disabled 1486 by default.</para></listitem> 1487 </varlistentry> 1488 1489 <varlistentry id="opt.lg_prof_interval"> 1490 <term> 1491 <mallctl>opt.lg_prof_interval</mallctl> 1492 (<type>ssize_t</type>) 1493 <literal>r-</literal> 1494 [<option>--enable-prof</option>] 1495 </term> 1496 <listitem><para>Average interval (log base 2) between memory profile 1497 dumps, as measured in bytes of allocation activity. The actual 1498 interval between dumps may be sporadic because decentralized allocation 1499 counters are used to avoid synchronization bottlenecks. Profiles are 1500 dumped to files named according to the pattern 1501 <filename><prefix>.<pid>.<seq>.i<iseq>.heap</filename>, 1502 where <literal><prefix></literal> is controlled by the 1503 <link 1504 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> and 1505 <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link> 1506 options. By default, interval-triggered profile dumping is disabled 1507 (encoded as -1). 1508 </para></listitem> 1509 </varlistentry> 1510 1511 <varlistentry id="opt.prof_gdump"> 1512 <term> 1513 <mallctl>opt.prof_gdump</mallctl> 1514 (<type>bool</type>) 1515 <literal>r-</literal> 1516 [<option>--enable-prof</option>] 1517 </term> 1518 <listitem><para>Set the initial state of <link 1519 linkend="prof.gdump"><mallctl>prof.gdump</mallctl></link>, which when 1520 enabled triggers a memory profile dump every time the total virtual 1521 memory exceeds the previous maximum. This option is disabled by 1522 default.</para></listitem> 1523 </varlistentry> 1524 1525 <varlistentry id="opt.prof_final"> 1526 <term> 1527 <mallctl>opt.prof_final</mallctl> 1528 (<type>bool</type>) 1529 <literal>r-</literal> 1530 [<option>--enable-prof</option>] 1531 </term> 1532 <listitem><para>Use an 1533 <citerefentry><refentrytitle>atexit</refentrytitle> 1534 <manvolnum>3</manvolnum></citerefentry> function to dump final memory 1535 usage to a file named according to the pattern 1536 <filename><prefix>.<pid>.<seq>.f.heap</filename>, 1537 where <literal><prefix></literal> is controlled by the <link 1538 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> and 1539 <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link> 1540 options. Note that <function>atexit()</function> may allocate 1541 memory during application initialization and then deadlock internally 1542 when jemalloc in turn calls <function>atexit()</function>, so 1543 this option is not universally usable (though the application can 1544 register its own <function>atexit()</function> function with 1545 equivalent functionality). This option is disabled by 1546 default.</para></listitem> 1547 </varlistentry> 1548 1549 <varlistentry id="opt.prof_leak"> 1550 <term> 1551 <mallctl>opt.prof_leak</mallctl> 1552 (<type>bool</type>) 1553 <literal>r-</literal> 1554 [<option>--enable-prof</option>] 1555 </term> 1556 <listitem><para>Leak reporting enabled/disabled. If enabled, use an 1557 <citerefentry><refentrytitle>atexit</refentrytitle> 1558 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks 1559 detected by allocation sampling. See the 1560 <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for 1561 information on analyzing heap profile output. Works only when combined 1562 with <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl> 1563 </link>, otherwise does nothing. This option is disabled by default. 1564 </para></listitem> 1565 </varlistentry> 1566 1567 <varlistentry id="opt.prof_leak_error"> 1568 <term> 1569 <mallctl>opt.prof_leak_error</mallctl> 1570 (<type>bool</type>) 1571 <literal>r-</literal> 1572 [<option>--enable-prof</option>] 1573 </term> 1574 <listitem><para>Similar to <link linkend="opt.prof_leak"><mallctl> 1575 opt.prof_leak</mallctl></link>, but makes the process exit with error 1576 code 1 if a memory leak is detected. This option supersedes 1577 <link linkend="opt.prof_leak"><mallctl>opt.prof_leak</mallctl></link>, 1578 meaning that if both are specified, this option takes precedence. When 1579 enabled, also enables <link linkend="opt.prof_leak"><mallctl> 1580 opt.prof_leak</mallctl></link>. Works only when combined with 1581 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link>, 1582 otherwise does nothing. This option is disabled by default. 1583 </para></listitem> 1584 </varlistentry> 1585 1586 <varlistentry id="opt.zero_realloc"> 1587 <term> 1588 <mallctl>opt.zero_realloc</mallctl> 1589 (<type>const char *</type>) 1590 <literal>r-</literal> 1591 </term> 1592 <listitem><para> Determines the behavior of 1593 <function>realloc()</function> when passed a value of zero for the new 1594 size. <quote>alloc</quote> treats this as an allocation of size zero 1595 (and returns a non-null result except in case of resource exhaustion). 1596 <quote>free</quote> treats this as a deallocation of the pointer, and 1597 returns <constant>NULL</constant> without setting 1598 <varname>errno</varname>. <quote>abort</quote> aborts the process if 1599 zero is passed. The default is <quote>free</quote> on Linux and 1600 Windows, and <quote>alloc</quote> elsewhere.</para> 1601 1602 <para>There is considerable divergence of behaviors across 1603 implementations in handling this case. Many have the behavior of 1604 <quote>free</quote>. This can introduce security vulnerabilities, since 1605 a <constant>NULL</constant> return value indicates failure, and the 1606 continued validity of the passed-in pointer (per POSIX and C11). 1607 <quote>alloc</quote> is safe, but can cause leaks in programs that 1608 expect the common behavior. Programs intended to be portable and 1609 leak-free cannot assume either behavior, and must therefore never call 1610 realloc with a size of 0. The <quote>abort</quote> option enables these 1611 testing this behavior.</para></listitem> 1612 </varlistentry> 1613 1614 <varlistentry id="thread.arena"> 1615 <term> 1616 <mallctl>thread.arena</mallctl> 1617 (<type>unsigned</type>) 1618 <literal>rw</literal> 1619 </term> 1620 <listitem><para>Get or set the arena associated with the calling 1621 thread. If the specified arena was not initialized beforehand (see the 1622 <link 1623 linkend="arena.i.initialized"><mallctl>arena.i.initialized</mallctl></link> 1624 mallctl), it will be automatically initialized as a side effect of 1625 calling this interface.</para></listitem> 1626 </varlistentry> 1627 1628 <varlistentry id="thread.allocated"> 1629 <term> 1630 <mallctl>thread.allocated</mallctl> 1631 (<type>uint64_t</type>) 1632 <literal>r-</literal> 1633 [<option>--enable-stats</option>] 1634 </term> 1635 <listitem><para>Get the total number of bytes ever allocated by the 1636 calling thread. This counter has the potential to wrap around; it is 1637 up to the application to appropriately interpret the counter in such 1638 cases.</para></listitem> 1639 </varlistentry> 1640 1641 <varlistentry id="thread.allocatedp"> 1642 <term> 1643 <mallctl>thread.allocatedp</mallctl> 1644 (<type>uint64_t *</type>) 1645 <literal>r-</literal> 1646 [<option>--enable-stats</option>] 1647 </term> 1648 <listitem><para>Get a pointer to the the value that is returned by the 1649 <link 1650 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 1651 mallctl. This is useful for avoiding the overhead of repeated 1652 <function>mallctl*()</function> calls. Note that the underlying counter 1653 should not be modified by the application.</para></listitem> 1654 </varlistentry> 1655 1656 <varlistentry id="thread.deallocated"> 1657 <term> 1658 <mallctl>thread.deallocated</mallctl> 1659 (<type>uint64_t</type>) 1660 <literal>r-</literal> 1661 [<option>--enable-stats</option>] 1662 </term> 1663 <listitem><para>Get the total number of bytes ever deallocated by the 1664 calling thread. This counter has the potential to wrap around; it is 1665 up to the application to appropriately interpret the counter in such 1666 cases.</para></listitem> 1667 </varlistentry> 1668 1669 <varlistentry id="thread.deallocatedp"> 1670 <term> 1671 <mallctl>thread.deallocatedp</mallctl> 1672 (<type>uint64_t *</type>) 1673 <literal>r-</literal> 1674 [<option>--enable-stats</option>] 1675 </term> 1676 <listitem><para>Get a pointer to the the value that is returned by the 1677 <link 1678 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link> 1679 mallctl. This is useful for avoiding the overhead of repeated 1680 <function>mallctl*()</function> calls. Note that the underlying counter 1681 should not be modified by the application.</para></listitem> 1682 </varlistentry> 1683 1684 <varlistentry id="thread.peak.read"> 1685 <term> 1686 <mallctl>thread.peak.read</mallctl> 1687 (<type>uint64_t</type>) 1688 <literal>r-</literal> 1689 [<option>--enable-stats</option>] 1690 </term> 1691 <listitem><para>Get an approximation of the maximum value of the 1692 difference between the number of bytes allocated and the number of bytes 1693 deallocated by the calling thread since the last call to <link 1694 linkend="thread.peak.reset"><mallctl>thread.peak.reset</mallctl></link>, 1695 or since the thread's creation if it has not called <link 1696 linkend="thread.peak.reset"><mallctl>thread.peak.reset</mallctl></link>. 1697 No guarantees are made about the quality of the approximation, but 1698 jemalloc currently endeavors to maintain accuracy to within one hundred 1699 kilobytes. 1700 </para></listitem> 1701 </varlistentry> 1702 1703 <varlistentry id="thread.peak.reset"> 1704 <term> 1705 <mallctl>thread.peak.reset</mallctl> 1706 (<type>void</type>) 1707 <literal>--</literal> 1708 [<option>--enable-stats</option>] 1709 </term> 1710 <listitem><para>Resets the counter for net bytes allocated in the calling 1711 thread to zero. This affects subsequent calls to <link 1712 linkend="thread.peak.read"><mallctl>thread.peak.read</mallctl></link>, 1713 but not the values returned by <link 1714 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 1715 or <link 1716 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link>. 1717 </para></listitem> 1718 </varlistentry> 1719 1720 <varlistentry id="thread.tcache.enabled"> 1721 <term> 1722 <mallctl>thread.tcache.enabled</mallctl> 1723 (<type>bool</type>) 1724 <literal>rw</literal> 1725 </term> 1726 <listitem><para>Enable/disable calling thread's tcache. The tcache is 1727 implicitly flushed as a side effect of becoming 1728 disabled (see <link 1729 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>). 1730 </para></listitem> 1731 </varlistentry> 1732 1733 <varlistentry id="thread.tcache.flush"> 1734 <term> 1735 <mallctl>thread.tcache.flush</mallctl> 1736 (<type>void</type>) 1737 <literal>--</literal> 1738 </term> 1739 <listitem><para>Flush calling thread's thread-specific cache (tcache). 1740 This interface releases all cached objects and internal data structures 1741 associated with the calling thread's tcache. Ordinarily, this interface 1742 need not be called, since automatic periodic incremental garbage 1743 collection occurs, and the thread cache is automatically discarded when 1744 a thread exits. However, garbage collection is triggered by allocation 1745 activity, so it is possible for a thread that stops 1746 allocating/deallocating to retain its cache indefinitely, in which case 1747 the developer may find manual flushing useful.</para></listitem> 1748 </varlistentry> 1749 1750 <varlistentry id="thread.prof.name"> 1751 <term> 1752 <mallctl>thread.prof.name</mallctl> 1753 (<type>const char *</type>) 1754 <literal>r-</literal> or 1755 <literal>-w</literal> 1756 [<option>--enable-prof</option>] 1757 </term> 1758 <listitem><para>Get/set the descriptive name associated with the calling 1759 thread in memory profile dumps. An internal copy of the name string is 1760 created, so the input string need not be maintained after this interface 1761 completes execution. The output string of this interface should be 1762 copied for non-ephemeral uses, because multiple implementation details 1763 can cause asynchronous string deallocation. Furthermore, each 1764 invocation of this interface can only read or write; simultaneous 1765 read/write is not supported due to string lifetime limitations. The 1766 name string must be nil-terminated and comprised only of characters in 1767 the sets recognized 1768 by <citerefentry><refentrytitle>isgraph</refentrytitle> 1769 <manvolnum>3</manvolnum></citerefentry> and 1770 <citerefentry><refentrytitle>isblank</refentrytitle> 1771 <manvolnum>3</manvolnum></citerefentry>.</para></listitem> 1772 </varlistentry> 1773 1774 <varlistentry id="thread.prof.active"> 1775 <term> 1776 <mallctl>thread.prof.active</mallctl> 1777 (<type>bool</type>) 1778 <literal>rw</literal> 1779 [<option>--enable-prof</option>] 1780 </term> 1781 <listitem><para>Control whether sampling is currently active for the 1782 calling thread. This is an activation mechanism in addition to <link 1783 linkend="prof.active"><mallctl>prof.active</mallctl></link>; both must 1784 be active for the calling thread to sample. This flag is enabled by 1785 default.</para></listitem> 1786 </varlistentry> 1787 1788 <varlistentry id="thread.idle"> 1789 <term> 1790 <mallctl>thread.idle</mallctl> 1791 (<type>void</type>) 1792 <literal>--</literal> 1793 </term> 1794 <listitem><para>Hints to jemalloc that the calling thread will be idle 1795 for some nontrivial period of time (say, on the order of seconds), and 1796 that doing some cleanup operations may be beneficial. There are no 1797 guarantees as to what specific operations will be performed; currently 1798 this flushes the caller's tcache and may (according to some heuristic) 1799 purge its associated arena.</para> 1800 <para>This is not intended to be a general-purpose background activity 1801 mechanism, and threads should not wake up multiple times solely to call 1802 it. Rather, a thread waiting for a task should do a timed wait first, 1803 call <link linkend="thread.idle"><mallctl>thread.idle</mallctl></link> 1804 if no task appears in the timeout interval, and then do an untimed wait. 1805 For such a background activity mechanism, see 1806 <link linkend="background_thread"><mallctl>background_thread</mallctl></link>. 1807 </para></listitem> 1808 </varlistentry> 1809 1810 <varlistentry id="tcache.create"> 1811 <term> 1812 <mallctl>tcache.create</mallctl> 1813 (<type>unsigned</type>) 1814 <literal>r-</literal> 1815 </term> 1816 <listitem><para>Create an explicit thread-specific cache (tcache) and 1817 return an identifier that can be passed to the <link 1818 linkend="MALLOCX_TCACHE"><constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant></link> 1819 macro to explicitly use the specified cache rather than the 1820 automatically managed one that is used by default. Each explicit cache 1821 can be used by only one thread at a time; the application must assure 1822 that this constraint holds. 1823 </para> 1824 1825 <para>If the amount of space supplied for storing the thread-specific 1826 cache identifier does not equal 1827 <code language="C">sizeof(<type>unsigned</type>)</code>, no 1828 thread-specific cache will be created, no data will be written to the 1829 space pointed by <parameter>oldp</parameter>, and 1830 <parameter>*oldlenp</parameter> will be set to 0. 1831 </para></listitem> 1832 1833 </varlistentry> 1834 1835 <varlistentry id="tcache.flush"> 1836 <term> 1837 <mallctl>tcache.flush</mallctl> 1838 (<type>unsigned</type>) 1839 <literal>-w</literal> 1840 </term> 1841 <listitem><para>Flush the specified thread-specific cache (tcache). The 1842 same considerations apply to this interface as to <link 1843 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>, 1844 except that the tcache will never be automatically discarded. 1845 </para></listitem> 1846 </varlistentry> 1847 1848 <varlistentry id="tcache.destroy"> 1849 <term> 1850 <mallctl>tcache.destroy</mallctl> 1851 (<type>unsigned</type>) 1852 <literal>-w</literal> 1853 </term> 1854 <listitem><para>Flush the specified thread-specific cache (tcache) and 1855 make the identifier available for use during a future tcache creation. 1856 </para></listitem> 1857 </varlistentry> 1858 1859 <varlistentry id="arena.i.initialized"> 1860 <term> 1861 <mallctl>arena.<i>.initialized</mallctl> 1862 (<type>bool</type>) 1863 <literal>r-</literal> 1864 </term> 1865 <listitem><para>Get whether the specified arena's statistics are 1866 initialized (i.e. the arena was initialized prior to the current epoch). 1867 This interface can also be nominally used to query whether the merged 1868 statistics corresponding to <constant>MALLCTL_ARENAS_ALL</constant> are 1869 initialized (always true).</para></listitem> 1870 </varlistentry> 1871 1872 <varlistentry id="arena.i.decay"> 1873 <term> 1874 <mallctl>arena.<i>.decay</mallctl> 1875 (<type>void</type>) 1876 <literal>--</literal> 1877 </term> 1878 <listitem><para>Trigger decay-based purging of unused dirty/muzzy pages 1879 for arena <i>, or for all arenas if <i> equals 1880 <constant>MALLCTL_ARENAS_ALL</constant>. The proportion of unused 1881 dirty/muzzy pages to be purged depends on the current time; see <link 1882 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 1883 and <link 1884 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzy_decay_ms</mallctl></link> 1885 for details.</para></listitem> 1886 </varlistentry> 1887 1888 <varlistentry id="arena.i.purge"> 1889 <term> 1890 <mallctl>arena.<i>.purge</mallctl> 1891 (<type>void</type>) 1892 <literal>--</literal> 1893 </term> 1894 <listitem><para>Purge all unused dirty pages for arena <i>, or for 1895 all arenas if <i> equals <constant>MALLCTL_ARENAS_ALL</constant>. 1896 </para></listitem> 1897 </varlistentry> 1898 1899 <varlistentry id="arena.i.reset"> 1900 <term> 1901 <mallctl>arena.<i>.reset</mallctl> 1902 (<type>void</type>) 1903 <literal>--</literal> 1904 </term> 1905 <listitem><para>Discard all of the arena's extant allocations. This 1906 interface can only be used with arenas explicitly created via <link 1907 linkend="arenas.create"><mallctl>arenas.create</mallctl></link>. None 1908 of the arena's discarded/cached allocations may accessed afterward. As 1909 part of this requirement, all thread caches which were used to 1910 allocate/deallocate in conjunction with the arena must be flushed 1911 beforehand.</para></listitem> 1912 </varlistentry> 1913 1914 <varlistentry id="arena.i.destroy"> 1915 <term> 1916 <mallctl>arena.<i>.destroy</mallctl> 1917 (<type>void</type>) 1918 <literal>--</literal> 1919 </term> 1920 <listitem><para>Destroy the arena. Discard all of the arena's extant 1921 allocations using the same mechanism as for <link 1922 linkend="arena.i.reset"><mallctl>arena.<i>.reset</mallctl></link> 1923 (with all the same constraints and side effects), merge the arena stats 1924 into those accessible at arena index 1925 <constant>MALLCTL_ARENAS_DESTROYED</constant>, and then completely 1926 discard all metadata associated with the arena. Future calls to <link 1927 linkend="arenas.create"><mallctl>arenas.create</mallctl></link> may 1928 recycle the arena index. Destruction will fail if any threads are 1929 currently associated with the arena as a result of calls to <link 1930 linkend="thread.arena"><mallctl>thread.arena</mallctl></link>.</para></listitem> 1931 </varlistentry> 1932 1933 <varlistentry id="arena.i.dss"> 1934 <term> 1935 <mallctl>arena.<i>.dss</mallctl> 1936 (<type>const char *</type>) 1937 <literal>rw</literal> 1938 </term> 1939 <listitem><para>Set the precedence of dss allocation as related to mmap 1940 allocation for arena <i>, or for all arenas if <i> equals 1941 <constant>MALLCTL_ARENAS_ALL</constant>. See <link 1942 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for supported 1943 settings.</para></listitem> 1944 </varlistentry> 1945 1946 <varlistentry id="arena.i.dirty_decay_ms"> 1947 <term> 1948 <mallctl>arena.<i>.dirty_decay_ms</mallctl> 1949 (<type>ssize_t</type>) 1950 <literal>rw</literal> 1951 </term> 1952 <listitem><para>Current per-arena approximate time in milliseconds from 1953 the creation of a set of unused dirty pages until an equivalent set of 1954 unused dirty pages is purged and/or reused. Each time this interface is 1955 set, all currently unused dirty pages are considered to have fully 1956 decayed, which causes immediate purging of all unused dirty pages unless 1957 the decay time is set to -1 (i.e. purging disabled). See <link 1958 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 1959 for additional information.</para></listitem> 1960 </varlistentry> 1961 1962 <varlistentry id="arena.i.muzzy_decay_ms"> 1963 <term> 1964 <mallctl>arena.<i>.muzzy_decay_ms</mallctl> 1965 (<type>ssize_t</type>) 1966 <literal>rw</literal> 1967 </term> 1968 <listitem><para>Current per-arena approximate time in milliseconds from 1969 the creation of a set of unused muzzy pages until an equivalent set of 1970 unused muzzy pages is purged and/or reused. Each time this interface is 1971 set, all currently unused muzzy pages are considered to have fully 1972 decayed, which causes immediate purging of all unused muzzy pages unless 1973 the decay time is set to -1 (i.e. purging disabled). See <link 1974 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 1975 for additional information.</para></listitem> 1976 </varlistentry> 1977 1978 <varlistentry id="arena.i.retain_grow_limit"> 1979 <term> 1980 <mallctl>arena.<i>.retain_grow_limit</mallctl> 1981 (<type>size_t</type>) 1982 <literal>rw</literal> 1983 </term> 1984 <listitem><para>Maximum size to grow retained region (only relevant when 1985 <link linkend="opt.retain"><mallctl>opt.retain</mallctl></link> is 1986 enabled). This controls the maximum increment to expand virtual memory, 1987 or allocation through <link 1988 linkend="arena.i.extent_hooks"><mallctl>arena.<i>extent_hooks</mallctl></link>. 1989 In particular, if customized extent hooks reserve physical memory 1990 (e.g. 1G huge pages), this is useful to control the allocation hook's 1991 input size. The default is no limit.</para></listitem> 1992 </varlistentry> 1993 1994 <varlistentry id="arena.i.extent_hooks"> 1995 <term> 1996 <mallctl>arena.<i>.extent_hooks</mallctl> 1997 (<type>extent_hooks_t *</type>) 1998 <literal>rw</literal> 1999 </term> 2000 <listitem><para>Get or set the extent management hook functions for 2001 arena <i>. The functions must be capable of operating on all 2002 extant extents associated with arena <i>, usually by passing 2003 unknown extents to the replaced functions. In practice, it is feasible 2004 to control allocation for arenas explicitly created via <link 2005 linkend="arenas.create"><mallctl>arenas.create</mallctl></link> such 2006 that all extents originate from an application-supplied extent allocator 2007 (by specifying the custom extent hook functions during arena creation). 2008 However, the API guarantees for the automatically created arenas may be 2009 relaxed -- hooks set there may be called in a "best effort" fashion; in 2010 addition there may be extents created prior to the application having an 2011 opportunity to take over extent allocation.</para> 2012 2013 <programlisting language="C"><![CDATA[ 2014typedef extent_hooks_s extent_hooks_t; 2015struct extent_hooks_s { 2016 extent_alloc_t *alloc; 2017 extent_dalloc_t *dalloc; 2018 extent_destroy_t *destroy; 2019 extent_commit_t *commit; 2020 extent_decommit_t *decommit; 2021 extent_purge_t *purge_lazy; 2022 extent_purge_t *purge_forced; 2023 extent_split_t *split; 2024 extent_merge_t *merge; 2025};]]></programlisting> 2026 <para>The <type>extent_hooks_t</type> structure comprises function 2027 pointers which are described individually below. jemalloc uses these 2028 functions to manage extent lifetime, which starts off with allocation of 2029 mapped committed memory, in the simplest case followed by deallocation. 2030 However, there are performance and platform reasons to retain extents 2031 for later reuse. Cleanup attempts cascade from deallocation to decommit 2032 to forced purging to lazy purging, which gives the extent management 2033 functions opportunities to reject the most permanent cleanup operations 2034 in favor of less permanent (and often less costly) operations. All 2035 operations except allocation can be universally opted out of by setting 2036 the hook pointers to <constant>NULL</constant>, or selectively opted out 2037 of by returning failure. Note that once the extent hook is set, the 2038 structure is accessed directly by the associated arenas, so it must 2039 remain valid for the entire lifetime of the arenas.</para> 2040 2041 <funcsynopsis><funcprototype> 2042 <funcdef>typedef void *<function>(extent_alloc_t)</function></funcdef> 2043 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2044 <paramdef>void *<parameter>new_addr</parameter></paramdef> 2045 <paramdef>size_t <parameter>size</parameter></paramdef> 2046 <paramdef>size_t <parameter>alignment</parameter></paramdef> 2047 <paramdef>bool *<parameter>zero</parameter></paramdef> 2048 <paramdef>bool *<parameter>commit</parameter></paramdef> 2049 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2050 </funcprototype></funcsynopsis> 2051 <literallayout></literallayout> 2052 <para>An extent allocation function conforms to the 2053 <type>extent_alloc_t</type> type and upon success returns a pointer to 2054 <parameter>size</parameter> bytes of mapped memory on behalf of arena 2055 <parameter>arena_ind</parameter> such that the extent's base address is 2056 a multiple of <parameter>alignment</parameter>, as well as setting 2057 <parameter>*zero</parameter> to indicate whether the extent is zeroed 2058 and <parameter>*commit</parameter> to indicate whether the extent is 2059 committed. Upon error the function returns <constant>NULL</constant> 2060 and leaves <parameter>*zero</parameter> and 2061 <parameter>*commit</parameter> unmodified. The 2062 <parameter>size</parameter> parameter is always a multiple of the page 2063 size. The <parameter>alignment</parameter> parameter is always a power 2064 of two at least as large as the page size. Zeroing is mandatory if 2065 <parameter>*zero</parameter> is true upon function entry. Committing is 2066 mandatory if <parameter>*commit</parameter> is true upon function entry. 2067 If <parameter>new_addr</parameter> is not <constant>NULL</constant>, the 2068 returned pointer must be <parameter>new_addr</parameter> on success or 2069 <constant>NULL</constant> on error. Committed memory may be committed 2070 in absolute terms as on a system that does not overcommit, or in 2071 implicit terms as on a system that overcommits and satisfies physical 2072 memory needs on demand via soft page faults. Note that replacing the 2073 default extent allocation function makes the arena's <link 2074 linkend="arena.i.dss"><mallctl>arena.<i>.dss</mallctl></link> 2075 setting irrelevant.</para> 2076 2077 <funcsynopsis><funcprototype> 2078 <funcdef>typedef bool <function>(extent_dalloc_t)</function></funcdef> 2079 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2080 <paramdef>void *<parameter>addr</parameter></paramdef> 2081 <paramdef>size_t <parameter>size</parameter></paramdef> 2082 <paramdef>bool <parameter>committed</parameter></paramdef> 2083 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2084 </funcprototype></funcsynopsis> 2085 <literallayout></literallayout> 2086 <para> 2087 An extent deallocation function conforms to the 2088 <type>extent_dalloc_t</type> type and deallocates an extent at given 2089 <parameter>addr</parameter> and <parameter>size</parameter> with 2090 <parameter>committed</parameter>/decommited memory as indicated, on 2091 behalf of arena <parameter>arena_ind</parameter>, returning false upon 2092 success. If the function returns true, this indicates opt-out from 2093 deallocation; the virtual memory mapping associated with the extent 2094 remains mapped, in the same commit state, and available for future use, 2095 in which case it will be automatically retained for later reuse.</para> 2096 2097 <funcsynopsis><funcprototype> 2098 <funcdef>typedef void <function>(extent_destroy_t)</function></funcdef> 2099 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2100 <paramdef>void *<parameter>addr</parameter></paramdef> 2101 <paramdef>size_t <parameter>size</parameter></paramdef> 2102 <paramdef>bool <parameter>committed</parameter></paramdef> 2103 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2104 </funcprototype></funcsynopsis> 2105 <literallayout></literallayout> 2106 <para> 2107 An extent destruction function conforms to the 2108 <type>extent_destroy_t</type> type and unconditionally destroys an 2109 extent at given <parameter>addr</parameter> and 2110 <parameter>size</parameter> with 2111 <parameter>committed</parameter>/decommited memory as indicated, on 2112 behalf of arena <parameter>arena_ind</parameter>. This function may be 2113 called to destroy retained extents during arena destruction (see <link 2114 linkend="arena.i.destroy"><mallctl>arena.<i>.destroy</mallctl></link>).</para> 2115 2116 <funcsynopsis><funcprototype> 2117 <funcdef>typedef bool <function>(extent_commit_t)</function></funcdef> 2118 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2119 <paramdef>void *<parameter>addr</parameter></paramdef> 2120 <paramdef>size_t <parameter>size</parameter></paramdef> 2121 <paramdef>size_t <parameter>offset</parameter></paramdef> 2122 <paramdef>size_t <parameter>length</parameter></paramdef> 2123 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2124 </funcprototype></funcsynopsis> 2125 <literallayout></literallayout> 2126 <para>An extent commit function conforms to the 2127 <type>extent_commit_t</type> type and commits zeroed physical memory to 2128 back pages within an extent at given <parameter>addr</parameter> and 2129 <parameter>size</parameter> at <parameter>offset</parameter> bytes, 2130 extending for <parameter>length</parameter> on behalf of arena 2131 <parameter>arena_ind</parameter>, returning false upon success. 2132 Committed memory may be committed in absolute terms as on a system that 2133 does not overcommit, or in implicit terms as on a system that 2134 overcommits and satisfies physical memory needs on demand via soft page 2135 faults. If the function returns true, this indicates insufficient 2136 physical memory to satisfy the request.</para> 2137 2138 <funcsynopsis><funcprototype> 2139 <funcdef>typedef bool <function>(extent_decommit_t)</function></funcdef> 2140 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2141 <paramdef>void *<parameter>addr</parameter></paramdef> 2142 <paramdef>size_t <parameter>size</parameter></paramdef> 2143 <paramdef>size_t <parameter>offset</parameter></paramdef> 2144 <paramdef>size_t <parameter>length</parameter></paramdef> 2145 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2146 </funcprototype></funcsynopsis> 2147 <literallayout></literallayout> 2148 <para>An extent decommit function conforms to the 2149 <type>extent_decommit_t</type> type and decommits any physical memory 2150 that is backing pages within an extent at given 2151 <parameter>addr</parameter> and <parameter>size</parameter> at 2152 <parameter>offset</parameter> bytes, extending for 2153 <parameter>length</parameter> on behalf of arena 2154 <parameter>arena_ind</parameter>, returning false upon success, in which 2155 case the pages will be committed via the extent commit function before 2156 being reused. If the function returns true, this indicates opt-out from 2157 decommit; the memory remains committed and available for future use, in 2158 which case it will be automatically retained for later reuse.</para> 2159 2160 <funcsynopsis><funcprototype> 2161 <funcdef>typedef bool <function>(extent_purge_t)</function></funcdef> 2162 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2163 <paramdef>void *<parameter>addr</parameter></paramdef> 2164 <paramdef>size_t <parameter>size</parameter></paramdef> 2165 <paramdef>size_t <parameter>offset</parameter></paramdef> 2166 <paramdef>size_t <parameter>length</parameter></paramdef> 2167 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2168 </funcprototype></funcsynopsis> 2169 <literallayout></literallayout> 2170 <para>An extent purge function conforms to the 2171 <type>extent_purge_t</type> type and discards physical pages 2172 within the virtual memory mapping associated with an extent at given 2173 <parameter>addr</parameter> and <parameter>size</parameter> at 2174 <parameter>offset</parameter> bytes, extending for 2175 <parameter>length</parameter> on behalf of arena 2176 <parameter>arena_ind</parameter>. A lazy extent purge function (e.g. 2177 implemented via 2178 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function>) 2179 can delay purging indefinitely and leave the pages within the purged 2180 virtual memory range in an indeterminite state, whereas a forced extent 2181 purge function immediately purges, and the pages within the virtual 2182 memory range will be zero-filled the next time they are accessed. If 2183 the function returns true, this indicates failure to purge.</para> 2184 2185 <funcsynopsis><funcprototype> 2186 <funcdef>typedef bool <function>(extent_split_t)</function></funcdef> 2187 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2188 <paramdef>void *<parameter>addr</parameter></paramdef> 2189 <paramdef>size_t <parameter>size</parameter></paramdef> 2190 <paramdef>size_t <parameter>size_a</parameter></paramdef> 2191 <paramdef>size_t <parameter>size_b</parameter></paramdef> 2192 <paramdef>bool <parameter>committed</parameter></paramdef> 2193 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2194 </funcprototype></funcsynopsis> 2195 <literallayout></literallayout> 2196 <para>An extent split function conforms to the 2197 <type>extent_split_t</type> type and optionally splits an extent at 2198 given <parameter>addr</parameter> and <parameter>size</parameter> into 2199 two adjacent extents, the first of <parameter>size_a</parameter> bytes, 2200 and the second of <parameter>size_b</parameter> bytes, operating on 2201 <parameter>committed</parameter>/decommitted memory as indicated, on 2202 behalf of arena <parameter>arena_ind</parameter>, returning false upon 2203 success. If the function returns true, this indicates that the extent 2204 remains unsplit and therefore should continue to be operated on as a 2205 whole.</para> 2206 2207 <funcsynopsis><funcprototype> 2208 <funcdef>typedef bool <function>(extent_merge_t)</function></funcdef> 2209 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 2210 <paramdef>void *<parameter>addr_a</parameter></paramdef> 2211 <paramdef>size_t <parameter>size_a</parameter></paramdef> 2212 <paramdef>void *<parameter>addr_b</parameter></paramdef> 2213 <paramdef>size_t <parameter>size_b</parameter></paramdef> 2214 <paramdef>bool <parameter>committed</parameter></paramdef> 2215 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 2216 </funcprototype></funcsynopsis> 2217 <literallayout></literallayout> 2218 <para>An extent merge function conforms to the 2219 <type>extent_merge_t</type> type and optionally merges adjacent extents, 2220 at given <parameter>addr_a</parameter> and <parameter>size_a</parameter> 2221 with given <parameter>addr_b</parameter> and 2222 <parameter>size_b</parameter> into one contiguous extent, operating on 2223 <parameter>committed</parameter>/decommitted memory as indicated, on 2224 behalf of arena <parameter>arena_ind</parameter>, returning false upon 2225 success. If the function returns true, this indicates that the extents 2226 remain distinct mappings and therefore should continue to be operated on 2227 independently.</para> 2228 </listitem> 2229 </varlistentry> 2230 2231 <varlistentry id="arenas.narenas"> 2232 <term> 2233 <mallctl>arenas.narenas</mallctl> 2234 (<type>unsigned</type>) 2235 <literal>r-</literal> 2236 </term> 2237 <listitem><para>Current limit on number of arenas.</para></listitem> 2238 </varlistentry> 2239 2240 <varlistentry id="arenas.dirty_decay_ms"> 2241 <term> 2242 <mallctl>arenas.dirty_decay_ms</mallctl> 2243 (<type>ssize_t</type>) 2244 <literal>rw</literal> 2245 </term> 2246 <listitem><para>Current default per-arena approximate time in 2247 milliseconds from the creation of a set of unused dirty pages until an 2248 equivalent set of unused dirty pages is purged and/or reused, used to 2249 initialize <link 2250 linkend="arena.i.dirty_decay_ms"><mallctl>arena.<i>.dirty_decay_ms</mallctl></link> 2251 during arena creation. See <link 2252 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2253 for additional information.</para></listitem> 2254 </varlistentry> 2255 2256 <varlistentry id="arenas.muzzy_decay_ms"> 2257 <term> 2258 <mallctl>arenas.muzzy_decay_ms</mallctl> 2259 (<type>ssize_t</type>) 2260 <literal>rw</literal> 2261 </term> 2262 <listitem><para>Current default per-arena approximate time in 2263 milliseconds from the creation of a set of unused muzzy pages until an 2264 equivalent set of unused muzzy pages is purged and/or reused, used to 2265 initialize <link 2266 linkend="arena.i.muzzy_decay_ms"><mallctl>arena.<i>.muzzy_decay_ms</mallctl></link> 2267 during arena creation. See <link 2268 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2269 for additional information.</para></listitem> 2270 </varlistentry> 2271 2272 <varlistentry id="arenas.quantum"> 2273 <term> 2274 <mallctl>arenas.quantum</mallctl> 2275 (<type>size_t</type>) 2276 <literal>r-</literal> 2277 </term> 2278 <listitem><para>Quantum size.</para></listitem> 2279 </varlistentry> 2280 2281 <varlistentry id="arenas.page"> 2282 <term> 2283 <mallctl>arenas.page</mallctl> 2284 (<type>size_t</type>) 2285 <literal>r-</literal> 2286 </term> 2287 <listitem><para>Page size.</para></listitem> 2288 </varlistentry> 2289 2290 <varlistentry id="arenas.tcache_max"> 2291 <term> 2292 <mallctl>arenas.tcache_max</mallctl> 2293 (<type>size_t</type>) 2294 <literal>r-</literal> 2295 </term> 2296 <listitem><para>Maximum thread-cached size class.</para></listitem> 2297 </varlistentry> 2298 2299 <varlistentry id="arenas.nbins"> 2300 <term> 2301 <mallctl>arenas.nbins</mallctl> 2302 (<type>unsigned</type>) 2303 <literal>r-</literal> 2304 </term> 2305 <listitem><para>Number of bin size classes.</para></listitem> 2306 </varlistentry> 2307 2308 <varlistentry id="arenas.nhbins"> 2309 <term> 2310 <mallctl>arenas.nhbins</mallctl> 2311 (<type>unsigned</type>) 2312 <literal>r-</literal> 2313 </term> 2314 <listitem><para>Total number of thread cache bin size 2315 classes.</para></listitem> 2316 </varlistentry> 2317 2318 <varlistentry id="arenas.bin.i.size"> 2319 <term> 2320 <mallctl>arenas.bin.<i>.size</mallctl> 2321 (<type>size_t</type>) 2322 <literal>r-</literal> 2323 </term> 2324 <listitem><para>Maximum size supported by size class.</para></listitem> 2325 </varlistentry> 2326 2327 <varlistentry id="arenas.bin.i.nregs"> 2328 <term> 2329 <mallctl>arenas.bin.<i>.nregs</mallctl> 2330 (<type>uint32_t</type>) 2331 <literal>r-</literal> 2332 </term> 2333 <listitem><para>Number of regions per slab.</para></listitem> 2334 </varlistentry> 2335 2336 <varlistentry id="arenas.bin.i.slab_size"> 2337 <term> 2338 <mallctl>arenas.bin.<i>.slab_size</mallctl> 2339 (<type>size_t</type>) 2340 <literal>r-</literal> 2341 </term> 2342 <listitem><para>Number of bytes per slab.</para></listitem> 2343 </varlistentry> 2344 2345 <varlistentry id="arenas.nlextents"> 2346 <term> 2347 <mallctl>arenas.nlextents</mallctl> 2348 (<type>unsigned</type>) 2349 <literal>r-</literal> 2350 </term> 2351 <listitem><para>Total number of large size classes.</para></listitem> 2352 </varlistentry> 2353 2354 <varlistentry id="arenas.lextent.i.size"> 2355 <term> 2356 <mallctl>arenas.lextent.<i>.size</mallctl> 2357 (<type>size_t</type>) 2358 <literal>r-</literal> 2359 </term> 2360 <listitem><para>Maximum size supported by this large size 2361 class.</para></listitem> 2362 </varlistentry> 2363 2364 <varlistentry id="arenas.create"> 2365 <term> 2366 <mallctl>arenas.create</mallctl> 2367 (<type>unsigned</type>, <type>extent_hooks_t *</type>) 2368 <literal>rw</literal> 2369 </term> 2370 <listitem><para>Explicitly create a new arena outside the range of 2371 automatically managed arenas, with optionally specified extent hooks, 2372 and return the new arena index.</para> 2373 2374 <para>If the amount of space supplied for storing the arena index does 2375 not equal <code language="C">sizeof(<type>unsigned</type>)</code>, no 2376 arena will be created, no data will be written to the space pointed by 2377 <parameter>oldp</parameter>, and <parameter>*oldlenp</parameter> will 2378 be set to 0. 2379 </para></listitem> 2380 </varlistentry> 2381 2382 <varlistentry id="arenas.lookup"> 2383 <term> 2384 <mallctl>arenas.lookup</mallctl> 2385 (<type>unsigned</type>, <type>void*</type>) 2386 <literal>rw</literal> 2387 </term> 2388 <listitem><para>Index of the arena to which an allocation belongs to.</para></listitem> 2389 </varlistentry> 2390 2391 <varlistentry id="prof.thread_active_init"> 2392 <term> 2393 <mallctl>prof.thread_active_init</mallctl> 2394 (<type>bool</type>) 2395 <literal>rw</literal> 2396 [<option>--enable-prof</option>] 2397 </term> 2398 <listitem><para>Control the initial setting for <link 2399 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 2400 in newly created threads. See the <link 2401 linkend="opt.prof_thread_active_init"><mallctl>opt.prof_thread_active_init</mallctl></link> 2402 option for additional information.</para></listitem> 2403 </varlistentry> 2404 2405 <varlistentry id="prof.active"> 2406 <term> 2407 <mallctl>prof.active</mallctl> 2408 (<type>bool</type>) 2409 <literal>rw</literal> 2410 [<option>--enable-prof</option>] 2411 </term> 2412 <listitem><para>Control whether sampling is currently active. See the 2413 <link 2414 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 2415 option for additional information, as well as the interrelated <link 2416 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 2417 mallctl.</para></listitem> 2418 </varlistentry> 2419 2420 <varlistentry id="prof.dump"> 2421 <term> 2422 <mallctl>prof.dump</mallctl> 2423 (<type>const char *</type>) 2424 <literal>-w</literal> 2425 [<option>--enable-prof</option>] 2426 </term> 2427 <listitem><para>Dump a memory profile to the specified file, or if NULL 2428 is specified, to a file according to the pattern 2429 <filename><prefix>.<pid>.<seq>.m<mseq>.heap</filename>, 2430 where <literal><prefix></literal> is controlled by the 2431 <link linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 2432 and <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link> 2433 options.</para></listitem> 2434 </varlistentry> 2435 2436 <varlistentry id="prof.prefix"> 2437 <term> 2438 <mallctl>prof.prefix</mallctl> 2439 (<type>const char *</type>) 2440 <literal>-w</literal> 2441 [<option>--enable-prof</option>] 2442 </term> 2443 <listitem><para>Set the filename prefix for profile dumps. See 2444 <link 2445 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 2446 for the default setting. This can be useful to differentiate profile 2447 dumps such as from forked processes. 2448 </para></listitem> 2449 </varlistentry> 2450 2451 <varlistentry id="prof.gdump"> 2452 <term> 2453 <mallctl>prof.gdump</mallctl> 2454 (<type>bool</type>) 2455 <literal>rw</literal> 2456 [<option>--enable-prof</option>] 2457 </term> 2458 <listitem><para>When enabled, trigger a memory profile dump every time 2459 the total virtual memory exceeds the previous maximum. Profiles are 2460 dumped to files named according to the pattern 2461 <filename><prefix>.<pid>.<seq>.u<useq>.heap</filename>, 2462 where <literal><prefix></literal> is controlled by the <link 2463 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> and 2464 <link linkend="prof.prefix"><mallctl>prof.prefix</mallctl></link> 2465 options.</para></listitem> 2466 </varlistentry> 2467 2468 <varlistentry id="prof.reset"> 2469 <term> 2470 <mallctl>prof.reset</mallctl> 2471 (<type>size_t</type>) 2472 <literal>-w</literal> 2473 [<option>--enable-prof</option>] 2474 </term> 2475 <listitem><para>Reset all memory profile statistics, and optionally 2476 update the sample rate (see <link 2477 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 2478 and <link 2479 linkend="prof.lg_sample"><mallctl>prof.lg_sample</mallctl></link>). 2480 </para></listitem> 2481 </varlistentry> 2482 2483 <varlistentry id="prof.lg_sample"> 2484 <term> 2485 <mallctl>prof.lg_sample</mallctl> 2486 (<type>size_t</type>) 2487 <literal>r-</literal> 2488 [<option>--enable-prof</option>] 2489 </term> 2490 <listitem><para>Get the current sample rate (see <link 2491 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link>). 2492 </para></listitem> 2493 </varlistentry> 2494 2495 <varlistentry id="prof.interval"> 2496 <term> 2497 <mallctl>prof.interval</mallctl> 2498 (<type>uint64_t</type>) 2499 <literal>r-</literal> 2500 [<option>--enable-prof</option>] 2501 </term> 2502 <listitem><para>Average number of bytes allocated between 2503 interval-based profile dumps. See the 2504 <link 2505 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 2506 option for additional information.</para></listitem> 2507 </varlistentry> 2508 2509 <varlistentry id="stats.allocated"> 2510 <term> 2511 <mallctl>stats.allocated</mallctl> 2512 (<type>size_t</type>) 2513 <literal>r-</literal> 2514 [<option>--enable-stats</option>] 2515 </term> 2516 <listitem><para>Total number of bytes allocated by the 2517 application.</para></listitem> 2518 </varlistentry> 2519 2520 <varlistentry id="stats.active"> 2521 <term> 2522 <mallctl>stats.active</mallctl> 2523 (<type>size_t</type>) 2524 <literal>r-</literal> 2525 [<option>--enable-stats</option>] 2526 </term> 2527 <listitem><para>Total number of bytes in active pages allocated by the 2528 application. This is a multiple of the page size, and greater than or 2529 equal to <link 2530 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>. 2531 This does not include <link linkend="stats.arenas.i.pdirty"> 2532 <mallctl>stats.arenas.<i>.pdirty</mallctl></link>, 2533 <link linkend="stats.arenas.i.pmuzzy"> 2534 <mallctl>stats.arenas.<i>.pmuzzy</mallctl></link>, nor pages 2535 entirely devoted to allocator metadata.</para></listitem> 2536 </varlistentry> 2537 2538 <varlistentry id="stats.metadata"> 2539 <term> 2540 <mallctl>stats.metadata</mallctl> 2541 (<type>size_t</type>) 2542 <literal>r-</literal> 2543 [<option>--enable-stats</option>] 2544 </term> 2545 <listitem><para>Total number of bytes dedicated to metadata, which 2546 comprise base allocations used for bootstrap-sensitive allocator 2547 metadata structures (see <link 2548 linkend="stats.arenas.i.base"><mallctl>stats.arenas.<i>.base</mallctl></link>) 2549 and internal allocations (see <link 2550 linkend="stats.arenas.i.internal"><mallctl>stats.arenas.<i>.internal</mallctl></link>). 2551 Transparent huge page (enabled with <link 2552 linkend="opt.metadata_thp">opt.metadata_thp</link>) usage is not 2553 considered.</para></listitem> 2554 </varlistentry> 2555 2556 <varlistentry id="stats.metadata_thp"> 2557 <term> 2558 <mallctl>stats.metadata_thp</mallctl> 2559 (<type>size_t</type>) 2560 <literal>r-</literal> 2561 [<option>--enable-stats</option>] 2562 </term> 2563 <listitem><para>Number of transparent huge pages (THP) used for 2564 metadata. See <link 2565 linkend="stats.metadata"><mallctl>stats.metadata</mallctl></link> and 2566 <link linkend="opt.metadata_thp">opt.metadata_thp</link>) for 2567 details.</para></listitem> 2568 </varlistentry> 2569 2570 <varlistentry id="stats.resident"> 2571 <term> 2572 <mallctl>stats.resident</mallctl> 2573 (<type>size_t</type>) 2574 <literal>r-</literal> 2575 [<option>--enable-stats</option>] 2576 </term> 2577 <listitem><para>Maximum number of bytes in physically resident data 2578 pages mapped by the allocator, comprising all pages dedicated to 2579 allocator metadata, pages backing active allocations, and unused dirty 2580 pages. This is a maximum rather than precise because pages may not 2581 actually be physically resident if they correspond to demand-zeroed 2582 virtual memory that has not yet been touched. This is a multiple of the 2583 page size, and is larger than <link 2584 linkend="stats.active"><mallctl>stats.active</mallctl></link>.</para></listitem> 2585 </varlistentry> 2586 2587 <varlistentry id="stats.mapped"> 2588 <term> 2589 <mallctl>stats.mapped</mallctl> 2590 (<type>size_t</type>) 2591 <literal>r-</literal> 2592 [<option>--enable-stats</option>] 2593 </term> 2594 <listitem><para>Total number of bytes in active extents mapped by the 2595 allocator. This is larger than <link 2596 linkend="stats.active"><mallctl>stats.active</mallctl></link>. This 2597 does not include inactive extents, even those that contain unused dirty 2598 pages, which means that there is no strict ordering between this and 2599 <link 2600 linkend="stats.resident"><mallctl>stats.resident</mallctl></link>.</para></listitem> 2601 </varlistentry> 2602 2603 <varlistentry id="stats.retained"> 2604 <term> 2605 <mallctl>stats.retained</mallctl> 2606 (<type>size_t</type>) 2607 <literal>r-</literal> 2608 [<option>--enable-stats</option>] 2609 </term> 2610 <listitem><para>Total number of bytes in virtual memory mappings that 2611 were retained rather than being returned to the operating system via 2612 e.g. <citerefentry><refentrytitle>munmap</refentrytitle> 2613 <manvolnum>2</manvolnum></citerefentry> or similar. Retained virtual 2614 memory is typically untouched, decommitted, or purged, so it has no 2615 strongly associated physical memory (see <link 2616 linkend="arena.i.extent_hooks">extent hooks</link> for details). 2617 Retained memory is excluded from mapped memory statistics, e.g. <link 2618 linkend="stats.mapped"><mallctl>stats.mapped</mallctl></link>. 2619 </para></listitem> 2620 </varlistentry> 2621 2622 <varlistentry id="stats.zero_reallocs"> 2623 <term> 2624 <mallctl>stats.zero_reallocs</mallctl> 2625 (<type>size_t</type>) 2626 <literal>r-</literal> 2627 [<option>--enable-stats</option>] 2628 </term> 2629 <listitem><para>Number of times that the <function>realloc()</function> 2630 was called with a non-<constant>NULL</constant> pointer argument and a 2631 <constant>0</constant> size argument. This is a fundamentally unsafe 2632 pattern in portable programs; see <link linkend="opt.zero_realloc"> 2633 <mallctl>opt.zero_realloc</mallctl></link> for details. 2634 </para></listitem> 2635 </varlistentry> 2636 2637 <varlistentry id="stats.background_thread.num_threads"> 2638 <term> 2639 <mallctl>stats.background_thread.num_threads</mallctl> 2640 (<type>size_t</type>) 2641 <literal>r-</literal> 2642 [<option>--enable-stats</option>] 2643 </term> 2644 <listitem><para> Number of <link linkend="background_thread">background 2645 threads</link> running currently.</para></listitem> 2646 </varlistentry> 2647 2648 <varlistentry id="stats.background_thread.num_runs"> 2649 <term> 2650 <mallctl>stats.background_thread.num_runs</mallctl> 2651 (<type>uint64_t</type>) 2652 <literal>r-</literal> 2653 [<option>--enable-stats</option>] 2654 </term> 2655 <listitem><para> Total number of runs from all <link 2656 linkend="background_thread">background threads</link>.</para></listitem> 2657 </varlistentry> 2658 2659 <varlistentry id="stats.background_thread.run_interval"> 2660 <term> 2661 <mallctl>stats.background_thread.run_interval</mallctl> 2662 (<type>uint64_t</type>) 2663 <literal>r-</literal> 2664 [<option>--enable-stats</option>] 2665 </term> 2666 <listitem><para> Average run interval in nanoseconds of <link 2667 linkend="background_thread">background threads</link>.</para></listitem> 2668 </varlistentry> 2669 2670 <varlistentry id="stats.mutexes.ctl"> 2671 <term> 2672 <mallctl>stats.mutexes.ctl.{counter};</mallctl> 2673 (<type>counter specific type</type>) 2674 <literal>r-</literal> 2675 [<option>--enable-stats</option>] 2676 </term> 2677 <listitem><para>Statistics on <varname>ctl</varname> mutex (global 2678 scope; mallctl related). <mallctl>{counter}</mallctl> is one of the 2679 counters below:</para> 2680 <varlistentry id="mutex_counters"> 2681 <listitem><para><varname>num_ops</varname> (<type>uint64_t</type>): 2682 Total number of lock acquisition operations on this mutex.</para> 2683 2684 <para><varname>num_spin_acq</varname> (<type>uint64_t</type>): Number 2685 of times the mutex was spin-acquired. When the mutex is currently 2686 locked and cannot be acquired immediately, a short period of 2687 spin-retry within jemalloc will be performed. Acquired through spin 2688 generally means the contention was lightweight and not causing context 2689 switches.</para> 2690 2691 <para><varname>num_wait</varname> (<type>uint64_t</type>): Number of 2692 times the mutex was wait-acquired, which means the mutex contention 2693 was not solved by spin-retry, and blocking operation was likely 2694 involved in order to acquire the mutex. This event generally implies 2695 higher cost / longer delay, and should be investigated if it happens 2696 often.</para> 2697 2698 <para><varname>max_wait_time</varname> (<type>uint64_t</type>): 2699 Maximum length of time in nanoseconds spent on a single wait-acquired 2700 lock operation. Note that to avoid profiling overhead on the common 2701 path, this does not consider spin-acquired cases.</para> 2702 2703 <para><varname>total_wait_time</varname> (<type>uint64_t</type>): 2704 Cumulative time in nanoseconds spent on wait-acquired lock operations. 2705 Similarly, spin-acquired cases are not considered.</para> 2706 2707 <para><varname>max_num_thds</varname> (<type>uint32_t</type>): Maximum 2708 number of threads waiting on this mutex simultaneously. Similarly, 2709 spin-acquired cases are not considered.</para> 2710 2711 <para><varname>num_owner_switch</varname> (<type>uint64_t</type>): 2712 Number of times the current mutex owner is different from the previous 2713 one. This event does not generally imply an issue; rather it is an 2714 indicator of how often the protected data are accessed by different 2715 threads. 2716 </para> 2717 </listitem> 2718 </varlistentry> 2719 </listitem> 2720 </varlistentry> 2721 2722 <varlistentry id="stats.mutexes.background_thread"> 2723 <term> 2724 <mallctl>stats.mutexes.background_thread.{counter}</mallctl> 2725 (<type>counter specific type</type>) <literal>r-</literal> 2726 [<option>--enable-stats</option>] 2727 </term> 2728 <listitem><para>Statistics on <varname>background_thread</varname> mutex 2729 (global scope; <link 2730 linkend="background_thread"><mallctl>background_thread</mallctl></link> 2731 related). <mallctl>{counter}</mallctl> is one of the counters in <link 2732 linkend="mutex_counters">mutex profiling 2733 counters</link>.</para></listitem> 2734 </varlistentry> 2735 2736 <varlistentry id="stats.mutexes.prof"> 2737 <term> 2738 <mallctl>stats.mutexes.prof.{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> mutex (global 2743 scope; profiling related). <mallctl>{counter}</mallctl> is one of the 2744 counters in <link linkend="mutex_counters">mutex profiling 2745 counters</link>.</para></listitem> 2746 </varlistentry> 2747 2748 <varlistentry id="stats.mutexes.prof_thds_data"> 2749 <term> 2750 <mallctl>stats.mutexes.prof_thds_data.{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> threads data 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.prof_dump"> 2761 <term> 2762 <mallctl>stats.mutexes.prof_dump.{counter}</mallctl> 2763 (<type>counter specific type</type>) <literal>r-</literal> 2764 [<option>--enable-stats</option>] 2765 </term> 2766 <listitem><para>Statistics on <varname>prof</varname> dumping mutex 2767 (global scope; profiling related). <mallctl>{counter}</mallctl> is one 2768 of the counters in <link linkend="mutex_counters">mutex profiling 2769 counters</link>.</para></listitem> 2770 </varlistentry> 2771 2772 <varlistentry id="stats.mutexes.reset"> 2773 <term> 2774 <mallctl>stats.mutexes.reset</mallctl> 2775 (<type>void</type>) <literal>--</literal> 2776 [<option>--enable-stats</option>] 2777 </term> 2778 <listitem><para>Reset all mutex profile statistics, including global 2779 mutexes, arena mutexes and bin mutexes.</para></listitem> 2780 </varlistentry> 2781 2782 <varlistentry id="stats.arenas.i.dss"> 2783 <term> 2784 <mallctl>stats.arenas.<i>.dss</mallctl> 2785 (<type>const char *</type>) 2786 <literal>r-</literal> 2787 </term> 2788 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 2789 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 2790 related to <citerefentry><refentrytitle>mmap</refentrytitle> 2791 <manvolnum>2</manvolnum></citerefentry> allocation. See <link 2792 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for details. 2793 </para></listitem> 2794 </varlistentry> 2795 2796 <varlistentry id="stats.arenas.i.dirty_decay_ms"> 2797 <term> 2798 <mallctl>stats.arenas.<i>.dirty_decay_ms</mallctl> 2799 (<type>ssize_t</type>) 2800 <literal>r-</literal> 2801 </term> 2802 <listitem><para>Approximate time in milliseconds from the creation of a 2803 set of unused dirty pages until an equivalent set of unused dirty pages 2804 is purged and/or reused. See <link 2805 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2806 for details.</para></listitem> 2807 </varlistentry> 2808 2809 <varlistentry id="stats.arenas.i.muzzy_decay_ms"> 2810 <term> 2811 <mallctl>stats.arenas.<i>.muzzy_decay_ms</mallctl> 2812 (<type>ssize_t</type>) 2813 <literal>r-</literal> 2814 </term> 2815 <listitem><para>Approximate time in milliseconds from the creation of a 2816 set of unused muzzy pages until an equivalent set of unused muzzy pages 2817 is purged and/or reused. See <link 2818 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2819 for details.</para></listitem> 2820 </varlistentry> 2821 2822 <varlistentry id="stats.arenas.i.nthreads"> 2823 <term> 2824 <mallctl>stats.arenas.<i>.nthreads</mallctl> 2825 (<type>unsigned</type>) 2826 <literal>r-</literal> 2827 </term> 2828 <listitem><para>Number of threads currently assigned to 2829 arena.</para></listitem> 2830 </varlistentry> 2831 2832 <varlistentry id="stats.arenas.i.uptime"> 2833 <term> 2834 <mallctl>stats.arenas.<i>.uptime</mallctl> 2835 (<type>uint64_t</type>) 2836 <literal>r-</literal> 2837 </term> 2838 <listitem><para>Time elapsed (in nanoseconds) since the arena was 2839 created. If <i> equals <constant>0</constant> or 2840 <constant>MALLCTL_ARENAS_ALL</constant>, this is the uptime since malloc 2841 initialization.</para></listitem> 2842 </varlistentry> 2843 2844 <varlistentry id="stats.arenas.i.pactive"> 2845 <term> 2846 <mallctl>stats.arenas.<i>.pactive</mallctl> 2847 (<type>size_t</type>) 2848 <literal>r-</literal> 2849 </term> 2850 <listitem><para>Number of pages in active extents.</para></listitem> 2851 </varlistentry> 2852 2853 <varlistentry id="stats.arenas.i.pdirty"> 2854 <term> 2855 <mallctl>stats.arenas.<i>.pdirty</mallctl> 2856 (<type>size_t</type>) 2857 <literal>r-</literal> 2858 </term> 2859 <listitem><para>Number of pages within unused extents that are 2860 potentially dirty, and for which <function>madvise()</function> or 2861 similar has not been called. See <link 2862 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 2863 for a description of dirty pages.</para></listitem> 2864 </varlistentry> 2865 2866 <varlistentry id="stats.arenas.i.pmuzzy"> 2867 <term> 2868 <mallctl>stats.arenas.<i>.pmuzzy</mallctl> 2869 (<type>size_t</type>) 2870 <literal>r-</literal> 2871 </term> 2872 <listitem><para>Number of pages within unused extents that are muzzy. 2873 See <link 2874 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 2875 for a description of muzzy pages.</para></listitem> 2876 </varlistentry> 2877 2878 <varlistentry id="stats.arenas.i.mapped"> 2879 <term> 2880 <mallctl>stats.arenas.<i>.mapped</mallctl> 2881 (<type>size_t</type>) 2882 <literal>r-</literal> 2883 [<option>--enable-stats</option>] 2884 </term> 2885 <listitem><para>Number of mapped bytes.</para></listitem> 2886 </varlistentry> 2887 2888 <varlistentry id="stats.arenas.i.retained"> 2889 <term> 2890 <mallctl>stats.arenas.<i>.retained</mallctl> 2891 (<type>size_t</type>) 2892 <literal>r-</literal> 2893 [<option>--enable-stats</option>] 2894 </term> 2895 <listitem><para>Number of retained bytes. See <link 2896 linkend="stats.retained"><mallctl>stats.retained</mallctl></link> for 2897 details.</para></listitem> 2898 </varlistentry> 2899 2900 <varlistentry id="stats.arenas.i.extent_avail"> 2901 <term> 2902 <mallctl>stats.arenas.<i>.extent_avail</mallctl> 2903 (<type>size_t</type>) 2904 <literal>r-</literal> 2905 [<option>--enable-stats</option>] 2906 </term> 2907 <listitem><para>Number of allocated (but unused) extent structs in this 2908 arena.</para></listitem> 2909 </varlistentry> 2910 2911 <varlistentry id="stats.arenas.i.base"> 2912 <term> 2913 <mallctl>stats.arenas.<i>.base</mallctl> 2914 (<type>size_t</type>) 2915 <literal>r-</literal> 2916 [<option>--enable-stats</option>] 2917 </term> 2918 <listitem><para> 2919 Number of bytes dedicated to bootstrap-sensitive allocator metadata 2920 structures.</para></listitem> 2921 </varlistentry> 2922 2923 <varlistentry id="stats.arenas.i.internal"> 2924 <term> 2925 <mallctl>stats.arenas.<i>.internal</mallctl> 2926 (<type>size_t</type>) 2927 <literal>r-</literal> 2928 [<option>--enable-stats</option>] 2929 </term> 2930 <listitem><para>Number of bytes dedicated to internal allocations. 2931 Internal allocations differ from application-originated allocations in 2932 that they are for internal use, and that they are omitted from heap 2933 profiles.</para></listitem> 2934 </varlistentry> 2935 2936 <varlistentry id="stats.arenas.i.metadata_thp"> 2937 <term> 2938 <mallctl>stats.arenas.<i>.metadata_thp</mallctl> 2939 (<type>size_t</type>) 2940 <literal>r-</literal> 2941 [<option>--enable-stats</option>] 2942 </term> 2943 <listitem><para>Number of transparent huge pages (THP) used for 2944 metadata. See <link linkend="opt.metadata_thp">opt.metadata_thp</link> 2945 for details.</para></listitem> 2946 </varlistentry> 2947 2948 <varlistentry id="stats.arenas.i.resident"> 2949 <term> 2950 <mallctl>stats.arenas.<i>.resident</mallctl> 2951 (<type>size_t</type>) 2952 <literal>r-</literal> 2953 [<option>--enable-stats</option>] 2954 </term> 2955 <listitem><para>Maximum number of bytes in physically resident data 2956 pages mapped by the arena, comprising all pages dedicated to allocator 2957 metadata, pages backing active allocations, and unused dirty pages. 2958 This is a maximum rather than precise because pages may not actually be 2959 physically resident if they correspond to demand-zeroed virtual memory 2960 that has not yet been touched. This is a multiple of the page 2961 size.</para></listitem> 2962 </varlistentry> 2963 2964 <varlistentry id="stats.arenas.i.dirty_npurge"> 2965 <term> 2966 <mallctl>stats.arenas.<i>.dirty_npurge</mallctl> 2967 (<type>uint64_t</type>) 2968 <literal>r-</literal> 2969 [<option>--enable-stats</option>] 2970 </term> 2971 <listitem><para>Number of dirty page purge sweeps performed. 2972 </para></listitem> 2973 </varlistentry> 2974 2975 <varlistentry id="stats.arenas.i.dirty_nmadvise"> 2976 <term> 2977 <mallctl>stats.arenas.<i>.dirty_nmadvise</mallctl> 2978 (<type>uint64_t</type>) 2979 <literal>r-</literal> 2980 [<option>--enable-stats</option>] 2981 </term> 2982 <listitem><para>Number of <function>madvise()</function> or similar 2983 calls made to purge dirty pages.</para></listitem> 2984 </varlistentry> 2985 2986 <varlistentry id="stats.arenas.i.dirty_purged"> 2987 <term> 2988 <mallctl>stats.arenas.<i>.dirty_purged</mallctl> 2989 (<type>uint64_t</type>) 2990 <literal>r-</literal> 2991 [<option>--enable-stats</option>] 2992 </term> 2993 <listitem><para>Number of dirty pages purged.</para></listitem> 2994 </varlistentry> 2995 2996 <varlistentry id="stats.arenas.i.muzzy_npurge"> 2997 <term> 2998 <mallctl>stats.arenas.<i>.muzzy_npurge</mallctl> 2999 (<type>uint64_t</type>) 3000 <literal>r-</literal> 3001 [<option>--enable-stats</option>] 3002 </term> 3003 <listitem><para>Number of muzzy page purge sweeps performed. 3004 </para></listitem> 3005 </varlistentry> 3006 3007 <varlistentry id="stats.arenas.i.muzzy_nmadvise"> 3008 <term> 3009 <mallctl>stats.arenas.<i>.muzzy_nmadvise</mallctl> 3010 (<type>uint64_t</type>) 3011 <literal>r-</literal> 3012 [<option>--enable-stats</option>] 3013 </term> 3014 <listitem><para>Number of <function>madvise()</function> or similar 3015 calls made to purge muzzy pages.</para></listitem> 3016 </varlistentry> 3017 3018 <varlistentry id="stats.arenas.i.muzzy_purged"> 3019 <term> 3020 <mallctl>stats.arenas.<i>.muzzy_purged</mallctl> 3021 (<type>uint64_t</type>) 3022 <literal>r-</literal> 3023 [<option>--enable-stats</option>] 3024 </term> 3025 <listitem><para>Number of muzzy pages purged.</para></listitem> 3026 </varlistentry> 3027 3028 <varlistentry id="stats.arenas.i.small.allocated"> 3029 <term> 3030 <mallctl>stats.arenas.<i>.small.allocated</mallctl> 3031 (<type>size_t</type>) 3032 <literal>r-</literal> 3033 [<option>--enable-stats</option>] 3034 </term> 3035 <listitem><para>Number of bytes currently allocated by small objects. 3036 </para></listitem> 3037 </varlistentry> 3038 3039 <varlistentry id="stats.arenas.i.small.nmalloc"> 3040 <term> 3041 <mallctl>stats.arenas.<i>.small.nmalloc</mallctl> 3042 (<type>uint64_t</type>) 3043 <literal>r-</literal> 3044 [<option>--enable-stats</option>] 3045 </term> 3046 <listitem><para>Cumulative number of times a small allocation was 3047 requested from the arena's bins, whether to fill the relevant tcache if 3048 <link linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is 3049 enabled, or to directly satisfy an allocation request 3050 otherwise.</para></listitem> 3051 </varlistentry> 3052 3053 <varlistentry id="stats.arenas.i.small.ndalloc"> 3054 <term> 3055 <mallctl>stats.arenas.<i>.small.ndalloc</mallctl> 3056 (<type>uint64_t</type>) 3057 <literal>r-</literal> 3058 [<option>--enable-stats</option>] 3059 </term> 3060 <listitem><para>Cumulative number of times a small allocation was 3061 returned to the arena's bins, whether to flush the relevant tcache if 3062 <link linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is 3063 enabled, or to directly deallocate an allocation 3064 otherwise.</para></listitem> 3065 </varlistentry> 3066 3067 <varlistentry id="stats.arenas.i.small.nrequests"> 3068 <term> 3069 <mallctl>stats.arenas.<i>.small.nrequests</mallctl> 3070 (<type>uint64_t</type>) 3071 <literal>r-</literal> 3072 [<option>--enable-stats</option>] 3073 </term> 3074 <listitem><para>Cumulative number of allocation requests satisfied by 3075 all bin size classes.</para></listitem> 3076 </varlistentry> 3077 3078 <varlistentry id="stats.arenas.i.small.nfills"> 3079 <term> 3080 <mallctl>stats.arenas.<i>.small.nfills</mallctl> 3081 (<type>uint64_t</type>) 3082 <literal>r-</literal> 3083 [<option>--enable-stats</option>] 3084 </term> 3085 <listitem><para>Cumulative number of tcache fills by all small size 3086 classes.</para></listitem> 3087 </varlistentry> 3088 3089 <varlistentry id="stats.arenas.i.small.nflushes"> 3090 <term> 3091 <mallctl>stats.arenas.<i>.small.nflushes</mallctl> 3092 (<type>uint64_t</type>) 3093 <literal>r-</literal> 3094 [<option>--enable-stats</option>] 3095 </term> 3096 <listitem><para>Cumulative number of tcache flushes by all small size 3097 classes.</para></listitem> 3098 </varlistentry> 3099 3100 <varlistentry id="stats.arenas.i.large.allocated"> 3101 <term> 3102 <mallctl>stats.arenas.<i>.large.allocated</mallctl> 3103 (<type>size_t</type>) 3104 <literal>r-</literal> 3105 [<option>--enable-stats</option>] 3106 </term> 3107 <listitem><para>Number of bytes currently allocated by large objects. 3108 </para></listitem> 3109 </varlistentry> 3110 3111 <varlistentry id="stats.arenas.i.large.nmalloc"> 3112 <term> 3113 <mallctl>stats.arenas.<i>.large.nmalloc</mallctl> 3114 (<type>uint64_t</type>) 3115 <literal>r-</literal> 3116 [<option>--enable-stats</option>] 3117 </term> 3118 <listitem><para>Cumulative number of times a large extent was allocated 3119 from the arena, whether to fill the relevant tcache if <link 3120 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3121 the size class is within the range being cached, or to directly satisfy 3122 an allocation request otherwise.</para></listitem> 3123 </varlistentry> 3124 3125 <varlistentry id="stats.arenas.i.large.ndalloc"> 3126 <term> 3127 <mallctl>stats.arenas.<i>.large.ndalloc</mallctl> 3128 (<type>uint64_t</type>) 3129 <literal>r-</literal> 3130 [<option>--enable-stats</option>] 3131 </term> 3132 <listitem><para>Cumulative number of times a large extent was returned 3133 to the arena, whether to flush the relevant tcache if <link 3134 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3135 the size class is within the range being cached, or to directly 3136 deallocate an allocation otherwise.</para></listitem> 3137 </varlistentry> 3138 3139 <varlistentry id="stats.arenas.i.large.nrequests"> 3140 <term> 3141 <mallctl>stats.arenas.<i>.large.nrequests</mallctl> 3142 (<type>uint64_t</type>) 3143 <literal>r-</literal> 3144 [<option>--enable-stats</option>] 3145 </term> 3146 <listitem><para>Cumulative number of allocation requests satisfied by 3147 all large size classes.</para></listitem> 3148 </varlistentry> 3149 3150 <varlistentry id="stats.arenas.i.large.nfills"> 3151 <term> 3152 <mallctl>stats.arenas.<i>.large.nfills</mallctl> 3153 (<type>uint64_t</type>) 3154 <literal>r-</literal> 3155 [<option>--enable-stats</option>] 3156 </term> 3157 <listitem><para>Cumulative number of tcache fills by all large size 3158 classes.</para></listitem> 3159 </varlistentry> 3160 3161 <varlistentry id="stats.arenas.i.large.nflushes"> 3162 <term> 3163 <mallctl>stats.arenas.<i>.large.nflushes</mallctl> 3164 (<type>uint64_t</type>) 3165 <literal>r-</literal> 3166 [<option>--enable-stats</option>] 3167 </term> 3168 <listitem><para>Cumulative number of tcache flushes by all large size 3169 classes.</para></listitem> 3170 </varlistentry> 3171 3172 <varlistentry id="stats.arenas.i.bins.j.nmalloc"> 3173 <term> 3174 <mallctl>stats.arenas.<i>.bins.<j>.nmalloc</mallctl> 3175 (<type>uint64_t</type>) 3176 <literal>r-</literal> 3177 [<option>--enable-stats</option>] 3178 </term> 3179 <listitem><para>Cumulative number of times a bin region of the 3180 corresponding size class was allocated from the arena, whether to fill 3181 the relevant tcache if <link 3182 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled, or 3183 to directly satisfy an allocation request otherwise.</para></listitem> 3184 </varlistentry> 3185 3186 <varlistentry id="stats.arenas.i.bins.j.ndalloc"> 3187 <term> 3188 <mallctl>stats.arenas.<i>.bins.<j>.ndalloc</mallctl> 3189 (<type>uint64_t</type>) 3190 <literal>r-</literal> 3191 [<option>--enable-stats</option>] 3192 </term> 3193 <listitem><para>Cumulative number of times a bin region of the 3194 corresponding size class was returned to the arena, whether to flush the 3195 relevant tcache if <link 3196 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled, or 3197 to directly deallocate an allocation otherwise.</para></listitem> 3198 </varlistentry> 3199 3200 <varlistentry id="stats.arenas.i.bins.j.nrequests"> 3201 <term> 3202 <mallctl>stats.arenas.<i>.bins.<j>.nrequests</mallctl> 3203 (<type>uint64_t</type>) 3204 <literal>r-</literal> 3205 [<option>--enable-stats</option>] 3206 </term> 3207 <listitem><para>Cumulative number of allocation requests satisfied by 3208 bin regions of the corresponding size class.</para></listitem> 3209 </varlistentry> 3210 3211 <varlistentry id="stats.arenas.i.bins.j.curregs"> 3212 <term> 3213 <mallctl>stats.arenas.<i>.bins.<j>.curregs</mallctl> 3214 (<type>size_t</type>) 3215 <literal>r-</literal> 3216 [<option>--enable-stats</option>] 3217 </term> 3218 <listitem><para>Current number of regions for this size 3219 class.</para></listitem> 3220 </varlistentry> 3221 3222 <varlistentry id="stats.arenas.i.bins.j.nfills"> 3223 <term> 3224 <mallctl>stats.arenas.<i>.bins.<j>.nfills</mallctl> 3225 (<type>uint64_t</type>) 3226 <literal>r-</literal> 3227 </term> 3228 <listitem><para>Cumulative number of tcache fills.</para></listitem> 3229 </varlistentry> 3230 3231 <varlistentry id="stats.arenas.i.bins.j.nflushes"> 3232 <term> 3233 <mallctl>stats.arenas.<i>.bins.<j>.nflushes</mallctl> 3234 (<type>uint64_t</type>) 3235 <literal>r-</literal> 3236 </term> 3237 <listitem><para>Cumulative number of tcache flushes.</para></listitem> 3238 </varlistentry> 3239 3240 <varlistentry id="stats.arenas.i.bins.j.nslabs"> 3241 <term> 3242 <mallctl>stats.arenas.<i>.bins.<j>.nslabs</mallctl> 3243 (<type>uint64_t</type>) 3244 <literal>r-</literal> 3245 [<option>--enable-stats</option>] 3246 </term> 3247 <listitem><para>Cumulative number of slabs created.</para></listitem> 3248 </varlistentry> 3249 3250 <varlistentry id="stats.arenas.i.bins.j.nreslabs"> 3251 <term> 3252 <mallctl>stats.arenas.<i>.bins.<j>.nreslabs</mallctl> 3253 (<type>uint64_t</type>) 3254 <literal>r-</literal> 3255 [<option>--enable-stats</option>] 3256 </term> 3257 <listitem><para>Cumulative number of times the current slab from which 3258 to allocate changed.</para></listitem> 3259 </varlistentry> 3260 3261 <varlistentry id="stats.arenas.i.bins.j.curslabs"> 3262 <term> 3263 <mallctl>stats.arenas.<i>.bins.<j>.curslabs</mallctl> 3264 (<type>size_t</type>) 3265 <literal>r-</literal> 3266 [<option>--enable-stats</option>] 3267 </term> 3268 <listitem><para>Current number of slabs.</para></listitem> 3269 </varlistentry> 3270 3271 3272 <varlistentry id="stats.arenas.i.bins.j.nonfull_slabs"> 3273 <term> 3274 <mallctl>stats.arenas.<i>.bins.<j>.nonfull_slabs</mallctl> 3275 (<type>size_t</type>) 3276 <literal>r-</literal> 3277 [<option>--enable-stats</option>] 3278 </term> 3279 <listitem><para>Current number of nonfull slabs.</para></listitem> 3280 </varlistentry> 3281 3282 <varlistentry id="stats.arenas.i.bins.mutex"> 3283 <term> 3284 <mallctl>stats.arenas.<i>.bins.<j>.mutex.{counter}</mallctl> 3285 (<type>counter specific type</type>) <literal>r-</literal> 3286 [<option>--enable-stats</option>] 3287 </term> 3288 <listitem><para>Statistics on 3289 <varname>arena.<i>.bins.<j></varname> mutex (arena bin 3290 scope; bin operation related). <mallctl>{counter}</mallctl> is one of 3291 the counters in <link linkend="mutex_counters">mutex profiling 3292 counters</link>.</para></listitem> 3293 </varlistentry> 3294 3295 <varlistentry id="stats.arenas.i.extents.n"> 3296 <term> 3297 <mallctl>stats.arenas.<i>.extents.<j>.n{extent_type}</mallctl> 3298 (<type>size_t</type>) 3299 <literal>r-</literal> 3300 [<option>--enable-stats</option>] 3301 </term> 3302 <listitem><para> Number of extents of the given type in this arena in 3303 the bucket corresponding to page size index <j>. The extent type 3304 is one of dirty, muzzy, or retained.</para></listitem> 3305 </varlistentry> 3306 3307 <varlistentry id="stats.arenas.i.extents.bytes"> 3308 <term> 3309 <mallctl>stats.arenas.<i>.extents.<j>.{extent_type}_bytes</mallctl> 3310 (<type>size_t</type>) 3311 <literal>r-</literal> 3312 [<option>--enable-stats</option>] 3313 </term> 3314 <listitem><para> Sum of the bytes managed by extents of the given type 3315 in this arena in the bucket corresponding to page size index <j>. 3316 The extent type is one of dirty, muzzy, or retained.</para></listitem> 3317 </varlistentry> 3318 3319 <varlistentry id="stats.arenas.i.lextents.j.nmalloc"> 3320 <term> 3321 <mallctl>stats.arenas.<i>.lextents.<j>.nmalloc</mallctl> 3322 (<type>uint64_t</type>) 3323 <literal>r-</literal> 3324 [<option>--enable-stats</option>] 3325 </term> 3326 <listitem><para>Cumulative number of times a large extent of the 3327 corresponding size class was allocated from the arena, whether to fill 3328 the relevant tcache if <link 3329 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3330 the size class is within the range being cached, or to directly satisfy 3331 an allocation request otherwise.</para></listitem> 3332 </varlistentry> 3333 3334 <varlistentry id="stats.arenas.i.lextents.j.ndalloc"> 3335 <term> 3336 <mallctl>stats.arenas.<i>.lextents.<j>.ndalloc</mallctl> 3337 (<type>uint64_t</type>) 3338 <literal>r-</literal> 3339 [<option>--enable-stats</option>] 3340 </term> 3341 <listitem><para>Cumulative number of times a large extent of the 3342 corresponding size class was returned to the arena, whether to flush the 3343 relevant tcache if <link 3344 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 3345 the size class is within the range being cached, or to directly 3346 deallocate an allocation otherwise.</para></listitem> 3347 </varlistentry> 3348 3349 <varlistentry id="stats.arenas.i.lextents.j.nrequests"> 3350 <term> 3351 <mallctl>stats.arenas.<i>.lextents.<j>.nrequests</mallctl> 3352 (<type>uint64_t</type>) 3353 <literal>r-</literal> 3354 [<option>--enable-stats</option>] 3355 </term> 3356 <listitem><para>Cumulative number of allocation requests satisfied by 3357 large extents of the corresponding size class.</para></listitem> 3358 </varlistentry> 3359 3360 <varlistentry id="stats.arenas.i.lextents.j.curlextents"> 3361 <term> 3362 <mallctl>stats.arenas.<i>.lextents.<j>.curlextents</mallctl> 3363 (<type>size_t</type>) 3364 <literal>r-</literal> 3365 [<option>--enable-stats</option>] 3366 </term> 3367 <listitem><para>Current number of large allocations for this size class. 3368 </para></listitem> 3369 </varlistentry> 3370 3371 <varlistentry id="stats.arenas.i.mutexes.large"> 3372 <term> 3373 <mallctl>stats.arenas.<i>.mutexes.large.{counter}</mallctl> 3374 (<type>counter specific type</type>) <literal>r-</literal> 3375 [<option>--enable-stats</option>] 3376 </term> 3377 <listitem><para>Statistics on <varname>arena.<i>.large</varname> 3378 mutex (arena scope; large allocation related). 3379 <mallctl>{counter}</mallctl> is one of the counters in <link 3380 linkend="mutex_counters">mutex profiling 3381 counters</link>.</para></listitem> 3382 </varlistentry> 3383 3384 <varlistentry id="stats.arenas.i.mutexes.extent_avail"> 3385 <term> 3386 <mallctl>stats.arenas.<i>.mutexes.extent_avail.{counter}</mallctl> 3387 (<type>counter specific type</type>) <literal>r-</literal> 3388 [<option>--enable-stats</option>] 3389 </term> 3390 <listitem><para>Statistics on <varname>arena.<i>.extent_avail 3391 </varname> mutex (arena scope; extent avail related). 3392 <mallctl>{counter}</mallctl> is one of the counters in <link 3393 linkend="mutex_counters">mutex profiling 3394 counters</link>.</para></listitem> 3395 </varlistentry> 3396 3397 <varlistentry id="stats.arenas.i.mutexes.extents_dirty"> 3398 <term> 3399 <mallctl>stats.arenas.<i>.mutexes.extents_dirty.{counter}</mallctl> 3400 (<type>counter specific type</type>) <literal>r-</literal> 3401 [<option>--enable-stats</option>] 3402 </term> 3403 <listitem><para>Statistics on <varname>arena.<i>.extents_dirty 3404 </varname> mutex (arena scope; dirty extents related). 3405 <mallctl>{counter}</mallctl> is one of the counters in <link 3406 linkend="mutex_counters">mutex profiling 3407 counters</link>.</para></listitem> 3408 </varlistentry> 3409 3410 <varlistentry id="stats.arenas.i.mutexes.extents_muzzy"> 3411 <term> 3412 <mallctl>stats.arenas.<i>.mutexes.extents_muzzy.{counter}</mallctl> 3413 (<type>counter specific type</type>) <literal>r-</literal> 3414 [<option>--enable-stats</option>] 3415 </term> 3416 <listitem><para>Statistics on <varname>arena.<i>.extents_muzzy 3417 </varname> mutex (arena scope; muzzy extents related). 3418 <mallctl>{counter}</mallctl> is one of the counters in <link 3419 linkend="mutex_counters">mutex profiling 3420 counters</link>.</para></listitem> 3421 </varlistentry> 3422 3423 <varlistentry id="stats.arenas.i.mutexes.extents_retained"> 3424 <term> 3425 <mallctl>stats.arenas.<i>.mutexes.extents_retained.{counter}</mallctl> 3426 (<type>counter specific type</type>) <literal>r-</literal> 3427 [<option>--enable-stats</option>] 3428 </term> 3429 <listitem><para>Statistics on <varname>arena.<i>.extents_retained 3430 </varname> mutex (arena scope; retained extents related). 3431 <mallctl>{counter}</mallctl> is one of the counters in <link 3432 linkend="mutex_counters">mutex profiling 3433 counters</link>.</para></listitem> 3434 </varlistentry> 3435 3436 <varlistentry id="stats.arenas.i.mutexes.decay_dirty"> 3437 <term> 3438 <mallctl>stats.arenas.<i>.mutexes.decay_dirty.{counter}</mallctl> 3439 (<type>counter specific type</type>) <literal>r-</literal> 3440 [<option>--enable-stats</option>] 3441 </term> 3442 <listitem><para>Statistics on <varname>arena.<i>.decay_dirty 3443 </varname> mutex (arena scope; decay for dirty pages related). 3444 <mallctl>{counter}</mallctl> is one of the counters in <link 3445 linkend="mutex_counters">mutex profiling 3446 counters</link>.</para></listitem> 3447 </varlistentry> 3448 3449 <varlistentry id="stats.arenas.i.mutexes.decay_muzzy"> 3450 <term> 3451 <mallctl>stats.arenas.<i>.mutexes.decay_muzzy.{counter}</mallctl> 3452 (<type>counter specific type</type>) <literal>r-</literal> 3453 [<option>--enable-stats</option>] 3454 </term> 3455 <listitem><para>Statistics on <varname>arena.<i>.decay_muzzy 3456 </varname> mutex (arena scope; decay for muzzy pages related). 3457 <mallctl>{counter}</mallctl> is one of the counters in <link 3458 linkend="mutex_counters">mutex profiling 3459 counters</link>.</para></listitem> 3460 </varlistentry> 3461 3462 <varlistentry id="stats.arenas.i.mutexes.base"> 3463 <term> 3464 <mallctl>stats.arenas.<i>.mutexes.base.{counter}</mallctl> 3465 (<type>counter specific type</type>) <literal>r-</literal> 3466 [<option>--enable-stats</option>] 3467 </term> 3468 <listitem><para>Statistics on <varname>arena.<i>.base</varname> 3469 mutex (arena scope; base allocator related). 3470 <mallctl>{counter}</mallctl> is one of the counters in <link 3471 linkend="mutex_counters">mutex profiling 3472 counters</link>.</para></listitem> 3473 </varlistentry> 3474 3475 <varlistentry id="stats.arenas.i.mutexes.tcache_list"> 3476 <term> 3477 <mallctl>stats.arenas.<i>.mutexes.tcache_list.{counter}</mallctl> 3478 (<type>counter specific type</type>) <literal>r-</literal> 3479 [<option>--enable-stats</option>] 3480 </term> 3481 <listitem><para>Statistics on 3482 <varname>arena.<i>.tcache_list</varname> mutex (arena scope; 3483 tcache to arena association related). This mutex is expected to be 3484 accessed less often. <mallctl>{counter}</mallctl> is one of the 3485 counters in <link linkend="mutex_counters">mutex profiling 3486 counters</link>.</para></listitem> 3487 </varlistentry> 3488 3489 </variablelist> 3490 </refsect1> 3491 <refsect1 id="heap_profile_format"> 3492 <title>HEAP PROFILE FORMAT</title> 3493 <para>Although the heap profiling functionality was originally designed to 3494 be compatible with the 3495 <command>pprof</command> command that is developed as part of the <ulink 3496 url="http://code.google.com/p/gperftools/">gperftools 3497 package</ulink>, the addition of per thread heap profiling functionality 3498 required a different heap profile format. The <command>jeprof</command> 3499 command is derived from <command>pprof</command>, with enhancements to 3500 support the heap profile format described here.</para> 3501 3502 <para>In the following hypothetical heap profile, <constant>[...]</constant> 3503 indicates elision for the sake of compactness. <programlisting><![CDATA[ 3504heap_v2/524288 3505 t*: 28106: 56637512 [0: 0] 3506 [...] 3507 t3: 352: 16777344 [0: 0] 3508 [...] 3509 t99: 17754: 29341640 [0: 0] 3510 [...] 3511@ 0x5f86da8 0x5f5a1dc [...] 0x29e4d4e 0xa200316 0xabb2988 [...] 3512 t*: 13: 6688 [0: 0] 3513 t3: 12: 6496 [0: 0] 3514 t99: 1: 192 [0: 0] 3515[...] 3516 3517MAPPED_LIBRARIES: 3518[...]]]></programlisting> The following matches the above heap profile, but most 3519tokens are replaced with <constant><description></constant> to indicate 3520descriptions of the corresponding fields. <programlisting><![CDATA[ 3521<heap_profile_format_version>/<mean_sample_interval> 3522 <aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3523 [...] 3524 <thread_3_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3525 [...] 3526 <thread_99_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3527 [...] 3528@ <top_frame> <frame> [...] <frame> <frame> <frame> [...] 3529 <backtrace_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3530 <backtrace_thread_3>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3531 <backtrace_thread_99>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 3532[...] 3533 3534MAPPED_LIBRARIES: 3535</proc/<pid>/maps>]]></programlisting></para> 3536 </refsect1> 3537 3538 <refsect1 id="debugging_malloc_problems"> 3539 <title>DEBUGGING MALLOC PROBLEMS</title> 3540 <para>When debugging, it is a good idea to configure/build jemalloc with 3541 the <option>--enable-debug</option> and <option>--enable-fill</option> 3542 options, and recompile the program with suitable options and symbols for 3543 debugger support. When so configured, jemalloc incorporates a wide variety 3544 of run-time assertions that catch application errors such as double-free, 3545 write-after-free, etc.</para> 3546 3547 <para>Programs often accidentally depend on <quote>uninitialized</quote> 3548 memory actually being filled with zero bytes. Junk filling 3549 (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> 3550 option) tends to expose such bugs in the form of obviously incorrect 3551 results and/or coredumps. Conversely, zero 3552 filling (see the <link 3553 linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates 3554 the symptoms of such bugs. Between these two options, it is usually 3555 possible to quickly detect, diagnose, and eliminate such bugs.</para> 3556 3557 <para>This implementation does not provide much detail about the problems 3558 it detects, because the performance impact for storing such information 3559 would be prohibitive.</para> 3560 </refsect1> 3561 <refsect1 id="diagnostic_messages"> 3562 <title>DIAGNOSTIC MESSAGES</title> 3563 <para>If any of the memory allocation/deallocation functions detect an 3564 error or warning condition, a message will be printed to file descriptor 3565 <constant>STDERR_FILENO</constant>. Errors will result in the process 3566 dumping core. If the <link 3567 linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most 3568 warnings are treated as errors.</para> 3569 3570 <para>The <varname>malloc_message</varname> variable allows the programmer 3571 to override the function which emits the text strings forming the errors 3572 and warnings if for some reason the <constant>STDERR_FILENO</constant> file 3573 descriptor is not suitable for this. 3574 <function>malloc_message()</function> takes the 3575 <parameter>cbopaque</parameter> pointer argument that is 3576 <constant>NULL</constant> unless overridden by the arguments in a call to 3577 <function>malloc_stats_print()</function>, followed by a string 3578 pointer. Please note that doing anything which tries to allocate memory in 3579 this function is likely to result in a crash or deadlock.</para> 3580 3581 <para>All messages are prefixed by 3582 <quote><computeroutput><jemalloc>: </computeroutput></quote>.</para> 3583 </refsect1> 3584 <refsect1 id="return_values"> 3585 <title>RETURN VALUES</title> 3586 <refsect2> 3587 <title>Standard API</title> 3588 <para>The <function>malloc()</function> and 3589 <function>calloc()</function> functions return a pointer to the 3590 allocated memory if successful; otherwise a <constant>NULL</constant> 3591 pointer is returned and <varname>errno</varname> is set to 3592 <errorname>ENOMEM</errorname>.</para> 3593 3594 <para>The <function>posix_memalign()</function> function 3595 returns the value 0 if successful; otherwise it returns an error value. 3596 The <function>posix_memalign()</function> function will fail 3597 if: 3598 <variablelist> 3599 <varlistentry> 3600 <term><errorname>EINVAL</errorname></term> 3601 3602 <listitem><para>The <parameter>alignment</parameter> parameter is 3603 not a power of 2 at least as large as 3604 <code language="C">sizeof(<type>void *</type>)</code>. 3605 </para></listitem> 3606 </varlistentry> 3607 <varlistentry> 3608 <term><errorname>ENOMEM</errorname></term> 3609 3610 <listitem><para>Memory allocation error.</para></listitem> 3611 </varlistentry> 3612 </variablelist> 3613 </para> 3614 3615 <para>The <function>aligned_alloc()</function> function returns 3616 a pointer to the allocated memory if successful; otherwise a 3617 <constant>NULL</constant> pointer is returned and 3618 <varname>errno</varname> is set. The 3619 <function>aligned_alloc()</function> function will fail if: 3620 <variablelist> 3621 <varlistentry> 3622 <term><errorname>EINVAL</errorname></term> 3623 3624 <listitem><para>The <parameter>alignment</parameter> parameter is 3625 not a power of 2. 3626 </para></listitem> 3627 </varlistentry> 3628 <varlistentry> 3629 <term><errorname>ENOMEM</errorname></term> 3630 3631 <listitem><para>Memory allocation error.</para></listitem> 3632 </varlistentry> 3633 </variablelist> 3634 </para> 3635 3636 <para>The <function>realloc()</function> function returns a 3637 pointer, possibly identical to <parameter>ptr</parameter>, to the 3638 allocated memory if successful; otherwise a <constant>NULL</constant> 3639 pointer is returned, and <varname>errno</varname> is set to 3640 <errorname>ENOMEM</errorname> if the error was the result of an 3641 allocation failure. The <function>realloc()</function> 3642 function always leaves the original buffer intact when an error occurs. 3643 </para> 3644 3645 <para>The <function>free()</function> function returns no 3646 value.</para> 3647 </refsect2> 3648 <refsect2> 3649 <title>Non-standard API</title> 3650 <para>The <function>mallocx()</function> and 3651 <function>rallocx()</function> functions return a pointer to 3652 the allocated memory if successful; otherwise a <constant>NULL</constant> 3653 pointer is returned to indicate insufficient contiguous memory was 3654 available to service the allocation request. </para> 3655 3656 <para>The <function>xallocx()</function> function returns the 3657 real size of the resulting resized allocation pointed to by 3658 <parameter>ptr</parameter>, which is a value less than 3659 <parameter>size</parameter> if the allocation could not be adequately 3660 grown in place. </para> 3661 3662 <para>The <function>sallocx()</function> function returns the 3663 real size of the allocation pointed to by <parameter>ptr</parameter>. 3664 </para> 3665 3666 <para>The <function>nallocx()</function> returns the real size 3667 that would result from a successful equivalent 3668 <function>mallocx()</function> function call, or zero if 3669 insufficient memory is available to perform the size computation. </para> 3670 3671 <para>The <function>mallctl()</function>, 3672 <function>mallctlnametomib()</function>, and 3673 <function>mallctlbymib()</function> functions return 0 on 3674 success; otherwise they return an error value. The functions will fail 3675 if: 3676 <variablelist> 3677 <varlistentry> 3678 <term><errorname>EINVAL</errorname></term> 3679 3680 <listitem><para><parameter>newp</parameter> is not 3681 <constant>NULL</constant>, and <parameter>newlen</parameter> is too 3682 large or too small. Alternatively, <parameter>*oldlenp</parameter> 3683 is too large or too small; when it happens, except for a very few 3684 cases explicitly documented otherwise, as much data as possible 3685 are read despite the error, with the amount of data read being 3686 recorded in <parameter>*oldlenp</parameter>.</para></listitem> 3687 </varlistentry> 3688 <varlistentry> 3689 <term><errorname>ENOENT</errorname></term> 3690 3691 <listitem><para><parameter>name</parameter> or 3692 <parameter>mib</parameter> specifies an unknown/invalid 3693 value.</para></listitem> 3694 </varlistentry> 3695 <varlistentry> 3696 <term><errorname>EPERM</errorname></term> 3697 3698 <listitem><para>Attempt to read or write void value, or attempt to 3699 write read-only value.</para></listitem> 3700 </varlistentry> 3701 <varlistentry> 3702 <term><errorname>EAGAIN</errorname></term> 3703 3704 <listitem><para>A memory allocation failure 3705 occurred.</para></listitem> 3706 </varlistentry> 3707 <varlistentry> 3708 <term><errorname>EFAULT</errorname></term> 3709 3710 <listitem><para>An interface with side effects failed in some way 3711 not directly related to <function>mallctl*()</function> 3712 read/write processing.</para></listitem> 3713 </varlistentry> 3714 </variablelist> 3715 </para> 3716 3717 <para>The <function>malloc_usable_size()</function> function 3718 returns the usable size of the allocation pointed to by 3719 <parameter>ptr</parameter>. </para> 3720 </refsect2> 3721 </refsect1> 3722 <refsect1 id="environment"> 3723 <title>ENVIRONMENT</title> 3724 <para>The following environment variable affects the execution of the 3725 allocation functions: 3726 <variablelist> 3727 <varlistentry> 3728 <term><envar>MALLOC_CONF</envar></term> 3729 3730 <listitem><para>If the environment variable 3731 <envar>MALLOC_CONF</envar> is set, the characters it contains 3732 will be interpreted as options.</para></listitem> 3733 </varlistentry> 3734 </variablelist> 3735 </para> 3736 </refsect1> 3737 <refsect1 id="examples"> 3738 <title>EXAMPLES</title> 3739 <para>To dump core whenever a problem occurs: 3740 <screen>ln -s 'abort:true' /etc/malloc.conf</screen> 3741 </para> 3742 <para>To specify in the source that only one arena should be automatically 3743 created: 3744 <programlisting language="C"><![CDATA[ 3745malloc_conf = "narenas:1";]]></programlisting></para> 3746 </refsect1> 3747 <refsect1 id="see_also"> 3748 <title>SEE ALSO</title> 3749 <para><citerefentry><refentrytitle>madvise</refentrytitle> 3750 <manvolnum>2</manvolnum></citerefentry>, 3751 <citerefentry><refentrytitle>mmap</refentrytitle> 3752 <manvolnum>2</manvolnum></citerefentry>, 3753 <citerefentry><refentrytitle>sbrk</refentrytitle> 3754 <manvolnum>2</manvolnum></citerefentry>, 3755 <citerefentry><refentrytitle>utrace</refentrytitle> 3756 <manvolnum>2</manvolnum></citerefentry>, 3757 <citerefentry><refentrytitle>alloca</refentrytitle> 3758 <manvolnum>3</manvolnum></citerefentry>, 3759 <citerefentry><refentrytitle>atexit</refentrytitle> 3760 <manvolnum>3</manvolnum></citerefentry>, 3761 <citerefentry><refentrytitle>getpagesize</refentrytitle> 3762 <manvolnum>3</manvolnum></citerefentry></para> 3763 </refsect1> 3764 <refsect1 id="standards"> 3765 <title>STANDARDS</title> 3766 <para>The <function>malloc()</function>, 3767 <function>calloc()</function>, 3768 <function>realloc()</function>, and 3769 <function>free()</function> functions conform to ISO/IEC 3770 9899:1990 (<quote>ISO C90</quote>).</para> 3771 3772 <para>The <function>posix_memalign()</function> function conforms 3773 to IEEE Std 1003.1-2001 (<quote>POSIX.1</quote>).</para> 3774 </refsect1> 3775 <refsect1 id="history"> 3776 <title>HISTORY</title> 3777 <para>The <function>malloc_usable_size()</function> and 3778 <function>posix_memalign()</function> functions first appeared in FreeBSD 3779 7.0.</para> 3780 3781 <para>The <function>aligned_alloc()</function>, 3782 <function>malloc_stats_print()</function>, and 3783 <function>mallctl*()</function> functions first appeared in FreeBSD 3784 10.0.</para> 3785 3786 <para>The <function>*allocx()</function> functions first appeared in FreeBSD 3787 11.0.</para> 3788 </refsect1> 3789</refentry> 3790||||||| dec341af7695 3791======= 3792<?xml version='1.0' encoding='UTF-8'?> 3793<?xml-stylesheet type="text/xsl" 3794 href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?> 3795<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 3796 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ 3797]> 3798 3799<refentry> 3800 <refentryinfo> 3801 <title>User Manual</title> 3802 <productname>jemalloc</productname> 3803 <releaseinfo role="version">@jemalloc_version@</releaseinfo> 3804 <authorgroup> 3805 <author> 3806 <firstname>Jason</firstname> 3807 <surname>Evans</surname> 3808 <personblurb>Author</personblurb> 3809 </author> 3810 </authorgroup> 3811 </refentryinfo> 3812 <refmeta> 3813 <refentrytitle>JEMALLOC</refentrytitle> 3814 <manvolnum>3</manvolnum> 3815 </refmeta> 3816 <refnamediv> 3817 <refdescriptor>jemalloc</refdescriptor> 3818 <refname>jemalloc</refname> 3819 <!-- Each refname causes a man page file to be created. Only if this were 3820 the system malloc(3) implementation would these files be appropriate. 3821 <refname>malloc</refname> 3822 <refname>calloc</refname> 3823 <refname>posix_memalign</refname> 3824 <refname>aligned_alloc</refname> 3825 <refname>realloc</refname> 3826 <refname>free</refname> 3827 <refname>mallocx</refname> 3828 <refname>rallocx</refname> 3829 <refname>xallocx</refname> 3830 <refname>sallocx</refname> 3831 <refname>dallocx</refname> 3832 <refname>sdallocx</refname> 3833 <refname>nallocx</refname> 3834 <refname>mallctl</refname> 3835 <refname>mallctlnametomib</refname> 3836 <refname>mallctlbymib</refname> 3837 <refname>malloc_stats_print</refname> 3838 <refname>malloc_usable_size</refname> 3839 --> 3840 <refpurpose>general purpose memory allocation functions</refpurpose> 3841 </refnamediv> 3842 <refsect1 id="library"> 3843 <title>LIBRARY</title> 3844 <para>This manual describes jemalloc @jemalloc_version@. More information 3845 can be found at the <ulink 3846 url="http://jemalloc.net/">jemalloc website</ulink>.</para> 3847 3848 <para>The following configuration options are enabled in libc's built-in 3849 jemalloc: <option>--enable-fill</option>, 3850 <option>--enable-lazy-lock</option>, <option>--enable-stats</option>, 3851 <option>--enable-utrace</option>, <option>--enable-xmalloc</option>, and 3852 <option>--with-malloc-conf=abort_conf:false</option>. 3853 Additionally, <option>--enable-debug</option> is enabled in development 3854 versions of FreeBSD (controlled by the 3855 <constant>MK_MALLOC_PRODUCTION</constant> make variable).</para> 3856 3857 </refsect1> 3858 <refsynopsisdiv> 3859 <title>SYNOPSIS</title> 3860 <funcsynopsis> 3861 <funcsynopsisinfo>#include <<filename class="headerfile">stdlib.h</filename>> 3862#include <<filename class="headerfile">malloc_np.h</filename>></funcsynopsisinfo> 3863 <refsect2> 3864 <title>Standard API</title> 3865 <funcprototype> 3866 <funcdef>void *<function>malloc</function></funcdef> 3867 <paramdef>size_t <parameter>size</parameter></paramdef> 3868 </funcprototype> 3869 <funcprototype> 3870 <funcdef>void *<function>calloc</function></funcdef> 3871 <paramdef>size_t <parameter>number</parameter></paramdef> 3872 <paramdef>size_t <parameter>size</parameter></paramdef> 3873 </funcprototype> 3874 <funcprototype> 3875 <funcdef>int <function>posix_memalign</function></funcdef> 3876 <paramdef>void **<parameter>ptr</parameter></paramdef> 3877 <paramdef>size_t <parameter>alignment</parameter></paramdef> 3878 <paramdef>size_t <parameter>size</parameter></paramdef> 3879 </funcprototype> 3880 <funcprototype> 3881 <funcdef>void *<function>aligned_alloc</function></funcdef> 3882 <paramdef>size_t <parameter>alignment</parameter></paramdef> 3883 <paramdef>size_t <parameter>size</parameter></paramdef> 3884 </funcprototype> 3885 <funcprototype> 3886 <funcdef>void *<function>realloc</function></funcdef> 3887 <paramdef>void *<parameter>ptr</parameter></paramdef> 3888 <paramdef>size_t <parameter>size</parameter></paramdef> 3889 </funcprototype> 3890 <funcprototype> 3891 <funcdef>void <function>free</function></funcdef> 3892 <paramdef>void *<parameter>ptr</parameter></paramdef> 3893 </funcprototype> 3894 </refsect2> 3895 <refsect2> 3896 <title>Non-standard API</title> 3897 <funcprototype> 3898 <funcdef>void *<function>mallocx</function></funcdef> 3899 <paramdef>size_t <parameter>size</parameter></paramdef> 3900 <paramdef>int <parameter>flags</parameter></paramdef> 3901 </funcprototype> 3902 <funcprototype> 3903 <funcdef>void *<function>rallocx</function></funcdef> 3904 <paramdef>void *<parameter>ptr</parameter></paramdef> 3905 <paramdef>size_t <parameter>size</parameter></paramdef> 3906 <paramdef>int <parameter>flags</parameter></paramdef> 3907 </funcprototype> 3908 <funcprototype> 3909 <funcdef>size_t <function>xallocx</function></funcdef> 3910 <paramdef>void *<parameter>ptr</parameter></paramdef> 3911 <paramdef>size_t <parameter>size</parameter></paramdef> 3912 <paramdef>size_t <parameter>extra</parameter></paramdef> 3913 <paramdef>int <parameter>flags</parameter></paramdef> 3914 </funcprototype> 3915 <funcprototype> 3916 <funcdef>size_t <function>sallocx</function></funcdef> 3917 <paramdef>void *<parameter>ptr</parameter></paramdef> 3918 <paramdef>int <parameter>flags</parameter></paramdef> 3919 </funcprototype> 3920 <funcprototype> 3921 <funcdef>void <function>dallocx</function></funcdef> 3922 <paramdef>void *<parameter>ptr</parameter></paramdef> 3923 <paramdef>int <parameter>flags</parameter></paramdef> 3924 </funcprototype> 3925 <funcprototype> 3926 <funcdef>void <function>sdallocx</function></funcdef> 3927 <paramdef>void *<parameter>ptr</parameter></paramdef> 3928 <paramdef>size_t <parameter>size</parameter></paramdef> 3929 <paramdef>int <parameter>flags</parameter></paramdef> 3930 </funcprototype> 3931 <funcprototype> 3932 <funcdef>size_t <function>nallocx</function></funcdef> 3933 <paramdef>size_t <parameter>size</parameter></paramdef> 3934 <paramdef>int <parameter>flags</parameter></paramdef> 3935 </funcprototype> 3936 <funcprototype> 3937 <funcdef>int <function>mallctl</function></funcdef> 3938 <paramdef>const char *<parameter>name</parameter></paramdef> 3939 <paramdef>void *<parameter>oldp</parameter></paramdef> 3940 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 3941 <paramdef>void *<parameter>newp</parameter></paramdef> 3942 <paramdef>size_t <parameter>newlen</parameter></paramdef> 3943 </funcprototype> 3944 <funcprototype> 3945 <funcdef>int <function>mallctlnametomib</function></funcdef> 3946 <paramdef>const char *<parameter>name</parameter></paramdef> 3947 <paramdef>size_t *<parameter>mibp</parameter></paramdef> 3948 <paramdef>size_t *<parameter>miblenp</parameter></paramdef> 3949 </funcprototype> 3950 <funcprototype> 3951 <funcdef>int <function>mallctlbymib</function></funcdef> 3952 <paramdef>const size_t *<parameter>mib</parameter></paramdef> 3953 <paramdef>size_t <parameter>miblen</parameter></paramdef> 3954 <paramdef>void *<parameter>oldp</parameter></paramdef> 3955 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 3956 <paramdef>void *<parameter>newp</parameter></paramdef> 3957 <paramdef>size_t <parameter>newlen</parameter></paramdef> 3958 </funcprototype> 3959 <funcprototype> 3960 <funcdef>void <function>malloc_stats_print</function></funcdef> 3961 <paramdef>void <parameter>(*write_cb)</parameter> 3962 <funcparams>void *, const char *</funcparams> 3963 </paramdef> 3964 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 3965 <paramdef>const char *<parameter>opts</parameter></paramdef> 3966 </funcprototype> 3967 <funcprototype> 3968 <funcdef>size_t <function>malloc_usable_size</function></funcdef> 3969 <paramdef>const void *<parameter>ptr</parameter></paramdef> 3970 </funcprototype> 3971 <funcprototype> 3972 <funcdef>void <function>(*malloc_message)</function></funcdef> 3973 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 3974 <paramdef>const char *<parameter>s</parameter></paramdef> 3975 </funcprototype> 3976 <para><type>const char *</type><varname>malloc_conf</varname>;</para> 3977 </refsect2> 3978 </funcsynopsis> 3979 </refsynopsisdiv> 3980 <refsect1 id="description"> 3981 <title>DESCRIPTION</title> 3982 <refsect2> 3983 <title>Standard API</title> 3984 3985 <para>The <function>malloc()</function> function allocates 3986 <parameter>size</parameter> bytes of uninitialized memory. The allocated 3987 space is suitably aligned (after possible pointer coercion) for storage 3988 of any type of object.</para> 3989 3990 <para>The <function>calloc()</function> function allocates 3991 space for <parameter>number</parameter> objects, each 3992 <parameter>size</parameter> bytes in length. The result is identical to 3993 calling <function>malloc()</function> with an argument of 3994 <parameter>number</parameter> * <parameter>size</parameter>, with the 3995 exception that the allocated memory is explicitly initialized to zero 3996 bytes.</para> 3997 3998 <para>The <function>posix_memalign()</function> function 3999 allocates <parameter>size</parameter> bytes of memory such that the 4000 allocation's base address is a multiple of 4001 <parameter>alignment</parameter>, and returns the allocation in the value 4002 pointed to by <parameter>ptr</parameter>. The requested 4003 <parameter>alignment</parameter> must be a power of 2 at least as large as 4004 <code language="C">sizeof(<type>void *</type>)</code>.</para> 4005 4006 <para>The <function>aligned_alloc()</function> function 4007 allocates <parameter>size</parameter> bytes of memory such that the 4008 allocation's base address is a multiple of 4009 <parameter>alignment</parameter>. The requested 4010 <parameter>alignment</parameter> must be a power of 2. Behavior is 4011 undefined if <parameter>size</parameter> is not an integral multiple of 4012 <parameter>alignment</parameter>.</para> 4013 4014 <para>The <function>realloc()</function> function changes the 4015 size of the previously allocated memory referenced by 4016 <parameter>ptr</parameter> to <parameter>size</parameter> bytes. The 4017 contents of the memory are unchanged up to the lesser of the new and old 4018 sizes. If the new size is larger, the contents of the newly allocated 4019 portion of the memory are undefined. Upon success, the memory referenced 4020 by <parameter>ptr</parameter> is freed and a pointer to the newly 4021 allocated memory is returned. Note that 4022 <function>realloc()</function> may move the memory allocation, 4023 resulting in a different return value than <parameter>ptr</parameter>. 4024 If <parameter>ptr</parameter> is <constant>NULL</constant>, the 4025 <function>realloc()</function> function behaves identically to 4026 <function>malloc()</function> for the specified size.</para> 4027 4028 <para>The <function>free()</function> function causes the 4029 allocated memory referenced by <parameter>ptr</parameter> to be made 4030 available for future allocations. If <parameter>ptr</parameter> is 4031 <constant>NULL</constant>, no action occurs.</para> 4032 </refsect2> 4033 <refsect2> 4034 <title>Non-standard API</title> 4035 <para>The <function>mallocx()</function>, 4036 <function>rallocx()</function>, 4037 <function>xallocx()</function>, 4038 <function>sallocx()</function>, 4039 <function>dallocx()</function>, 4040 <function>sdallocx()</function>, and 4041 <function>nallocx()</function> functions all have a 4042 <parameter>flags</parameter> argument that can be used to specify 4043 options. The functions only check the options that are contextually 4044 relevant. Use bitwise or (<code language="C">|</code>) operations to 4045 specify one or more of the following: 4046 <variablelist> 4047 <varlistentry id="MALLOCX_LG_ALIGN"> 4048 <term><constant>MALLOCX_LG_ALIGN(<parameter>la</parameter>) 4049 </constant></term> 4050 4051 <listitem><para>Align the memory allocation to start at an address 4052 that is a multiple of <code language="C">(1 << 4053 <parameter>la</parameter>)</code>. This macro does not validate 4054 that <parameter>la</parameter> is within the valid 4055 range.</para></listitem> 4056 </varlistentry> 4057 <varlistentry id="MALLOCX_ALIGN"> 4058 <term><constant>MALLOCX_ALIGN(<parameter>a</parameter>) 4059 </constant></term> 4060 4061 <listitem><para>Align the memory allocation to start at an address 4062 that is a multiple of <parameter>a</parameter>, where 4063 <parameter>a</parameter> is a power of two. This macro does not 4064 validate that <parameter>a</parameter> is a power of 2. 4065 </para></listitem> 4066 </varlistentry> 4067 <varlistentry id="MALLOCX_ZERO"> 4068 <term><constant>MALLOCX_ZERO</constant></term> 4069 4070 <listitem><para>Initialize newly allocated memory to contain zero 4071 bytes. In the growing reallocation case, the real size prior to 4072 reallocation defines the boundary between untouched bytes and those 4073 that are initialized to contain zero bytes. If this macro is 4074 absent, newly allocated memory is uninitialized.</para></listitem> 4075 </varlistentry> 4076 <varlistentry id="MALLOCX_TCACHE"> 4077 <term><constant>MALLOCX_TCACHE(<parameter>tc</parameter>) 4078 </constant></term> 4079 4080 <listitem><para>Use the thread-specific cache (tcache) specified by 4081 the identifier <parameter>tc</parameter>, which must have been 4082 acquired via the <link 4083 linkend="tcache.create"><mallctl>tcache.create</mallctl></link> 4084 mallctl. This macro does not validate that 4085 <parameter>tc</parameter> specifies a valid 4086 identifier.</para></listitem> 4087 </varlistentry> 4088 <varlistentry id="MALLOC_TCACHE_NONE"> 4089 <term><constant>MALLOCX_TCACHE_NONE</constant></term> 4090 4091 <listitem><para>Do not use a thread-specific cache (tcache). Unless 4092 <constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant> or 4093 <constant>MALLOCX_TCACHE_NONE</constant> is specified, an 4094 automatically managed tcache will be used under many circumstances. 4095 This macro cannot be used in the same <parameter>flags</parameter> 4096 argument as 4097 <constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant>.</para></listitem> 4098 </varlistentry> 4099 <varlistentry id="MALLOCX_ARENA"> 4100 <term><constant>MALLOCX_ARENA(<parameter>a</parameter>) 4101 </constant></term> 4102 4103 <listitem><para>Use the arena specified by the index 4104 <parameter>a</parameter>. This macro has no effect for regions that 4105 were allocated via an arena other than the one specified. This 4106 macro does not validate that <parameter>a</parameter> specifies an 4107 arena index in the valid range.</para></listitem> 4108 </varlistentry> 4109 </variablelist> 4110 </para> 4111 4112 <para>The <function>mallocx()</function> function allocates at 4113 least <parameter>size</parameter> bytes of memory, and returns a pointer 4114 to the base address of the allocation. Behavior is undefined if 4115 <parameter>size</parameter> is <constant>0</constant>.</para> 4116 4117 <para>The <function>rallocx()</function> function resizes the 4118 allocation at <parameter>ptr</parameter> to be at least 4119 <parameter>size</parameter> bytes, and returns a pointer to the base 4120 address of the resulting allocation, which may or may not have moved from 4121 its original location. Behavior is undefined if 4122 <parameter>size</parameter> is <constant>0</constant>.</para> 4123 4124 <para>The <function>xallocx()</function> function resizes the 4125 allocation at <parameter>ptr</parameter> in place to be at least 4126 <parameter>size</parameter> bytes, and returns the real size of the 4127 allocation. If <parameter>extra</parameter> is non-zero, an attempt is 4128 made to resize the allocation to be at least <code 4129 language="C">(<parameter>size</parameter> + 4130 <parameter>extra</parameter>)</code> bytes, though inability to allocate 4131 the extra byte(s) will not by itself result in failure to resize. 4132 Behavior is undefined if <parameter>size</parameter> is 4133 <constant>0</constant>, or if <code 4134 language="C">(<parameter>size</parameter> + <parameter>extra</parameter> 4135 > <constant>SIZE_T_MAX</constant>)</code>.</para> 4136 4137 <para>The <function>sallocx()</function> function returns the 4138 real size of the allocation at <parameter>ptr</parameter>.</para> 4139 4140 <para>The <function>dallocx()</function> function causes the 4141 memory referenced by <parameter>ptr</parameter> to be made available for 4142 future allocations.</para> 4143 4144 <para>The <function>sdallocx()</function> function is an 4145 extension of <function>dallocx()</function> with a 4146 <parameter>size</parameter> parameter to allow the caller to pass in the 4147 allocation size as an optimization. The minimum valid input size is the 4148 original requested size of the allocation, and the maximum valid input 4149 size is the corresponding value returned by 4150 <function>nallocx()</function> or 4151 <function>sallocx()</function>.</para> 4152 4153 <para>The <function>nallocx()</function> function allocates no 4154 memory, but it performs the same size computation as the 4155 <function>mallocx()</function> function, and returns the real 4156 size of the allocation that would result from the equivalent 4157 <function>mallocx()</function> function call, or 4158 <constant>0</constant> if the inputs exceed the maximum supported size 4159 class and/or alignment. Behavior is undefined if 4160 <parameter>size</parameter> is <constant>0</constant>.</para> 4161 4162 <para>The <function>mallctl()</function> function provides a 4163 general interface for introspecting the memory allocator, as well as 4164 setting modifiable parameters and triggering actions. The 4165 period-separated <parameter>name</parameter> argument specifies a 4166 location in a tree-structured namespace; see the <xref 4167 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for 4168 documentation on the tree contents. To read a value, pass a pointer via 4169 <parameter>oldp</parameter> to adequate space to contain the value, and a 4170 pointer to its length via <parameter>oldlenp</parameter>; otherwise pass 4171 <constant>NULL</constant> and <constant>NULL</constant>. Similarly, to 4172 write a value, pass a pointer to the value via 4173 <parameter>newp</parameter>, and its length via 4174 <parameter>newlen</parameter>; otherwise pass <constant>NULL</constant> 4175 and <constant>0</constant>.</para> 4176 4177 <para>The <function>mallctlnametomib()</function> function 4178 provides a way to avoid repeated name lookups for applications that 4179 repeatedly query the same portion of the namespace, by translating a name 4180 to a <quote>Management Information Base</quote> (MIB) that can be passed 4181 repeatedly to <function>mallctlbymib()</function>. Upon 4182 successful return from <function>mallctlnametomib()</function>, 4183 <parameter>mibp</parameter> contains an array of 4184 <parameter>*miblenp</parameter> integers, where 4185 <parameter>*miblenp</parameter> is the lesser of the number of components 4186 in <parameter>name</parameter> and the input value of 4187 <parameter>*miblenp</parameter>. Thus it is possible to pass a 4188 <parameter>*miblenp</parameter> that is smaller than the number of 4189 period-separated name components, which results in a partial MIB that can 4190 be used as the basis for constructing a complete MIB. For name 4191 components that are integers (e.g. the 2 in 4192 <link 4193 linkend="arenas.bin.i.size"><mallctl>arenas.bin.2.size</mallctl></link>), 4194 the corresponding MIB component will always be that integer. Therefore, 4195 it is legitimate to construct code like the following: <programlisting 4196 language="C"><![CDATA[ 4197unsigned nbins, i; 4198size_t mib[4]; 4199size_t len, miblen; 4200 4201len = sizeof(nbins); 4202mallctl("arenas.nbins", &nbins, &len, NULL, 0); 4203 4204miblen = 4; 4205mallctlnametomib("arenas.bin.0.size", mib, &miblen); 4206for (i = 0; i < nbins; i++) { 4207 size_t bin_size; 4208 4209 mib[2] = i; 4210 len = sizeof(bin_size); 4211 mallctlbymib(mib, miblen, (void *)&bin_size, &len, NULL, 0); 4212 /* Do something with bin_size... */ 4213}]]></programlisting></para> 4214 4215 <varlistentry id="malloc_stats_print_opts"> 4216 </varlistentry> 4217 <para>The <function>malloc_stats_print()</function> function writes 4218 summary statistics via the <parameter>write_cb</parameter> callback 4219 function pointer and <parameter>cbopaque</parameter> data passed to 4220 <parameter>write_cb</parameter>, or <function>malloc_message()</function> 4221 if <parameter>write_cb</parameter> is <constant>NULL</constant>. The 4222 statistics are presented in human-readable form unless <quote>J</quote> is 4223 specified as a character within the <parameter>opts</parameter> string, in 4224 which case the statistics are presented in <ulink 4225 url="http://www.json.org/">JSON format</ulink>. This function can be 4226 called repeatedly. General information that never changes during 4227 execution can be omitted by specifying <quote>g</quote> as a character 4228 within the <parameter>opts</parameter> string. Note that 4229 <function>malloc_stats_print()</function> uses the 4230 <function>mallctl*()</function> functions internally, so inconsistent 4231 statistics can be reported if multiple threads use these functions 4232 simultaneously. If <option>--enable-stats</option> is specified during 4233 configuration, <quote>m</quote>, <quote>d</quote>, and <quote>a</quote> 4234 can be specified to omit merged arena, destroyed merged arena, and per 4235 arena statistics, respectively; <quote>b</quote> and <quote>l</quote> can 4236 be specified to omit per size class statistics for bins and large objects, 4237 respectively; <quote>x</quote> can be specified to omit all mutex 4238 statistics; <quote>e</quote> can be used to omit extent statistics. 4239 Unrecognized characters are silently ignored. Note that thread caching 4240 may prevent some statistics from being completely up to date, since extra 4241 locking would be required to merge counters that track thread cache 4242 operations.</para> 4243 4244 <para>The <function>malloc_usable_size()</function> function 4245 returns the usable size of the allocation pointed to by 4246 <parameter>ptr</parameter>. The return value may be larger than the size 4247 that was requested during allocation. The 4248 <function>malloc_usable_size()</function> function is not a 4249 mechanism for in-place <function>realloc()</function>; rather 4250 it is provided solely as a tool for introspection purposes. Any 4251 discrepancy between the requested allocation size and the size reported 4252 by <function>malloc_usable_size()</function> should not be 4253 depended on, since such behavior is entirely implementation-dependent. 4254 </para> 4255 </refsect2> 4256 </refsect1> 4257 <refsect1 id="tuning"> 4258 <title>TUNING</title> 4259 <para>Once, when the first call is made to one of the memory allocation 4260 routines, the allocator initializes its internals based in part on various 4261 options that can be specified at compile- or run-time.</para> 4262 4263 <para>The string specified via <option>--with-malloc-conf</option>, the 4264 string pointed to by the global variable <varname>malloc_conf</varname>, the 4265 <quote>name</quote> of the file referenced by the symbolic link named 4266 <filename class="symlink">/etc/malloc.conf</filename>, and the value of the 4267 environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in 4268 that order, from left to right as options. Note that 4269 <varname>malloc_conf</varname> may be read before 4270 <function>main()</function> is entered, so the declaration of 4271 <varname>malloc_conf</varname> should specify an initializer that contains 4272 the final value to be read by jemalloc. <option>--with-malloc-conf</option> 4273 and <varname>malloc_conf</varname> are compile-time mechanisms, whereas 4274 <filename class="symlink">/etc/malloc.conf</filename> and 4275 <envar>MALLOC_CONF</envar> can be safely set any time prior to program 4276 invocation.</para> 4277 4278 <para>An options string is a comma-separated list of option:value pairs. 4279 There is one key corresponding to each <link 4280 linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the <xref 4281 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for options 4282 documentation). For example, <literal>abort:true,narenas:1</literal> sets 4283 the <link linkend="opt.abort"><mallctl>opt.abort</mallctl></link> and <link 4284 linkend="opt.narenas"><mallctl>opt.narenas</mallctl></link> options. Some 4285 options have boolean values (true/false), others have integer values (base 4286 8, 10, or 16, depending on prefix), and yet others have raw string 4287 values.</para> 4288 </refsect1> 4289 <refsect1 id="implementation_notes"> 4290 <title>IMPLEMENTATION NOTES</title> 4291 <para>Traditionally, allocators have used 4292 <citerefentry><refentrytitle>sbrk</refentrytitle> 4293 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is 4294 suboptimal for several reasons, including race conditions, increased 4295 fragmentation, and artificial limitations on maximum usable memory. If 4296 <citerefentry><refentrytitle>sbrk</refentrytitle> 4297 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 4298 system, this allocator uses both 4299 <citerefentry><refentrytitle>mmap</refentrytitle> 4300 <manvolnum>2</manvolnum></citerefentry> and 4301 <citerefentry><refentrytitle>sbrk</refentrytitle> 4302 <manvolnum>2</manvolnum></citerefentry>, in that order of preference; 4303 otherwise only <citerefentry><refentrytitle>mmap</refentrytitle> 4304 <manvolnum>2</manvolnum></citerefentry> is used.</para> 4305 4306 <para>This allocator uses multiple arenas in order to reduce lock 4307 contention for threaded programs on multi-processor systems. This works 4308 well with regard to threading scalability, but incurs some costs. There is 4309 a small fixed per-arena overhead, and additionally, arenas manage memory 4310 completely independently of each other, which means a small fixed increase 4311 in overall memory fragmentation. These overheads are not generally an 4312 issue, given the number of arenas normally used. Note that using 4313 substantially more arenas than the default is not likely to improve 4314 performance, mainly due to reduced cache performance. However, it may make 4315 sense to reduce the number of arenas if an application does not make much 4316 use of the allocation functions.</para> 4317 4318 <para>In addition to multiple arenas, this allocator supports 4319 thread-specific caching, in order to make it possible to completely avoid 4320 synchronization for most allocation requests. Such caching allows very fast 4321 allocation in the common case, but it increases memory usage and 4322 fragmentation, since a bounded number of objects can remain allocated in 4323 each thread cache.</para> 4324 4325 <para>Memory is conceptually broken into extents. Extents are always 4326 aligned to multiples of the page size. This alignment makes it possible to 4327 find metadata for user objects quickly. User objects are broken into two 4328 categories according to size: small and large. Contiguous small objects 4329 comprise a slab, which resides within a single extent, whereas large objects 4330 each have their own extents backing them.</para> 4331 4332 <para>Small objects are managed in groups by slabs. Each slab maintains 4333 a bitmap to track which regions are in use. Allocation requests that are no 4334 more than half the quantum (8 or 16, depending on architecture) are rounded 4335 up to the nearest power of two that is at least <code 4336 language="C">sizeof(<type>double</type>)</code>. All other object size 4337 classes are multiples of the quantum, spaced such that there are four size 4338 classes for each doubling in size, which limits internal fragmentation to 4339 approximately 20% for all but the smallest size classes. Small size classes 4340 are smaller than four times the page size, and large size classes extend 4341 from four times the page size up to the largest size class that does not 4342 exceed <constant>PTRDIFF_MAX</constant>.</para> 4343 4344 <para>Allocations are packed tightly together, which can be an issue for 4345 multi-threaded applications. If you need to assure that allocations do not 4346 suffer from cacheline sharing, round your allocation requests up to the 4347 nearest multiple of the cacheline size, or specify cacheline alignment when 4348 allocating.</para> 4349 4350 <para>The <function>realloc()</function>, 4351 <function>rallocx()</function>, and 4352 <function>xallocx()</function> functions may resize allocations 4353 without moving them under limited circumstances. Unlike the 4354 <function>*allocx()</function> API, the standard API does not 4355 officially round up the usable size of an allocation to the nearest size 4356 class, so technically it is necessary to call 4357 <function>realloc()</function> to grow e.g. a 9-byte allocation to 4358 16 bytes, or shrink a 16-byte allocation to 9 bytes. Growth and shrinkage 4359 trivially succeeds in place as long as the pre-size and post-size both round 4360 up to the same size class. No other API guarantees are made regarding 4361 in-place resizing, but the current implementation also tries to resize large 4362 allocations in place, as long as the pre-size and post-size are both large. 4363 For shrinkage to succeed, the extent allocator must support splitting (see 4364 <link 4365 linkend="arena.i.extent_hooks"><mallctl>arena.<i>.extent_hooks</mallctl></link>). 4366 Growth only succeeds if the trailing memory is currently available, and the 4367 extent allocator supports merging.</para> 4368 4369 <para>Assuming 4 KiB pages and a 16-byte quantum on a 64-bit system, the 4370 size classes in each category are as shown in <xref linkend="size_classes" 4371 xrefstyle="template:Table %n"/>.</para> 4372 4373 <table xml:id="size_classes" frame="all"> 4374 <title>Size classes</title> 4375 <tgroup cols="3" colsep="1" rowsep="1"> 4376 <colspec colname="c1" align="left"/> 4377 <colspec colname="c2" align="right"/> 4378 <colspec colname="c3" align="left"/> 4379 <thead> 4380 <row> 4381 <entry>Category</entry> 4382 <entry>Spacing</entry> 4383 <entry>Size</entry> 4384 </row> 4385 </thead> 4386 <tbody> 4387 <row> 4388 <entry morerows="8">Small</entry> 4389 <entry>lg</entry> 4390 <entry>[8]</entry> 4391 </row> 4392 <row> 4393 <entry>16</entry> 4394 <entry>[16, 32, 48, 64, 80, 96, 112, 128]</entry> 4395 </row> 4396 <row> 4397 <entry>32</entry> 4398 <entry>[160, 192, 224, 256]</entry> 4399 </row> 4400 <row> 4401 <entry>64</entry> 4402 <entry>[320, 384, 448, 512]</entry> 4403 </row> 4404 <row> 4405 <entry>128</entry> 4406 <entry>[640, 768, 896, 1024]</entry> 4407 </row> 4408 <row> 4409 <entry>256</entry> 4410 <entry>[1280, 1536, 1792, 2048]</entry> 4411 </row> 4412 <row> 4413 <entry>512</entry> 4414 <entry>[2560, 3072, 3584, 4096]</entry> 4415 </row> 4416 <row> 4417 <entry>1 KiB</entry> 4418 <entry>[5 KiB, 6 KiB, 7 KiB, 8 KiB]</entry> 4419 </row> 4420 <row> 4421 <entry>2 KiB</entry> 4422 <entry>[10 KiB, 12 KiB, 14 KiB]</entry> 4423 </row> 4424 <row> 4425 <entry morerows="15">Large</entry> 4426 <entry>2 KiB</entry> 4427 <entry>[16 KiB]</entry> 4428 </row> 4429 <row> 4430 <entry>4 KiB</entry> 4431 <entry>[20 KiB, 24 KiB, 28 KiB, 32 KiB]</entry> 4432 </row> 4433 <row> 4434 <entry>8 KiB</entry> 4435 <entry>[40 KiB, 48 KiB, 54 KiB, 64 KiB]</entry> 4436 </row> 4437 <row> 4438 <entry>16 KiB</entry> 4439 <entry>[80 KiB, 96 KiB, 112 KiB, 128 KiB]</entry> 4440 </row> 4441 <row> 4442 <entry>32 KiB</entry> 4443 <entry>[160 KiB, 192 KiB, 224 KiB, 256 KiB]</entry> 4444 </row> 4445 <row> 4446 <entry>64 KiB</entry> 4447 <entry>[320 KiB, 384 KiB, 448 KiB, 512 KiB]</entry> 4448 </row> 4449 <row> 4450 <entry>128 KiB</entry> 4451 <entry>[640 KiB, 768 KiB, 896 KiB, 1 MiB]</entry> 4452 </row> 4453 <row> 4454 <entry>256 KiB</entry> 4455 <entry>[1280 KiB, 1536 KiB, 1792 KiB, 2 MiB]</entry> 4456 </row> 4457 <row> 4458 <entry>512 KiB</entry> 4459 <entry>[2560 KiB, 3 MiB, 3584 KiB, 4 MiB]</entry> 4460 </row> 4461 <row> 4462 <entry>1 MiB</entry> 4463 <entry>[5 MiB, 6 MiB, 7 MiB, 8 MiB]</entry> 4464 </row> 4465 <row> 4466 <entry>2 MiB</entry> 4467 <entry>[10 MiB, 12 MiB, 14 MiB, 16 MiB]</entry> 4468 </row> 4469 <row> 4470 <entry>4 MiB</entry> 4471 <entry>[20 MiB, 24 MiB, 28 MiB, 32 MiB]</entry> 4472 </row> 4473 <row> 4474 <entry>8 MiB</entry> 4475 <entry>[40 MiB, 48 MiB, 56 MiB, 64 MiB]</entry> 4476 </row> 4477 <row> 4478 <entry>...</entry> 4479 <entry>...</entry> 4480 </row> 4481 <row> 4482 <entry>512 PiB</entry> 4483 <entry>[2560 PiB, 3 EiB, 3584 PiB, 4 EiB]</entry> 4484 </row> 4485 <row> 4486 <entry>1 EiB</entry> 4487 <entry>[5 EiB, 6 EiB, 7 EiB]</entry> 4488 </row> 4489 </tbody> 4490 </tgroup> 4491 </table> 4492 </refsect1> 4493 <refsect1 id="mallctl_namespace"> 4494 <title>MALLCTL NAMESPACE</title> 4495 <para>The following names are defined in the namespace accessible via the 4496 <function>mallctl*()</function> functions. Value types are specified in 4497 parentheses, their readable/writable statuses are encoded as 4498 <literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or 4499 <literal>--</literal>, and required build configuration flags follow, if 4500 any. A name element encoded as <literal><i></literal> or 4501 <literal><j></literal> indicates an integer component, where the 4502 integer varies from 0 to some upper value that must be determined via 4503 introspection. In the case of <mallctl>stats.arenas.<i>.*</mallctl> 4504 and <mallctl>arena.<i>.{initialized,purge,decay,dss}</mallctl>, 4505 <literal><i></literal> equal to 4506 <constant>MALLCTL_ARENAS_ALL</constant> can be used to operate on all arenas 4507 or access the summation of statistics from all arenas; similarly 4508 <literal><i></literal> equal to 4509 <constant>MALLCTL_ARENAS_DESTROYED</constant> can be used to access the 4510 summation of statistics from all destroyed arenas. These constants can be 4511 utilized either via <function>mallctlnametomib()</function> followed by 4512 <function>mallctlbymib()</function>, or via code such as the following: 4513 <programlisting language="C"><![CDATA[ 4514#define STRINGIFY_HELPER(x) #x 4515#define STRINGIFY(x) STRINGIFY_HELPER(x) 4516 4517mallctl("arena." STRINGIFY(MALLCTL_ARENAS_ALL) ".decay", 4518 NULL, NULL, NULL, 0);]]></programlisting> 4519 Take special note of the <link 4520 linkend="epoch"><mallctl>epoch</mallctl></link> mallctl, which controls 4521 refreshing of cached dynamic statistics.</para> 4522 4523 <variablelist> 4524 <varlistentry id="version"> 4525 <term> 4526 <mallctl>version</mallctl> 4527 (<type>const char *</type>) 4528 <literal>r-</literal> 4529 </term> 4530 <listitem><para>Return the jemalloc version string.</para></listitem> 4531 </varlistentry> 4532 4533 <varlistentry id="epoch"> 4534 <term> 4535 <mallctl>epoch</mallctl> 4536 (<type>uint64_t</type>) 4537 <literal>rw</literal> 4538 </term> 4539 <listitem><para>If a value is passed in, refresh the data from which 4540 the <function>mallctl*()</function> functions report values, 4541 and increment the epoch. Return the current epoch. This is useful for 4542 detecting whether another thread caused a refresh.</para></listitem> 4543 </varlistentry> 4544 4545 <varlistentry id="background_thread"> 4546 <term> 4547 <mallctl>background_thread</mallctl> 4548 (<type>bool</type>) 4549 <literal>rw</literal> 4550 </term> 4551 <listitem><para>Enable/disable internal background worker threads. When 4552 set to true, background threads are created on demand (the number of 4553 background threads will be no more than the number of CPUs or active 4554 arenas). Threads run periodically, and handle <link 4555 linkend="arena.i.decay">purging</link> asynchronously. When switching 4556 off, background threads are terminated synchronously. Note that after 4557 <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry> 4558 function, the state in the child process will be disabled regardless 4559 the state in parent process. See <link 4560 linkend="stats.background_thread.num_threads"><mallctl>stats.background_thread</mallctl></link> 4561 for related stats. <link 4562 linkend="opt.background_thread"><mallctl>opt.background_thread</mallctl></link> 4563 can be used to set the default option. This option is only available on 4564 selected pthread-based platforms.</para></listitem> 4565 </varlistentry> 4566 4567 <varlistentry id="max_background_threads"> 4568 <term> 4569 <mallctl>max_background_threads</mallctl> 4570 (<type>size_t</type>) 4571 <literal>rw</literal> 4572 </term> 4573 <listitem><para>Maximum number of background worker threads that will 4574 be created. This value is capped at <link 4575 linkend="opt.max_background_threads"><mallctl>opt.max_background_threads</mallctl></link> at 4576 startup.</para></listitem> 4577 </varlistentry> 4578 4579 <varlistentry id="config.cache_oblivious"> 4580 <term> 4581 <mallctl>config.cache_oblivious</mallctl> 4582 (<type>bool</type>) 4583 <literal>r-</literal> 4584 </term> 4585 <listitem><para><option>--enable-cache-oblivious</option> was specified 4586 during build configuration.</para></listitem> 4587 </varlistentry> 4588 4589 <varlistentry id="config.debug"> 4590 <term> 4591 <mallctl>config.debug</mallctl> 4592 (<type>bool</type>) 4593 <literal>r-</literal> 4594 </term> 4595 <listitem><para><option>--enable-debug</option> was specified during 4596 build configuration.</para></listitem> 4597 </varlistentry> 4598 4599 <varlistentry id="config.fill"> 4600 <term> 4601 <mallctl>config.fill</mallctl> 4602 (<type>bool</type>) 4603 <literal>r-</literal> 4604 </term> 4605 <listitem><para><option>--enable-fill</option> was specified during 4606 build configuration.</para></listitem> 4607 </varlistentry> 4608 4609 <varlistentry id="config.lazy_lock"> 4610 <term> 4611 <mallctl>config.lazy_lock</mallctl> 4612 (<type>bool</type>) 4613 <literal>r-</literal> 4614 </term> 4615 <listitem><para><option>--enable-lazy-lock</option> was specified 4616 during build configuration.</para></listitem> 4617 </varlistentry> 4618 4619 <varlistentry id="config.malloc_conf"> 4620 <term> 4621 <mallctl>config.malloc_conf</mallctl> 4622 (<type>const char *</type>) 4623 <literal>r-</literal> 4624 </term> 4625 <listitem><para>Embedded configure-time-specified run-time options 4626 string, empty unless <option>--with-malloc-conf</option> was specified 4627 during build configuration.</para></listitem> 4628 </varlistentry> 4629 4630 <varlistentry id="config.prof"> 4631 <term> 4632 <mallctl>config.prof</mallctl> 4633 (<type>bool</type>) 4634 <literal>r-</literal> 4635 </term> 4636 <listitem><para><option>--enable-prof</option> was specified during 4637 build configuration.</para></listitem> 4638 </varlistentry> 4639 4640 <varlistentry id="config.prof_libgcc"> 4641 <term> 4642 <mallctl>config.prof_libgcc</mallctl> 4643 (<type>bool</type>) 4644 <literal>r-</literal> 4645 </term> 4646 <listitem><para><option>--disable-prof-libgcc</option> was not 4647 specified during build configuration.</para></listitem> 4648 </varlistentry> 4649 4650 <varlistentry id="config.prof_libunwind"> 4651 <term> 4652 <mallctl>config.prof_libunwind</mallctl> 4653 (<type>bool</type>) 4654 <literal>r-</literal> 4655 </term> 4656 <listitem><para><option>--enable-prof-libunwind</option> was specified 4657 during build configuration.</para></listitem> 4658 </varlistentry> 4659 4660 <varlistentry id="config.stats"> 4661 <term> 4662 <mallctl>config.stats</mallctl> 4663 (<type>bool</type>) 4664 <literal>r-</literal> 4665 </term> 4666 <listitem><para><option>--enable-stats</option> was specified during 4667 build configuration.</para></listitem> 4668 </varlistentry> 4669 4670 4671 <varlistentry id="config.utrace"> 4672 <term> 4673 <mallctl>config.utrace</mallctl> 4674 (<type>bool</type>) 4675 <literal>r-</literal> 4676 </term> 4677 <listitem><para><option>--enable-utrace</option> was specified during 4678 build configuration.</para></listitem> 4679 </varlistentry> 4680 4681 <varlistentry id="config.xmalloc"> 4682 <term> 4683 <mallctl>config.xmalloc</mallctl> 4684 (<type>bool</type>) 4685 <literal>r-</literal> 4686 </term> 4687 <listitem><para><option>--enable-xmalloc</option> was specified during 4688 build configuration.</para></listitem> 4689 </varlistentry> 4690 4691 <varlistentry id="opt.abort"> 4692 <term> 4693 <mallctl>opt.abort</mallctl> 4694 (<type>bool</type>) 4695 <literal>r-</literal> 4696 </term> 4697 <listitem><para>Abort-on-warning enabled/disabled. If true, most 4698 warnings are fatal. Note that runtime option warnings are not included 4699 (see <link 4700 linkend="opt.abort_conf"><mallctl>opt.abort_conf</mallctl></link> for 4701 that). The process will call 4702 <citerefentry><refentrytitle>abort</refentrytitle> 4703 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 4704 disabled by default unless <option>--enable-debug</option> is 4705 specified during configuration, in which case it is enabled by default. 4706 </para></listitem> 4707 </varlistentry> 4708 4709 <varlistentry id="opt.confirm_conf"> 4710 <term> 4711 <mallctl>opt.confirm_conf</mallctl> 4712 (<type>bool</type>) 4713 <literal>r-</literal> 4714 </term> 4715 <listitem><para>Confirm-runtime-options-when-program-starts 4716 enabled/disabled. If true, the string specified via 4717 <option>--with-malloc-conf</option>, the string pointed to by the 4718 global variable <varname>malloc_conf</varname>, the <quote>name</quote> 4719 of the file referenced by the symbolic link named 4720 <filename class="symlink">/etc/malloc.conf</filename>, and the value of 4721 the environment variable <envar>MALLOC_CONF</envar>, will be printed in 4722 order. Then, each option being set will be individually printed. This 4723 option is disabled by default.</para></listitem> 4724 </varlistentry> 4725 4726 <varlistentry id="opt.abort_conf"> 4727 <term> 4728 <mallctl>opt.abort_conf</mallctl> 4729 (<type>bool</type>) 4730 <literal>r-</literal> 4731 </term> 4732 <listitem><para>Abort-on-invalid-configuration enabled/disabled. If 4733 true, invalid runtime options are fatal. The process will call 4734 <citerefentry><refentrytitle>abort</refentrytitle> 4735 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 4736 disabled by default unless <option>--enable-debug</option> is 4737 specified during configuration, in which case it is enabled by default. 4738 </para></listitem> 4739 </varlistentry> 4740 4741 <varlistentry id="opt.metadata_thp"> 4742 <term> 4743 <mallctl>opt.metadata_thp</mallctl> 4744 (<type>const char *</type>) 4745 <literal>r-</literal> 4746 </term> 4747 <listitem><para>Controls whether to allow jemalloc to use transparent 4748 huge page (THP) for internal metadata (see <link 4749 linkend="stats.metadata">stats.metadata</link>). <quote>always</quote> 4750 allows such usage. <quote>auto</quote> uses no THP initially, but may 4751 begin to do so when metadata usage reaches certain level. The default 4752 is <quote>disabled</quote>.</para></listitem> 4753 </varlistentry> 4754 4755 <varlistentry id="opt.retain"> 4756 <term> 4757 <mallctl>opt.retain</mallctl> 4758 (<type>bool</type>) 4759 <literal>r-</literal> 4760 </term> 4761 <listitem><para>If true, retain unused virtual memory for later reuse 4762 rather than discarding it by calling 4763 <citerefentry><refentrytitle>munmap</refentrytitle> 4764 <manvolnum>2</manvolnum></citerefentry> or equivalent (see <link 4765 linkend="stats.retained">stats.retained</link> for related details). 4766 It also makes jemalloc use <citerefentry> 4767 <refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum> 4768 </citerefentry> or equivalent in a more greedy way, mapping larger 4769 chunks in one go. This option is disabled by default unless discarding 4770 virtual memory is known to trigger platform-specific performance 4771 problems, namely 1) for [64-bit] Linux, which has a quirk in its virtual 4772 memory allocation algorithm that causes semi-permanent VM map holes 4773 under normal jemalloc operation; and 2) for [64-bit] Windows, which 4774 disallows split / merged regions with 4775 <parameter><constant>MEM_RELEASE</constant></parameter>. Although the 4776 same issues may present on 32-bit platforms as well, retaining virtual 4777 memory for 32-bit Linux and Windows is disabled by default due to the 4778 practical possibility of address space exhaustion. </para></listitem> 4779 </varlistentry> 4780 4781 <varlistentry id="opt.dss"> 4782 <term> 4783 <mallctl>opt.dss</mallctl> 4784 (<type>const char *</type>) 4785 <literal>r-</literal> 4786 </term> 4787 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 4788 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 4789 related to <citerefentry><refentrytitle>mmap</refentrytitle> 4790 <manvolnum>2</manvolnum></citerefentry> allocation. The following 4791 settings are supported if 4792 <citerefentry><refentrytitle>sbrk</refentrytitle> 4793 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 4794 system: <quote>disabled</quote>, <quote>primary</quote>, and 4795 <quote>secondary</quote>; otherwise only <quote>disabled</quote> is 4796 supported. The default is <quote>secondary</quote> if 4797 <citerefentry><refentrytitle>sbrk</refentrytitle> 4798 <manvolnum>2</manvolnum></citerefentry> is supported by the operating 4799 system; <quote>disabled</quote> otherwise. 4800 </para></listitem> 4801 </varlistentry> 4802 4803 <varlistentry id="opt.narenas"> 4804 <term> 4805 <mallctl>opt.narenas</mallctl> 4806 (<type>unsigned</type>) 4807 <literal>r-</literal> 4808 </term> 4809 <listitem><para>Maximum number of arenas to use for automatic 4810 multiplexing of threads and arenas. The default is four times the 4811 number of CPUs, or one if there is a single CPU.</para></listitem> 4812 </varlistentry> 4813 4814 <varlistentry id="opt.oversize_threshold"> 4815 <term> 4816 <mallctl>opt.oversize_threshold</mallctl> 4817 (<type>size_t</type>) 4818 <literal>r-</literal> 4819 </term> 4820 <listitem><para>The threshold in bytes of which requests are considered 4821 oversize. Allocation requests with greater sizes are fulfilled from a 4822 dedicated arena (automatically managed, however not within 4823 <literal>narenas</literal>), in order to reduce fragmentation by not 4824 mixing huge allocations with small ones. In addition, the decay API 4825 guarantees on the extents greater than the specified threshold may be 4826 overridden. Note that requests with arena index specified via 4827 <constant>MALLOCX_ARENA</constant>, or threads associated with explicit 4828 arenas will not be considered. The default threshold is 8MiB. Values 4829 not within large size classes disables this feature.</para></listitem> 4830 </varlistentry> 4831 4832 <varlistentry id="opt.percpu_arena"> 4833 <term> 4834 <mallctl>opt.percpu_arena</mallctl> 4835 (<type>const char *</type>) 4836 <literal>r-</literal> 4837 </term> 4838 <listitem><para>Per CPU arena mode. Use the <quote>percpu</quote> 4839 setting to enable this feature, which uses number of CPUs to determine 4840 number of arenas, and bind threads to arenas dynamically based on the 4841 CPU the thread runs on currently. <quote>phycpu</quote> setting uses 4842 one arena per physical CPU, which means the two hyper threads on the 4843 same CPU share one arena. Note that no runtime checking regarding the 4844 availability of hyper threading is done at the moment. When set to 4845 <quote>disabled</quote>, narenas and thread to arena association will 4846 not be impacted by this option. The default is <quote>disabled</quote>. 4847 </para></listitem> 4848 </varlistentry> 4849 4850 <varlistentry id="opt.background_thread"> 4851 <term> 4852 <mallctl>opt.background_thread</mallctl> 4853 (<type>bool</type>) 4854 <literal>r-</literal> 4855 </term> 4856 <listitem><para>Internal background worker threads enabled/disabled. 4857 Because of potential circular dependencies, enabling background thread 4858 using this option may cause crash or deadlock during initialization. For 4859 a reliable way to use this feature, see <link 4860 linkend="background_thread">background_thread</link> for dynamic control 4861 options and details. This option is disabled by 4862 default.</para></listitem> 4863 </varlistentry> 4864 4865 <varlistentry id="opt.max_background_threads"> 4866 <term> 4867 <mallctl>opt.max_background_threads</mallctl> 4868 (<type>size_t</type>) 4869 <literal>r-</literal> 4870 </term> 4871 <listitem><para>Maximum number of background threads that will be created 4872 if <link linkend="background_thread">background_thread</link> is set. 4873 Defaults to number of cpus.</para></listitem> 4874 </varlistentry> 4875 4876 <varlistentry id="opt.dirty_decay_ms"> 4877 <term> 4878 <mallctl>opt.dirty_decay_ms</mallctl> 4879 (<type>ssize_t</type>) 4880 <literal>r-</literal> 4881 </term> 4882 <listitem><para>Approximate time in milliseconds from the creation of a 4883 set of unused dirty pages until an equivalent set of unused dirty pages 4884 is purged (i.e. converted to muzzy via e.g. 4885 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function> 4886 if supported by the operating system, or converted to clean otherwise) 4887 and/or reused. Dirty pages are defined as previously having been 4888 potentially written to by the application, and therefore consuming 4889 physical memory, yet having no current use. The pages are incrementally 4890 purged according to a sigmoidal decay curve that starts and ends with 4891 zero purge rate. A decay time of 0 causes all unused dirty pages to be 4892 purged immediately upon creation. A decay time of -1 disables purging. 4893 The default decay time is 10 seconds. See <link 4894 linkend="arenas.dirty_decay_ms"><mallctl>arenas.dirty_decay_ms</mallctl></link> 4895 and <link 4896 linkend="arena.i.dirty_decay_ms"><mallctl>arena.<i>.dirty_decay_ms</mallctl></link> 4897 for related dynamic control options. See <link 4898 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 4899 for a description of muzzy pages.for a description of muzzy pages. Note 4900 that when the <link 4901 linkend="opt.oversize_threshold"><mallctl>oversize_threshold</mallctl></link> 4902 feature is enabled, the arenas reserved for oversize requests may have 4903 its own default decay settings.</para></listitem> 4904 </varlistentry> 4905 4906 <varlistentry id="opt.muzzy_decay_ms"> 4907 <term> 4908 <mallctl>opt.muzzy_decay_ms</mallctl> 4909 (<type>ssize_t</type>) 4910 <literal>r-</literal> 4911 </term> 4912 <listitem><para>Approximate time in milliseconds from the creation of a 4913 set of unused muzzy pages until an equivalent set of unused muzzy pages 4914 is purged (i.e. converted to clean) and/or reused. Muzzy pages are 4915 defined as previously having been unused dirty pages that were 4916 subsequently purged in a manner that left them subject to the 4917 reclamation whims of the operating system (e.g. 4918 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function>), 4919 and therefore in an indeterminate state. The pages are incrementally 4920 purged according to a sigmoidal decay curve that starts and ends with 4921 zero purge rate. A decay time of 0 causes all unused muzzy pages to be 4922 purged immediately upon creation. A decay time of -1 disables purging. 4923 The default decay time is 10 seconds. See <link 4924 linkend="arenas.muzzy_decay_ms"><mallctl>arenas.muzzy_decay_ms</mallctl></link> 4925 and <link 4926 linkend="arena.i.muzzy_decay_ms"><mallctl>arena.<i>.muzzy_decay_ms</mallctl></link> 4927 for related dynamic control options.</para></listitem> 4928 </varlistentry> 4929 4930 <varlistentry id="opt.lg_extent_max_active_fit"> 4931 <term> 4932 <mallctl>opt.lg_extent_max_active_fit</mallctl> 4933 (<type>size_t</type>) 4934 <literal>r-</literal> 4935 </term> 4936 <listitem><para>When reusing dirty extents, this determines the (log 4937 base 2 of the) maximum ratio between the size of the active extent 4938 selected (to split off from) and the size of the requested allocation. 4939 This prevents the splitting of large active extents for smaller 4940 allocations, which can reduce fragmentation over the long run 4941 (especially for non-active extents). Lower value may reduce 4942 fragmentation, at the cost of extra active extents. The default value 4943 is 6, which gives a maximum ratio of 64 (2^6).</para></listitem> 4944 </varlistentry> 4945 4946 <varlistentry id="opt.stats_print"> 4947 <term> 4948 <mallctl>opt.stats_print</mallctl> 4949 (<type>bool</type>) 4950 <literal>r-</literal> 4951 </term> 4952 <listitem><para>Enable/disable statistics printing at exit. If 4953 enabled, the <function>malloc_stats_print()</function> 4954 function is called at program exit via an 4955 <citerefentry><refentrytitle>atexit</refentrytitle> 4956 <manvolnum>3</manvolnum></citerefentry> function. <link 4957 linkend="opt.stats_print_opts"><mallctl>opt.stats_print_opts</mallctl></link> 4958 can be combined to specify output options. If 4959 <option>--enable-stats</option> is specified during configuration, this 4960 has the potential to cause deadlock for a multi-threaded process that 4961 exits while one or more threads are executing in the memory allocation 4962 functions. Furthermore, <function>atexit()</function> may 4963 allocate memory during application initialization and then deadlock 4964 internally when jemalloc in turn calls 4965 <function>atexit()</function>, so this option is not 4966 universally usable (though the application can register its own 4967 <function>atexit()</function> function with equivalent 4968 functionality). Therefore, this option should only be used with care; 4969 it is primarily intended as a performance tuning aid during application 4970 development. This option is disabled by default.</para></listitem> 4971 </varlistentry> 4972 4973 <varlistentry id="opt.stats_print_opts"> 4974 <term> 4975 <mallctl>opt.stats_print_opts</mallctl> 4976 (<type>const char *</type>) 4977 <literal>r-</literal> 4978 </term> 4979 <listitem><para>Options (the <parameter>opts</parameter> string) to pass 4980 to the <function>malloc_stats_print()</function> at exit (enabled 4981 through <link 4982 linkend="opt.stats_print"><mallctl>opt.stats_print</mallctl></link>). See 4983 available options in <link 4984 linkend="malloc_stats_print_opts"><function>malloc_stats_print()</function></link>. 4985 Has no effect unless <link 4986 linkend="opt.stats_print"><mallctl>opt.stats_print</mallctl></link> is 4987 enabled. The default is <quote></quote>.</para></listitem> 4988 </varlistentry> 4989 4990 <varlistentry id="opt.junk"> 4991 <term> 4992 <mallctl>opt.junk</mallctl> 4993 (<type>const char *</type>) 4994 <literal>r-</literal> 4995 [<option>--enable-fill</option>] 4996 </term> 4997 <listitem><para>Junk filling. If set to <quote>alloc</quote>, each byte 4998 of uninitialized allocated memory will be initialized to 4999 <literal>0xa5</literal>. If set to <quote>free</quote>, all deallocated 5000 memory will be initialized to <literal>0x5a</literal>. If set to 5001 <quote>true</quote>, both allocated and deallocated memory will be 5002 initialized, and if set to <quote>false</quote>, junk filling be 5003 disabled entirely. This is intended for debugging and will impact 5004 performance negatively. This option is <quote>false</quote> by default 5005 unless <option>--enable-debug</option> is specified during 5006 configuration, in which case it is <quote>true</quote> by 5007 default.</para></listitem> 5008 </varlistentry> 5009 5010 <varlistentry id="opt.zero"> 5011 <term> 5012 <mallctl>opt.zero</mallctl> 5013 (<type>bool</type>) 5014 <literal>r-</literal> 5015 [<option>--enable-fill</option>] 5016 </term> 5017 <listitem><para>Zero filling enabled/disabled. If enabled, each byte 5018 of uninitialized allocated memory will be initialized to 0. Note that 5019 this initialization only happens once for each byte, so 5020 <function>realloc()</function> and 5021 <function>rallocx()</function> calls do not zero memory that 5022 was previously allocated. This is intended for debugging and will 5023 impact performance negatively. This option is disabled by default. 5024 </para></listitem> 5025 </varlistentry> 5026 5027 <varlistentry id="opt.utrace"> 5028 <term> 5029 <mallctl>opt.utrace</mallctl> 5030 (<type>bool</type>) 5031 <literal>r-</literal> 5032 [<option>--enable-utrace</option>] 5033 </term> 5034 <listitem><para>Allocation tracing based on 5035 <citerefentry><refentrytitle>utrace</refentrytitle> 5036 <manvolnum>2</manvolnum></citerefentry> enabled/disabled. This option 5037 is disabled by default.</para></listitem> 5038 </varlistentry> 5039 5040 <varlistentry id="opt.xmalloc"> 5041 <term> 5042 <mallctl>opt.xmalloc</mallctl> 5043 (<type>bool</type>) 5044 <literal>r-</literal> 5045 [<option>--enable-xmalloc</option>] 5046 </term> 5047 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled, 5048 rather than returning failure for any allocation function, display a 5049 diagnostic message on <constant>STDERR_FILENO</constant> and cause the 5050 program to drop core (using 5051 <citerefentry><refentrytitle>abort</refentrytitle> 5052 <manvolnum>3</manvolnum></citerefentry>). If an application is 5053 designed to depend on this behavior, set the option at compile time by 5054 including the following in the source code: 5055 <programlisting language="C"><![CDATA[ 5056malloc_conf = "xmalloc:true";]]></programlisting> 5057 This option is disabled by default.</para></listitem> 5058 </varlistentry> 5059 5060 <varlistentry id="opt.tcache"> 5061 <term> 5062 <mallctl>opt.tcache</mallctl> 5063 (<type>bool</type>) 5064 <literal>r-</literal> 5065 </term> 5066 <listitem><para>Thread-specific caching (tcache) enabled/disabled. When 5067 there are multiple threads, each thread uses a tcache for objects up to 5068 a certain size. Thread-specific caching allows many allocations to be 5069 satisfied without performing any thread synchronization, at the cost of 5070 increased memory use. See the <link 5071 linkend="opt.lg_tcache_max"><mallctl>opt.lg_tcache_max</mallctl></link> 5072 option for related tuning information. This option is enabled by 5073 default.</para></listitem> 5074 </varlistentry> 5075 5076 <varlistentry id="opt.lg_tcache_max"> 5077 <term> 5078 <mallctl>opt.lg_tcache_max</mallctl> 5079 (<type>size_t</type>) 5080 <literal>r-</literal> 5081 </term> 5082 <listitem><para>Maximum size class (log base 2) to cache in the 5083 thread-specific cache (tcache). At a minimum, all small size classes 5084 are cached, and at a maximum all large size classes are cached. The 5085 default maximum is 32 KiB (2^15).</para></listitem> 5086 </varlistentry> 5087 5088 <varlistentry id="opt.thp"> 5089 <term> 5090 <mallctl>opt.thp</mallctl> 5091 (<type>const char *</type>) 5092 <literal>r-</literal> 5093 </term> 5094 <listitem><para>Transparent hugepage (THP) mode. Settings "always", 5095 "never" and "default" are available if THP is supported by the operating 5096 system. The "always" setting enables transparent hugepage for all user 5097 memory mappings with 5098 <parameter><constant>MADV_HUGEPAGE</constant></parameter>; "never" 5099 ensures no transparent hugepage with 5100 <parameter><constant>MADV_NOHUGEPAGE</constant></parameter>; the default 5101 setting "default" makes no changes. Note that: this option does not 5102 affect THP for jemalloc internal metadata (see <link 5103 linkend="opt.metadata_thp"><mallctl>opt.metadata_thp</mallctl></link>); 5104 in addition, for arenas with customized <link 5105 linkend="arena.i.extent_hooks"><mallctl>extent_hooks</mallctl></link>, 5106 this option is bypassed as it is implemented as part of the default 5107 extent hooks.</para></listitem> 5108 </varlistentry> 5109 5110 <varlistentry id="opt.prof"> 5111 <term> 5112 <mallctl>opt.prof</mallctl> 5113 (<type>bool</type>) 5114 <literal>r-</literal> 5115 [<option>--enable-prof</option>] 5116 </term> 5117 <listitem><para>Memory profiling enabled/disabled. If enabled, profile 5118 memory allocation activity. See the <link 5119 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 5120 option for on-the-fly activation/deactivation. See the <link 5121 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 5122 option for probabilistic sampling control. See the <link 5123 linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> 5124 option for control of cumulative sample reporting. See the <link 5125 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 5126 option for information on interval-triggered profile dumping, the <link 5127 linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link> 5128 option for information on high-water-triggered profile dumping, and the 5129 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link> 5130 option for final profile dumping. Profile output is compatible with 5131 the <command>jeprof</command> command, which is based on the 5132 <command>pprof</command> that is developed as part of the <ulink 5133 url="http://code.google.com/p/gperftools/">gperftools 5134 package</ulink>. See <link linkend="heap_profile_format">HEAP PROFILE 5135 FORMAT</link> for heap profile format documentation.</para></listitem> 5136 </varlistentry> 5137 5138 <varlistentry id="opt.prof_prefix"> 5139 <term> 5140 <mallctl>opt.prof_prefix</mallctl> 5141 (<type>const char *</type>) 5142 <literal>r-</literal> 5143 [<option>--enable-prof</option>] 5144 </term> 5145 <listitem><para>Filename prefix for profile dumps. If the prefix is 5146 set to the empty string, no automatic dumps will occur; this is 5147 primarily useful for disabling the automatic final heap dump (which 5148 also disables leak reporting, if enabled). The default prefix is 5149 <filename>jeprof</filename>.</para></listitem> 5150 </varlistentry> 5151 5152 <varlistentry id="opt.prof_active"> 5153 <term> 5154 <mallctl>opt.prof_active</mallctl> 5155 (<type>bool</type>) 5156 <literal>r-</literal> 5157 [<option>--enable-prof</option>] 5158 </term> 5159 <listitem><para>Profiling activated/deactivated. This is a secondary 5160 control mechanism that makes it possible to start the application with 5161 profiling enabled (see the <link 5162 linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but 5163 inactive, then toggle profiling at any time during program execution 5164 with the <link 5165 linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl. 5166 This option is enabled by default.</para></listitem> 5167 </varlistentry> 5168 5169 <varlistentry id="opt.prof_thread_active_init"> 5170 <term> 5171 <mallctl>opt.prof_thread_active_init</mallctl> 5172 (<type>bool</type>) 5173 <literal>r-</literal> 5174 [<option>--enable-prof</option>] 5175 </term> 5176 <listitem><para>Initial setting for <link 5177 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 5178 in newly created threads. The initial setting for newly created threads 5179 can also be changed during execution via the <link 5180 linkend="prof.thread_active_init"><mallctl>prof.thread_active_init</mallctl></link> 5181 mallctl. This option is enabled by default.</para></listitem> 5182 </varlistentry> 5183 5184 <varlistentry id="opt.lg_prof_sample"> 5185 <term> 5186 <mallctl>opt.lg_prof_sample</mallctl> 5187 (<type>size_t</type>) 5188 <literal>r-</literal> 5189 [<option>--enable-prof</option>] 5190 </term> 5191 <listitem><para>Average interval (log base 2) between allocation 5192 samples, as measured in bytes of allocation activity. Increasing the 5193 sampling interval decreases profile fidelity, but also decreases the 5194 computational overhead. The default sample interval is 512 KiB (2^19 5195 B).</para></listitem> 5196 </varlistentry> 5197 5198 <varlistentry id="opt.prof_accum"> 5199 <term> 5200 <mallctl>opt.prof_accum</mallctl> 5201 (<type>bool</type>) 5202 <literal>r-</literal> 5203 [<option>--enable-prof</option>] 5204 </term> 5205 <listitem><para>Reporting of cumulative object/byte counts in profile 5206 dumps enabled/disabled. If this option is enabled, every unique 5207 backtrace must be stored for the duration of execution. Depending on 5208 the application, this can impose a large memory overhead, and the 5209 cumulative counts are not always of interest. This option is disabled 5210 by default.</para></listitem> 5211 </varlistentry> 5212 5213 <varlistentry id="opt.lg_prof_interval"> 5214 <term> 5215 <mallctl>opt.lg_prof_interval</mallctl> 5216 (<type>ssize_t</type>) 5217 <literal>r-</literal> 5218 [<option>--enable-prof</option>] 5219 </term> 5220 <listitem><para>Average interval (log base 2) between memory profile 5221 dumps, as measured in bytes of allocation activity. The actual 5222 interval between dumps may be sporadic because decentralized allocation 5223 counters are used to avoid synchronization bottlenecks. Profiles are 5224 dumped to files named according to the pattern 5225 <filename><prefix>.<pid>.<seq>.i<iseq>.heap</filename>, 5226 where <literal><prefix></literal> is controlled by the 5227 <link 5228 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 5229 option. By default, interval-triggered profile dumping is disabled 5230 (encoded as -1). 5231 </para></listitem> 5232 </varlistentry> 5233 5234 <varlistentry id="opt.prof_gdump"> 5235 <term> 5236 <mallctl>opt.prof_gdump</mallctl> 5237 (<type>bool</type>) 5238 <literal>r-</literal> 5239 [<option>--enable-prof</option>] 5240 </term> 5241 <listitem><para>Set the initial state of <link 5242 linkend="prof.gdump"><mallctl>prof.gdump</mallctl></link>, which when 5243 enabled triggers a memory profile dump every time the total virtual 5244 memory exceeds the previous maximum. This option is disabled by 5245 default.</para></listitem> 5246 </varlistentry> 5247 5248 <varlistentry id="opt.prof_final"> 5249 <term> 5250 <mallctl>opt.prof_final</mallctl> 5251 (<type>bool</type>) 5252 <literal>r-</literal> 5253 [<option>--enable-prof</option>] 5254 </term> 5255 <listitem><para>Use an 5256 <citerefentry><refentrytitle>atexit</refentrytitle> 5257 <manvolnum>3</manvolnum></citerefentry> function to dump final memory 5258 usage to a file named according to the pattern 5259 <filename><prefix>.<pid>.<seq>.f.heap</filename>, 5260 where <literal><prefix></literal> is controlled by the <link 5261 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 5262 option. Note that <function>atexit()</function> may allocate 5263 memory during application initialization and then deadlock internally 5264 when jemalloc in turn calls <function>atexit()</function>, so 5265 this option is not universally usable (though the application can 5266 register its own <function>atexit()</function> function with 5267 equivalent functionality). This option is disabled by 5268 default.</para></listitem> 5269 </varlistentry> 5270 5271 <varlistentry id="opt.prof_leak"> 5272 <term> 5273 <mallctl>opt.prof_leak</mallctl> 5274 (<type>bool</type>) 5275 <literal>r-</literal> 5276 [<option>--enable-prof</option>] 5277 </term> 5278 <listitem><para>Leak reporting enabled/disabled. If enabled, use an 5279 <citerefentry><refentrytitle>atexit</refentrytitle> 5280 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks 5281 detected by allocation sampling. See the 5282 <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for 5283 information on analyzing heap profile output. This option is disabled 5284 by default.</para></listitem> 5285 </varlistentry> 5286 5287 <varlistentry id="thread.arena"> 5288 <term> 5289 <mallctl>thread.arena</mallctl> 5290 (<type>unsigned</type>) 5291 <literal>rw</literal> 5292 </term> 5293 <listitem><para>Get or set the arena associated with the calling 5294 thread. If the specified arena was not initialized beforehand (see the 5295 <link 5296 linkend="arena.i.initialized"><mallctl>arena.i.initialized</mallctl></link> 5297 mallctl), it will be automatically initialized as a side effect of 5298 calling this interface.</para></listitem> 5299 </varlistentry> 5300 5301 <varlistentry id="thread.allocated"> 5302 <term> 5303 <mallctl>thread.allocated</mallctl> 5304 (<type>uint64_t</type>) 5305 <literal>r-</literal> 5306 [<option>--enable-stats</option>] 5307 </term> 5308 <listitem><para>Get the total number of bytes ever allocated by the 5309 calling thread. This counter has the potential to wrap around; it is 5310 up to the application to appropriately interpret the counter in such 5311 cases.</para></listitem> 5312 </varlistentry> 5313 5314 <varlistentry id="thread.allocatedp"> 5315 <term> 5316 <mallctl>thread.allocatedp</mallctl> 5317 (<type>uint64_t *</type>) 5318 <literal>r-</literal> 5319 [<option>--enable-stats</option>] 5320 </term> 5321 <listitem><para>Get a pointer to the the value that is returned by the 5322 <link 5323 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 5324 mallctl. This is useful for avoiding the overhead of repeated 5325 <function>mallctl*()</function> calls.</para></listitem> 5326 </varlistentry> 5327 5328 <varlistentry id="thread.deallocated"> 5329 <term> 5330 <mallctl>thread.deallocated</mallctl> 5331 (<type>uint64_t</type>) 5332 <literal>r-</literal> 5333 [<option>--enable-stats</option>] 5334 </term> 5335 <listitem><para>Get the total number of bytes ever deallocated by the 5336 calling thread. This counter has the potential to wrap around; it is 5337 up to the application to appropriately interpret the counter in such 5338 cases.</para></listitem> 5339 </varlistentry> 5340 5341 <varlistentry id="thread.deallocatedp"> 5342 <term> 5343 <mallctl>thread.deallocatedp</mallctl> 5344 (<type>uint64_t *</type>) 5345 <literal>r-</literal> 5346 [<option>--enable-stats</option>] 5347 </term> 5348 <listitem><para>Get a pointer to the the value that is returned by the 5349 <link 5350 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link> 5351 mallctl. This is useful for avoiding the overhead of repeated 5352 <function>mallctl*()</function> calls.</para></listitem> 5353 </varlistentry> 5354 5355 <varlistentry id="thread.tcache.enabled"> 5356 <term> 5357 <mallctl>thread.tcache.enabled</mallctl> 5358 (<type>bool</type>) 5359 <literal>rw</literal> 5360 </term> 5361 <listitem><para>Enable/disable calling thread's tcache. The tcache is 5362 implicitly flushed as a side effect of becoming 5363 disabled (see <link 5364 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>). 5365 </para></listitem> 5366 </varlistentry> 5367 5368 <varlistentry id="thread.tcache.flush"> 5369 <term> 5370 <mallctl>thread.tcache.flush</mallctl> 5371 (<type>void</type>) 5372 <literal>--</literal> 5373 </term> 5374 <listitem><para>Flush calling thread's thread-specific cache (tcache). 5375 This interface releases all cached objects and internal data structures 5376 associated with the calling thread's tcache. Ordinarily, this interface 5377 need not be called, since automatic periodic incremental garbage 5378 collection occurs, and the thread cache is automatically discarded when 5379 a thread exits. However, garbage collection is triggered by allocation 5380 activity, so it is possible for a thread that stops 5381 allocating/deallocating to retain its cache indefinitely, in which case 5382 the developer may find manual flushing useful.</para></listitem> 5383 </varlistentry> 5384 5385 <varlistentry id="thread.prof.name"> 5386 <term> 5387 <mallctl>thread.prof.name</mallctl> 5388 (<type>const char *</type>) 5389 <literal>r-</literal> or 5390 <literal>-w</literal> 5391 [<option>--enable-prof</option>] 5392 </term> 5393 <listitem><para>Get/set the descriptive name associated with the calling 5394 thread in memory profile dumps. An internal copy of the name string is 5395 created, so the input string need not be maintained after this interface 5396 completes execution. The output string of this interface should be 5397 copied for non-ephemeral uses, because multiple implementation details 5398 can cause asynchronous string deallocation. Furthermore, each 5399 invocation of this interface can only read or write; simultaneous 5400 read/write is not supported due to string lifetime limitations. The 5401 name string must be nil-terminated and comprised only of characters in 5402 the sets recognized 5403 by <citerefentry><refentrytitle>isgraph</refentrytitle> 5404 <manvolnum>3</manvolnum></citerefentry> and 5405 <citerefentry><refentrytitle>isblank</refentrytitle> 5406 <manvolnum>3</manvolnum></citerefentry>.</para></listitem> 5407 </varlistentry> 5408 5409 <varlistentry id="thread.prof.active"> 5410 <term> 5411 <mallctl>thread.prof.active</mallctl> 5412 (<type>bool</type>) 5413 <literal>rw</literal> 5414 [<option>--enable-prof</option>] 5415 </term> 5416 <listitem><para>Control whether sampling is currently active for the 5417 calling thread. This is an activation mechanism in addition to <link 5418 linkend="prof.active"><mallctl>prof.active</mallctl></link>; both must 5419 be active for the calling thread to sample. This flag is enabled by 5420 default.</para></listitem> 5421 </varlistentry> 5422 5423 <varlistentry id="tcache.create"> 5424 <term> 5425 <mallctl>tcache.create</mallctl> 5426 (<type>unsigned</type>) 5427 <literal>r-</literal> 5428 </term> 5429 <listitem><para>Create an explicit thread-specific cache (tcache) and 5430 return an identifier that can be passed to the <link 5431 linkend="MALLOCX_TCACHE"><constant>MALLOCX_TCACHE(<parameter>tc</parameter>)</constant></link> 5432 macro to explicitly use the specified cache rather than the 5433 automatically managed one that is used by default. Each explicit cache 5434 can be used by only one thread at a time; the application must assure 5435 that this constraint holds. 5436 </para></listitem> 5437 </varlistentry> 5438 5439 <varlistentry id="tcache.flush"> 5440 <term> 5441 <mallctl>tcache.flush</mallctl> 5442 (<type>unsigned</type>) 5443 <literal>-w</literal> 5444 </term> 5445 <listitem><para>Flush the specified thread-specific cache (tcache). The 5446 same considerations apply to this interface as to <link 5447 linkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>, 5448 except that the tcache will never be automatically discarded. 5449 </para></listitem> 5450 </varlistentry> 5451 5452 <varlistentry id="tcache.destroy"> 5453 <term> 5454 <mallctl>tcache.destroy</mallctl> 5455 (<type>unsigned</type>) 5456 <literal>-w</literal> 5457 </term> 5458 <listitem><para>Flush the specified thread-specific cache (tcache) and 5459 make the identifier available for use during a future tcache creation. 5460 </para></listitem> 5461 </varlistentry> 5462 5463 <varlistentry id="arena.i.initialized"> 5464 <term> 5465 <mallctl>arena.<i>.initialized</mallctl> 5466 (<type>bool</type>) 5467 <literal>r-</literal> 5468 </term> 5469 <listitem><para>Get whether the specified arena's statistics are 5470 initialized (i.e. the arena was initialized prior to the current epoch). 5471 This interface can also be nominally used to query whether the merged 5472 statistics corresponding to <constant>MALLCTL_ARENAS_ALL</constant> are 5473 initialized (always true).</para></listitem> 5474 </varlistentry> 5475 5476 <varlistentry id="arena.i.decay"> 5477 <term> 5478 <mallctl>arena.<i>.decay</mallctl> 5479 (<type>void</type>) 5480 <literal>--</literal> 5481 </term> 5482 <listitem><para>Trigger decay-based purging of unused dirty/muzzy pages 5483 for arena <i>, or for all arenas if <i> equals 5484 <constant>MALLCTL_ARENAS_ALL</constant>. The proportion of unused 5485 dirty/muzzy pages to be purged depends on the current time; see <link 5486 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 5487 and <link 5488 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzy_decay_ms</mallctl></link> 5489 for details.</para></listitem> 5490 </varlistentry> 5491 5492 <varlistentry id="arena.i.purge"> 5493 <term> 5494 <mallctl>arena.<i>.purge</mallctl> 5495 (<type>void</type>) 5496 <literal>--</literal> 5497 </term> 5498 <listitem><para>Purge all unused dirty pages for arena <i>, or for 5499 all arenas if <i> equals <constant>MALLCTL_ARENAS_ALL</constant>. 5500 </para></listitem> 5501 </varlistentry> 5502 5503 <varlistentry id="arena.i.reset"> 5504 <term> 5505 <mallctl>arena.<i>.reset</mallctl> 5506 (<type>void</type>) 5507 <literal>--</literal> 5508 </term> 5509 <listitem><para>Discard all of the arena's extant allocations. This 5510 interface can only be used with arenas explicitly created via <link 5511 linkend="arenas.create"><mallctl>arenas.create</mallctl></link>. None 5512 of the arena's discarded/cached allocations may accessed afterward. As 5513 part of this requirement, all thread caches which were used to 5514 allocate/deallocate in conjunction with the arena must be flushed 5515 beforehand.</para></listitem> 5516 </varlistentry> 5517 5518 <varlistentry id="arena.i.destroy"> 5519 <term> 5520 <mallctl>arena.<i>.destroy</mallctl> 5521 (<type>void</type>) 5522 <literal>--</literal> 5523 </term> 5524 <listitem><para>Destroy the arena. Discard all of the arena's extant 5525 allocations using the same mechanism as for <link 5526 linkend="arena.i.reset"><mallctl>arena.<i>.reset</mallctl></link> 5527 (with all the same constraints and side effects), merge the arena stats 5528 into those accessible at arena index 5529 <constant>MALLCTL_ARENAS_DESTROYED</constant>, and then completely 5530 discard all metadata associated with the arena. Future calls to <link 5531 linkend="arenas.create"><mallctl>arenas.create</mallctl></link> may 5532 recycle the arena index. Destruction will fail if any threads are 5533 currently associated with the arena as a result of calls to <link 5534 linkend="thread.arena"><mallctl>thread.arena</mallctl></link>.</para></listitem> 5535 </varlistentry> 5536 5537 <varlistentry id="arena.i.dss"> 5538 <term> 5539 <mallctl>arena.<i>.dss</mallctl> 5540 (<type>const char *</type>) 5541 <literal>rw</literal> 5542 </term> 5543 <listitem><para>Set the precedence of dss allocation as related to mmap 5544 allocation for arena <i>, or for all arenas if <i> equals 5545 <constant>MALLCTL_ARENAS_ALL</constant>. See <link 5546 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for supported 5547 settings.</para></listitem> 5548 </varlistentry> 5549 5550 <varlistentry id="arena.i.dirty_decay_ms"> 5551 <term> 5552 <mallctl>arena.<i>.dirty_decay_ms</mallctl> 5553 (<type>ssize_t</type>) 5554 <literal>rw</literal> 5555 </term> 5556 <listitem><para>Current per-arena approximate time in milliseconds from 5557 the creation of a set of unused dirty pages until an equivalent set of 5558 unused dirty pages is purged and/or reused. Each time this interface is 5559 set, all currently unused dirty pages are considered to have fully 5560 decayed, which causes immediate purging of all unused dirty pages unless 5561 the decay time is set to -1 (i.e. purging disabled). See <link 5562 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 5563 for additional information.</para></listitem> 5564 </varlistentry> 5565 5566 <varlistentry id="arena.i.muzzy_decay_ms"> 5567 <term> 5568 <mallctl>arena.<i>.muzzy_decay_ms</mallctl> 5569 (<type>ssize_t</type>) 5570 <literal>rw</literal> 5571 </term> 5572 <listitem><para>Current per-arena approximate time in milliseconds from 5573 the creation of a set of unused muzzy pages until an equivalent set of 5574 unused muzzy pages is purged and/or reused. Each time this interface is 5575 set, all currently unused muzzy pages are considered to have fully 5576 decayed, which causes immediate purging of all unused muzzy pages unless 5577 the decay time is set to -1 (i.e. purging disabled). See <link 5578 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 5579 for additional information.</para></listitem> 5580 </varlistentry> 5581 5582 <varlistentry id="arena.i.retain_grow_limit"> 5583 <term> 5584 <mallctl>arena.<i>.retain_grow_limit</mallctl> 5585 (<type>size_t</type>) 5586 <literal>rw</literal> 5587 </term> 5588 <listitem><para>Maximum size to grow retained region (only relevant when 5589 <link linkend="opt.retain"><mallctl>opt.retain</mallctl></link> is 5590 enabled). This controls the maximum increment to expand virtual memory, 5591 or allocation through <link 5592 linkend="arena.i.extent_hooks"><mallctl>arena.<i>extent_hooks</mallctl></link>. 5593 In particular, if customized extent hooks reserve physical memory 5594 (e.g. 1G huge pages), this is useful to control the allocation hook's 5595 input size. The default is no limit.</para></listitem> 5596 </varlistentry> 5597 5598 <varlistentry id="arena.i.extent_hooks"> 5599 <term> 5600 <mallctl>arena.<i>.extent_hooks</mallctl> 5601 (<type>extent_hooks_t *</type>) 5602 <literal>rw</literal> 5603 </term> 5604 <listitem><para>Get or set the extent management hook functions for 5605 arena <i>. The functions must be capable of operating on all 5606 extant extents associated with arena <i>, usually by passing 5607 unknown extents to the replaced functions. In practice, it is feasible 5608 to control allocation for arenas explicitly created via <link 5609 linkend="arenas.create"><mallctl>arenas.create</mallctl></link> such 5610 that all extents originate from an application-supplied extent allocator 5611 (by specifying the custom extent hook functions during arena creation). 5612 However, the API guarantees for the automatically created arenas may be 5613 relaxed -- hooks set there may be called in a "best effort" fashion; in 5614 addition there may be extents created prior to the application having an 5615 opportunity to take over extent allocation.</para> 5616 5617 <programlisting language="C"><![CDATA[ 5618typedef extent_hooks_s extent_hooks_t; 5619struct extent_hooks_s { 5620 extent_alloc_t *alloc; 5621 extent_dalloc_t *dalloc; 5622 extent_destroy_t *destroy; 5623 extent_commit_t *commit; 5624 extent_decommit_t *decommit; 5625 extent_purge_t *purge_lazy; 5626 extent_purge_t *purge_forced; 5627 extent_split_t *split; 5628 extent_merge_t *merge; 5629};]]></programlisting> 5630 <para>The <type>extent_hooks_t</type> structure comprises function 5631 pointers which are described individually below. jemalloc uses these 5632 functions to manage extent lifetime, which starts off with allocation of 5633 mapped committed memory, in the simplest case followed by deallocation. 5634 However, there are performance and platform reasons to retain extents 5635 for later reuse. Cleanup attempts cascade from deallocation to decommit 5636 to forced purging to lazy purging, which gives the extent management 5637 functions opportunities to reject the most permanent cleanup operations 5638 in favor of less permanent (and often less costly) operations. All 5639 operations except allocation can be universally opted out of by setting 5640 the hook pointers to <constant>NULL</constant>, or selectively opted out 5641 of by returning failure. Note that once the extent hook is set, the 5642 structure is accessed directly by the associated arenas, so it must 5643 remain valid for the entire lifetime of the arenas.</para> 5644 5645 <funcsynopsis><funcprototype> 5646 <funcdef>typedef void *<function>(extent_alloc_t)</function></funcdef> 5647 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 5648 <paramdef>void *<parameter>new_addr</parameter></paramdef> 5649 <paramdef>size_t <parameter>size</parameter></paramdef> 5650 <paramdef>size_t <parameter>alignment</parameter></paramdef> 5651 <paramdef>bool *<parameter>zero</parameter></paramdef> 5652 <paramdef>bool *<parameter>commit</parameter></paramdef> 5653 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 5654 </funcprototype></funcsynopsis> 5655 <literallayout></literallayout> 5656 <para>An extent allocation function conforms to the 5657 <type>extent_alloc_t</type> type and upon success returns a pointer to 5658 <parameter>size</parameter> bytes of mapped memory on behalf of arena 5659 <parameter>arena_ind</parameter> such that the extent's base address is 5660 a multiple of <parameter>alignment</parameter>, as well as setting 5661 <parameter>*zero</parameter> to indicate whether the extent is zeroed 5662 and <parameter>*commit</parameter> to indicate whether the extent is 5663 committed. Upon error the function returns <constant>NULL</constant> 5664 and leaves <parameter>*zero</parameter> and 5665 <parameter>*commit</parameter> unmodified. The 5666 <parameter>size</parameter> parameter is always a multiple of the page 5667 size. The <parameter>alignment</parameter> parameter is always a power 5668 of two at least as large as the page size. Zeroing is mandatory if 5669 <parameter>*zero</parameter> is true upon function entry. Committing is 5670 mandatory if <parameter>*commit</parameter> is true upon function entry. 5671 If <parameter>new_addr</parameter> is not <constant>NULL</constant>, the 5672 returned pointer must be <parameter>new_addr</parameter> on success or 5673 <constant>NULL</constant> on error. Committed memory may be committed 5674 in absolute terms as on a system that does not overcommit, or in 5675 implicit terms as on a system that overcommits and satisfies physical 5676 memory needs on demand via soft page faults. Note that replacing the 5677 default extent allocation function makes the arena's <link 5678 linkend="arena.i.dss"><mallctl>arena.<i>.dss</mallctl></link> 5679 setting irrelevant.</para> 5680 5681 <funcsynopsis><funcprototype> 5682 <funcdef>typedef bool <function>(extent_dalloc_t)</function></funcdef> 5683 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 5684 <paramdef>void *<parameter>addr</parameter></paramdef> 5685 <paramdef>size_t <parameter>size</parameter></paramdef> 5686 <paramdef>bool <parameter>committed</parameter></paramdef> 5687 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 5688 </funcprototype></funcsynopsis> 5689 <literallayout></literallayout> 5690 <para> 5691 An extent deallocation function conforms to the 5692 <type>extent_dalloc_t</type> type and deallocates an extent at given 5693 <parameter>addr</parameter> and <parameter>size</parameter> with 5694 <parameter>committed</parameter>/decommited memory as indicated, on 5695 behalf of arena <parameter>arena_ind</parameter>, returning false upon 5696 success. If the function returns true, this indicates opt-out from 5697 deallocation; the virtual memory mapping associated with the extent 5698 remains mapped, in the same commit state, and available for future use, 5699 in which case it will be automatically retained for later reuse.</para> 5700 5701 <funcsynopsis><funcprototype> 5702 <funcdef>typedef void <function>(extent_destroy_t)</function></funcdef> 5703 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 5704 <paramdef>void *<parameter>addr</parameter></paramdef> 5705 <paramdef>size_t <parameter>size</parameter></paramdef> 5706 <paramdef>bool <parameter>committed</parameter></paramdef> 5707 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 5708 </funcprototype></funcsynopsis> 5709 <literallayout></literallayout> 5710 <para> 5711 An extent destruction function conforms to the 5712 <type>extent_destroy_t</type> type and unconditionally destroys an 5713 extent at given <parameter>addr</parameter> and 5714 <parameter>size</parameter> with 5715 <parameter>committed</parameter>/decommited memory as indicated, on 5716 behalf of arena <parameter>arena_ind</parameter>. This function may be 5717 called to destroy retained extents during arena destruction (see <link 5718 linkend="arena.i.destroy"><mallctl>arena.<i>.destroy</mallctl></link>).</para> 5719 5720 <funcsynopsis><funcprototype> 5721 <funcdef>typedef bool <function>(extent_commit_t)</function></funcdef> 5722 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 5723 <paramdef>void *<parameter>addr</parameter></paramdef> 5724 <paramdef>size_t <parameter>size</parameter></paramdef> 5725 <paramdef>size_t <parameter>offset</parameter></paramdef> 5726 <paramdef>size_t <parameter>length</parameter></paramdef> 5727 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 5728 </funcprototype></funcsynopsis> 5729 <literallayout></literallayout> 5730 <para>An extent commit function conforms to the 5731 <type>extent_commit_t</type> type and commits zeroed physical memory to 5732 back pages within an extent at given <parameter>addr</parameter> and 5733 <parameter>size</parameter> at <parameter>offset</parameter> bytes, 5734 extending for <parameter>length</parameter> on behalf of arena 5735 <parameter>arena_ind</parameter>, returning false upon success. 5736 Committed memory may be committed in absolute terms as on a system that 5737 does not overcommit, or in implicit terms as on a system that 5738 overcommits and satisfies physical memory needs on demand via soft page 5739 faults. If the function returns true, this indicates insufficient 5740 physical memory to satisfy the request.</para> 5741 5742 <funcsynopsis><funcprototype> 5743 <funcdef>typedef bool <function>(extent_decommit_t)</function></funcdef> 5744 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 5745 <paramdef>void *<parameter>addr</parameter></paramdef> 5746 <paramdef>size_t <parameter>size</parameter></paramdef> 5747 <paramdef>size_t <parameter>offset</parameter></paramdef> 5748 <paramdef>size_t <parameter>length</parameter></paramdef> 5749 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 5750 </funcprototype></funcsynopsis> 5751 <literallayout></literallayout> 5752 <para>An extent decommit function conforms to the 5753 <type>extent_decommit_t</type> type and decommits any physical memory 5754 that is backing pages within an extent at given 5755 <parameter>addr</parameter> and <parameter>size</parameter> at 5756 <parameter>offset</parameter> bytes, extending for 5757 <parameter>length</parameter> on behalf of arena 5758 <parameter>arena_ind</parameter>, returning false upon success, in which 5759 case the pages will be committed via the extent commit function before 5760 being reused. If the function returns true, this indicates opt-out from 5761 decommit; the memory remains committed and available for future use, in 5762 which case it will be automatically retained for later reuse.</para> 5763 5764 <funcsynopsis><funcprototype> 5765 <funcdef>typedef bool <function>(extent_purge_t)</function></funcdef> 5766 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 5767 <paramdef>void *<parameter>addr</parameter></paramdef> 5768 <paramdef>size_t <parameter>size</parameter></paramdef> 5769 <paramdef>size_t <parameter>offset</parameter></paramdef> 5770 <paramdef>size_t <parameter>length</parameter></paramdef> 5771 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 5772 </funcprototype></funcsynopsis> 5773 <literallayout></literallayout> 5774 <para>An extent purge function conforms to the 5775 <type>extent_purge_t</type> type and discards physical pages 5776 within the virtual memory mapping associated with an extent at given 5777 <parameter>addr</parameter> and <parameter>size</parameter> at 5778 <parameter>offset</parameter> bytes, extending for 5779 <parameter>length</parameter> on behalf of arena 5780 <parameter>arena_ind</parameter>. A lazy extent purge function (e.g. 5781 implemented via 5782 <function>madvise(<parameter>...</parameter><parameter><constant>MADV_FREE</constant></parameter>)</function>) 5783 can delay purging indefinitely and leave the pages within the purged 5784 virtual memory range in an indeterminite state, whereas a forced extent 5785 purge function immediately purges, and the pages within the virtual 5786 memory range will be zero-filled the next time they are accessed. If 5787 the function returns true, this indicates failure to purge.</para> 5788 5789 <funcsynopsis><funcprototype> 5790 <funcdef>typedef bool <function>(extent_split_t)</function></funcdef> 5791 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 5792 <paramdef>void *<parameter>addr</parameter></paramdef> 5793 <paramdef>size_t <parameter>size</parameter></paramdef> 5794 <paramdef>size_t <parameter>size_a</parameter></paramdef> 5795 <paramdef>size_t <parameter>size_b</parameter></paramdef> 5796 <paramdef>bool <parameter>committed</parameter></paramdef> 5797 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 5798 </funcprototype></funcsynopsis> 5799 <literallayout></literallayout> 5800 <para>An extent split function conforms to the 5801 <type>extent_split_t</type> type and optionally splits an extent at 5802 given <parameter>addr</parameter> and <parameter>size</parameter> into 5803 two adjacent extents, the first of <parameter>size_a</parameter> bytes, 5804 and the second of <parameter>size_b</parameter> bytes, operating on 5805 <parameter>committed</parameter>/decommitted memory as indicated, on 5806 behalf of arena <parameter>arena_ind</parameter>, returning false upon 5807 success. If the function returns true, this indicates that the extent 5808 remains unsplit and therefore should continue to be operated on as a 5809 whole.</para> 5810 5811 <funcsynopsis><funcprototype> 5812 <funcdef>typedef bool <function>(extent_merge_t)</function></funcdef> 5813 <paramdef>extent_hooks_t *<parameter>extent_hooks</parameter></paramdef> 5814 <paramdef>void *<parameter>addr_a</parameter></paramdef> 5815 <paramdef>size_t <parameter>size_a</parameter></paramdef> 5816 <paramdef>void *<parameter>addr_b</parameter></paramdef> 5817 <paramdef>size_t <parameter>size_b</parameter></paramdef> 5818 <paramdef>bool <parameter>committed</parameter></paramdef> 5819 <paramdef>unsigned <parameter>arena_ind</parameter></paramdef> 5820 </funcprototype></funcsynopsis> 5821 <literallayout></literallayout> 5822 <para>An extent merge function conforms to the 5823 <type>extent_merge_t</type> type and optionally merges adjacent extents, 5824 at given <parameter>addr_a</parameter> and <parameter>size_a</parameter> 5825 with given <parameter>addr_b</parameter> and 5826 <parameter>size_b</parameter> into one contiguous extent, operating on 5827 <parameter>committed</parameter>/decommitted memory as indicated, on 5828 behalf of arena <parameter>arena_ind</parameter>, returning false upon 5829 success. If the function returns true, this indicates that the extents 5830 remain distinct mappings and therefore should continue to be operated on 5831 independently.</para> 5832 </listitem> 5833 </varlistentry> 5834 5835 <varlistentry id="arenas.narenas"> 5836 <term> 5837 <mallctl>arenas.narenas</mallctl> 5838 (<type>unsigned</type>) 5839 <literal>r-</literal> 5840 </term> 5841 <listitem><para>Current limit on number of arenas.</para></listitem> 5842 </varlistentry> 5843 5844 <varlistentry id="arenas.dirty_decay_ms"> 5845 <term> 5846 <mallctl>arenas.dirty_decay_ms</mallctl> 5847 (<type>ssize_t</type>) 5848 <literal>rw</literal> 5849 </term> 5850 <listitem><para>Current default per-arena approximate time in 5851 milliseconds from the creation of a set of unused dirty pages until an 5852 equivalent set of unused dirty pages is purged and/or reused, used to 5853 initialize <link 5854 linkend="arena.i.dirty_decay_ms"><mallctl>arena.<i>.dirty_decay_ms</mallctl></link> 5855 during arena creation. See <link 5856 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 5857 for additional information.</para></listitem> 5858 </varlistentry> 5859 5860 <varlistentry id="arenas.muzzy_decay_ms"> 5861 <term> 5862 <mallctl>arenas.muzzy_decay_ms</mallctl> 5863 (<type>ssize_t</type>) 5864 <literal>rw</literal> 5865 </term> 5866 <listitem><para>Current default per-arena approximate time in 5867 milliseconds from the creation of a set of unused muzzy pages until an 5868 equivalent set of unused muzzy pages is purged and/or reused, used to 5869 initialize <link 5870 linkend="arena.i.muzzy_decay_ms"><mallctl>arena.<i>.muzzy_decay_ms</mallctl></link> 5871 during arena creation. See <link 5872 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 5873 for additional information.</para></listitem> 5874 </varlistentry> 5875 5876 <varlistentry id="arenas.quantum"> 5877 <term> 5878 <mallctl>arenas.quantum</mallctl> 5879 (<type>size_t</type>) 5880 <literal>r-</literal> 5881 </term> 5882 <listitem><para>Quantum size.</para></listitem> 5883 </varlistentry> 5884 5885 <varlistentry id="arenas.page"> 5886 <term> 5887 <mallctl>arenas.page</mallctl> 5888 (<type>size_t</type>) 5889 <literal>r-</literal> 5890 </term> 5891 <listitem><para>Page size.</para></listitem> 5892 </varlistentry> 5893 5894 <varlistentry id="arenas.tcache_max"> 5895 <term> 5896 <mallctl>arenas.tcache_max</mallctl> 5897 (<type>size_t</type>) 5898 <literal>r-</literal> 5899 </term> 5900 <listitem><para>Maximum thread-cached size class.</para></listitem> 5901 </varlistentry> 5902 5903 <varlistentry id="arenas.nbins"> 5904 <term> 5905 <mallctl>arenas.nbins</mallctl> 5906 (<type>unsigned</type>) 5907 <literal>r-</literal> 5908 </term> 5909 <listitem><para>Number of bin size classes.</para></listitem> 5910 </varlistentry> 5911 5912 <varlistentry id="arenas.nhbins"> 5913 <term> 5914 <mallctl>arenas.nhbins</mallctl> 5915 (<type>unsigned</type>) 5916 <literal>r-</literal> 5917 </term> 5918 <listitem><para>Total number of thread cache bin size 5919 classes.</para></listitem> 5920 </varlistentry> 5921 5922 <varlistentry id="arenas.bin.i.size"> 5923 <term> 5924 <mallctl>arenas.bin.<i>.size</mallctl> 5925 (<type>size_t</type>) 5926 <literal>r-</literal> 5927 </term> 5928 <listitem><para>Maximum size supported by size class.</para></listitem> 5929 </varlistentry> 5930 5931 <varlistentry id="arenas.bin.i.nregs"> 5932 <term> 5933 <mallctl>arenas.bin.<i>.nregs</mallctl> 5934 (<type>uint32_t</type>) 5935 <literal>r-</literal> 5936 </term> 5937 <listitem><para>Number of regions per slab.</para></listitem> 5938 </varlistentry> 5939 5940 <varlistentry id="arenas.bin.i.slab_size"> 5941 <term> 5942 <mallctl>arenas.bin.<i>.slab_size</mallctl> 5943 (<type>size_t</type>) 5944 <literal>r-</literal> 5945 </term> 5946 <listitem><para>Number of bytes per slab.</para></listitem> 5947 </varlistentry> 5948 5949 <varlistentry id="arenas.nlextents"> 5950 <term> 5951 <mallctl>arenas.nlextents</mallctl> 5952 (<type>unsigned</type>) 5953 <literal>r-</literal> 5954 </term> 5955 <listitem><para>Total number of large size classes.</para></listitem> 5956 </varlistentry> 5957 5958 <varlistentry id="arenas.lextent.i.size"> 5959 <term> 5960 <mallctl>arenas.lextent.<i>.size</mallctl> 5961 (<type>size_t</type>) 5962 <literal>r-</literal> 5963 </term> 5964 <listitem><para>Maximum size supported by this large size 5965 class.</para></listitem> 5966 </varlistentry> 5967 5968 <varlistentry id="arenas.create"> 5969 <term> 5970 <mallctl>arenas.create</mallctl> 5971 (<type>unsigned</type>, <type>extent_hooks_t *</type>) 5972 <literal>rw</literal> 5973 </term> 5974 <listitem><para>Explicitly create a new arena outside the range of 5975 automatically managed arenas, with optionally specified extent hooks, 5976 and return the new arena index.</para></listitem> 5977 </varlistentry> 5978 5979 <varlistentry id="arenas.lookup"> 5980 <term> 5981 <mallctl>arenas.lookup</mallctl> 5982 (<type>unsigned</type>, <type>void*</type>) 5983 <literal>rw</literal> 5984 </term> 5985 <listitem><para>Index of the arena to which an allocation belongs to.</para></listitem> 5986 </varlistentry> 5987 5988 <varlistentry id="prof.thread_active_init"> 5989 <term> 5990 <mallctl>prof.thread_active_init</mallctl> 5991 (<type>bool</type>) 5992 <literal>rw</literal> 5993 [<option>--enable-prof</option>] 5994 </term> 5995 <listitem><para>Control the initial setting for <link 5996 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 5997 in newly created threads. See the <link 5998 linkend="opt.prof_thread_active_init"><mallctl>opt.prof_thread_active_init</mallctl></link> 5999 option for additional information.</para></listitem> 6000 </varlistentry> 6001 6002 <varlistentry id="prof.active"> 6003 <term> 6004 <mallctl>prof.active</mallctl> 6005 (<type>bool</type>) 6006 <literal>rw</literal> 6007 [<option>--enable-prof</option>] 6008 </term> 6009 <listitem><para>Control whether sampling is currently active. See the 6010 <link 6011 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 6012 option for additional information, as well as the interrelated <link 6013 linkend="thread.prof.active"><mallctl>thread.prof.active</mallctl></link> 6014 mallctl.</para></listitem> 6015 </varlistentry> 6016 6017 <varlistentry id="prof.dump"> 6018 <term> 6019 <mallctl>prof.dump</mallctl> 6020 (<type>const char *</type>) 6021 <literal>-w</literal> 6022 [<option>--enable-prof</option>] 6023 </term> 6024 <listitem><para>Dump a memory profile to the specified file, or if NULL 6025 is specified, to a file according to the pattern 6026 <filename><prefix>.<pid>.<seq>.m<mseq>.heap</filename>, 6027 where <literal><prefix></literal> is controlled by the 6028 <link 6029 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 6030 option.</para></listitem> 6031 </varlistentry> 6032 6033 <varlistentry id="prof.gdump"> 6034 <term> 6035 <mallctl>prof.gdump</mallctl> 6036 (<type>bool</type>) 6037 <literal>rw</literal> 6038 [<option>--enable-prof</option>] 6039 </term> 6040 <listitem><para>When enabled, trigger a memory profile dump every time 6041 the total virtual memory exceeds the previous maximum. Profiles are 6042 dumped to files named according to the pattern 6043 <filename><prefix>.<pid>.<seq>.u<useq>.heap</filename>, 6044 where <literal><prefix></literal> is controlled by the <link 6045 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 6046 option.</para></listitem> 6047 </varlistentry> 6048 6049 <varlistentry id="prof.reset"> 6050 <term> 6051 <mallctl>prof.reset</mallctl> 6052 (<type>size_t</type>) 6053 <literal>-w</literal> 6054 [<option>--enable-prof</option>] 6055 </term> 6056 <listitem><para>Reset all memory profile statistics, and optionally 6057 update the sample rate (see <link 6058 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 6059 and <link 6060 linkend="prof.lg_sample"><mallctl>prof.lg_sample</mallctl></link>). 6061 </para></listitem> 6062 </varlistentry> 6063 6064 <varlistentry id="prof.lg_sample"> 6065 <term> 6066 <mallctl>prof.lg_sample</mallctl> 6067 (<type>size_t</type>) 6068 <literal>r-</literal> 6069 [<option>--enable-prof</option>] 6070 </term> 6071 <listitem><para>Get the current sample rate (see <link 6072 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link>). 6073 </para></listitem> 6074 </varlistentry> 6075 6076 <varlistentry id="prof.interval"> 6077 <term> 6078 <mallctl>prof.interval</mallctl> 6079 (<type>uint64_t</type>) 6080 <literal>r-</literal> 6081 [<option>--enable-prof</option>] 6082 </term> 6083 <listitem><para>Average number of bytes allocated between 6084 interval-based profile dumps. See the 6085 <link 6086 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 6087 option for additional information.</para></listitem> 6088 </varlistentry> 6089 6090 <varlistentry id="stats.allocated"> 6091 <term> 6092 <mallctl>stats.allocated</mallctl> 6093 (<type>size_t</type>) 6094 <literal>r-</literal> 6095 [<option>--enable-stats</option>] 6096 </term> 6097 <listitem><para>Total number of bytes allocated by the 6098 application.</para></listitem> 6099 </varlistentry> 6100 6101 <varlistentry id="stats.active"> 6102 <term> 6103 <mallctl>stats.active</mallctl> 6104 (<type>size_t</type>) 6105 <literal>r-</literal> 6106 [<option>--enable-stats</option>] 6107 </term> 6108 <listitem><para>Total number of bytes in active pages allocated by the 6109 application. This is a multiple of the page size, and greater than or 6110 equal to <link 6111 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>. 6112 This does not include <link linkend="stats.arenas.i.pdirty"> 6113 <mallctl>stats.arenas.<i>.pdirty</mallctl></link>, 6114 <link linkend="stats.arenas.i.pmuzzy"> 6115 <mallctl>stats.arenas.<i>.pmuzzy</mallctl></link>, nor pages 6116 entirely devoted to allocator metadata.</para></listitem> 6117 </varlistentry> 6118 6119 <varlistentry id="stats.metadata"> 6120 <term> 6121 <mallctl>stats.metadata</mallctl> 6122 (<type>size_t</type>) 6123 <literal>r-</literal> 6124 [<option>--enable-stats</option>] 6125 </term> 6126 <listitem><para>Total number of bytes dedicated to metadata, which 6127 comprise base allocations used for bootstrap-sensitive allocator 6128 metadata structures (see <link 6129 linkend="stats.arenas.i.base"><mallctl>stats.arenas.<i>.base</mallctl></link>) 6130 and internal allocations (see <link 6131 linkend="stats.arenas.i.internal"><mallctl>stats.arenas.<i>.internal</mallctl></link>). 6132 Transparent huge page (enabled with <link 6133 linkend="opt.metadata_thp">opt.metadata_thp</link>) usage is not 6134 considered.</para></listitem> 6135 </varlistentry> 6136 6137 <varlistentry id="stats.metadata_thp"> 6138 <term> 6139 <mallctl>stats.metadata_thp</mallctl> 6140 (<type>size_t</type>) 6141 <literal>r-</literal> 6142 [<option>--enable-stats</option>] 6143 </term> 6144 <listitem><para>Number of transparent huge pages (THP) used for 6145 metadata. See <link 6146 linkend="stats.metadata"><mallctl>stats.metadata</mallctl></link> and 6147 <link linkend="opt.metadata_thp">opt.metadata_thp</link>) for 6148 details.</para></listitem> 6149 </varlistentry> 6150 6151 <varlistentry id="stats.resident"> 6152 <term> 6153 <mallctl>stats.resident</mallctl> 6154 (<type>size_t</type>) 6155 <literal>r-</literal> 6156 [<option>--enable-stats</option>] 6157 </term> 6158 <listitem><para>Maximum number of bytes in physically resident data 6159 pages mapped by the allocator, comprising all pages dedicated to 6160 allocator metadata, pages backing active allocations, and unused dirty 6161 pages. This is a maximum rather than precise because pages may not 6162 actually be physically resident if they correspond to demand-zeroed 6163 virtual memory that has not yet been touched. This is a multiple of the 6164 page size, and is larger than <link 6165 linkend="stats.active"><mallctl>stats.active</mallctl></link>.</para></listitem> 6166 </varlistentry> 6167 6168 <varlistentry id="stats.mapped"> 6169 <term> 6170 <mallctl>stats.mapped</mallctl> 6171 (<type>size_t</type>) 6172 <literal>r-</literal> 6173 [<option>--enable-stats</option>] 6174 </term> 6175 <listitem><para>Total number of bytes in active extents mapped by the 6176 allocator. This is larger than <link 6177 linkend="stats.active"><mallctl>stats.active</mallctl></link>. This 6178 does not include inactive extents, even those that contain unused dirty 6179 pages, which means that there is no strict ordering between this and 6180 <link 6181 linkend="stats.resident"><mallctl>stats.resident</mallctl></link>.</para></listitem> 6182 </varlistentry> 6183 6184 <varlistentry id="stats.retained"> 6185 <term> 6186 <mallctl>stats.retained</mallctl> 6187 (<type>size_t</type>) 6188 <literal>r-</literal> 6189 [<option>--enable-stats</option>] 6190 </term> 6191 <listitem><para>Total number of bytes in virtual memory mappings that 6192 were retained rather than being returned to the operating system via 6193 e.g. <citerefentry><refentrytitle>munmap</refentrytitle> 6194 <manvolnum>2</manvolnum></citerefentry> or similar. Retained virtual 6195 memory is typically untouched, decommitted, or purged, so it has no 6196 strongly associated physical memory (see <link 6197 linkend="arena.i.extent_hooks">extent hooks</link> for details). 6198 Retained memory is excluded from mapped memory statistics, e.g. <link 6199 linkend="stats.mapped"><mallctl>stats.mapped</mallctl></link>. 6200 </para></listitem> 6201 </varlistentry> 6202 6203 <varlistentry id="stats.background_thread.num_threads"> 6204 <term> 6205 <mallctl>stats.background_thread.num_threads</mallctl> 6206 (<type>size_t</type>) 6207 <literal>r-</literal> 6208 [<option>--enable-stats</option>] 6209 </term> 6210 <listitem><para> Number of <link linkend="background_thread">background 6211 threads</link> running currently.</para></listitem> 6212 </varlistentry> 6213 6214 <varlistentry id="stats.background_thread.num_runs"> 6215 <term> 6216 <mallctl>stats.background_thread.num_runs</mallctl> 6217 (<type>uint64_t</type>) 6218 <literal>r-</literal> 6219 [<option>--enable-stats</option>] 6220 </term> 6221 <listitem><para> Total number of runs from all <link 6222 linkend="background_thread">background threads</link>.</para></listitem> 6223 </varlistentry> 6224 6225 <varlistentry id="stats.background_thread.run_interval"> 6226 <term> 6227 <mallctl>stats.background_thread.run_interval</mallctl> 6228 (<type>uint64_t</type>) 6229 <literal>r-</literal> 6230 [<option>--enable-stats</option>] 6231 </term> 6232 <listitem><para> Average run interval in nanoseconds of <link 6233 linkend="background_thread">background threads</link>.</para></listitem> 6234 </varlistentry> 6235 6236 <varlistentry id="stats.mutexes.ctl"> 6237 <term> 6238 <mallctl>stats.mutexes.ctl.{counter};</mallctl> 6239 (<type>counter specific type</type>) 6240 <literal>r-</literal> 6241 [<option>--enable-stats</option>] 6242 </term> 6243 <listitem><para>Statistics on <varname>ctl</varname> mutex (global 6244 scope; mallctl related). <mallctl>{counter}</mallctl> is one of the 6245 counters below:</para> 6246 <varlistentry id="mutex_counters"> 6247 <listitem><para><varname>num_ops</varname> (<type>uint64_t</type>): 6248 Total number of lock acquisition operations on this mutex.</para> 6249 6250 <para><varname>num_spin_acq</varname> (<type>uint64_t</type>): Number 6251 of times the mutex was spin-acquired. When the mutex is currently 6252 locked and cannot be acquired immediately, a short period of 6253 spin-retry within jemalloc will be performed. Acquired through spin 6254 generally means the contention was lightweight and not causing context 6255 switches.</para> 6256 6257 <para><varname>num_wait</varname> (<type>uint64_t</type>): Number of 6258 times the mutex was wait-acquired, which means the mutex contention 6259 was not solved by spin-retry, and blocking operation was likely 6260 involved in order to acquire the mutex. This event generally implies 6261 higher cost / longer delay, and should be investigated if it happens 6262 often.</para> 6263 6264 <para><varname>max_wait_time</varname> (<type>uint64_t</type>): 6265 Maximum length of time in nanoseconds spent on a single wait-acquired 6266 lock operation. Note that to avoid profiling overhead on the common 6267 path, this does not consider spin-acquired cases.</para> 6268 6269 <para><varname>total_wait_time</varname> (<type>uint64_t</type>): 6270 Cumulative time in nanoseconds spent on wait-acquired lock operations. 6271 Similarly, spin-acquired cases are not considered.</para> 6272 6273 <para><varname>max_num_thds</varname> (<type>uint32_t</type>): Maximum 6274 number of threads waiting on this mutex simultaneously. Similarly, 6275 spin-acquired cases are not considered.</para> 6276 6277 <para><varname>num_owner_switch</varname> (<type>uint64_t</type>): 6278 Number of times the current mutex owner is different from the previous 6279 one. This event does not generally imply an issue; rather it is an 6280 indicator of how often the protected data are accessed by different 6281 threads. 6282 </para> 6283 </listitem> 6284 </varlistentry> 6285 </listitem> 6286 </varlistentry> 6287 6288 <varlistentry id="stats.mutexes.background_thread"> 6289 <term> 6290 <mallctl>stats.mutexes.background_thread.{counter}</mallctl> 6291 (<type>counter specific type</type>) <literal>r-</literal> 6292 [<option>--enable-stats</option>] 6293 </term> 6294 <listitem><para>Statistics on <varname>background_thread</varname> mutex 6295 (global scope; <link 6296 linkend="background_thread"><mallctl>background_thread</mallctl></link> 6297 related). <mallctl>{counter}</mallctl> is one of the counters in <link 6298 linkend="mutex_counters">mutex profiling 6299 counters</link>.</para></listitem> 6300 </varlistentry> 6301 6302 <varlistentry id="stats.mutexes.prof"> 6303 <term> 6304 <mallctl>stats.mutexes.prof.{counter}</mallctl> 6305 (<type>counter specific type</type>) <literal>r-</literal> 6306 [<option>--enable-stats</option>] 6307 </term> 6308 <listitem><para>Statistics on <varname>prof</varname> mutex (global 6309 scope; profiling related). <mallctl>{counter}</mallctl> is one of the 6310 counters in <link linkend="mutex_counters">mutex profiling 6311 counters</link>.</para></listitem> 6312 </varlistentry> 6313 6314 <varlistentry id="stats.mutexes.reset"> 6315 <term> 6316 <mallctl>stats.mutexes.reset</mallctl> 6317 (<type>void</type>) <literal>--</literal> 6318 [<option>--enable-stats</option>] 6319 </term> 6320 <listitem><para>Reset all mutex profile statistics, including global 6321 mutexes, arena mutexes and bin mutexes.</para></listitem> 6322 </varlistentry> 6323 6324 <varlistentry id="stats.arenas.i.dss"> 6325 <term> 6326 <mallctl>stats.arenas.<i>.dss</mallctl> 6327 (<type>const char *</type>) 6328 <literal>r-</literal> 6329 </term> 6330 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 6331 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 6332 related to <citerefentry><refentrytitle>mmap</refentrytitle> 6333 <manvolnum>2</manvolnum></citerefentry> allocation. See <link 6334 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for details. 6335 </para></listitem> 6336 </varlistentry> 6337 6338 <varlistentry id="stats.arenas.i.dirty_decay_ms"> 6339 <term> 6340 <mallctl>stats.arenas.<i>.dirty_decay_ms</mallctl> 6341 (<type>ssize_t</type>) 6342 <literal>r-</literal> 6343 </term> 6344 <listitem><para>Approximate time in milliseconds from the creation of a 6345 set of unused dirty pages until an equivalent set of unused dirty pages 6346 is purged and/or reused. See <link 6347 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 6348 for details.</para></listitem> 6349 </varlistentry> 6350 6351 <varlistentry id="stats.arenas.i.muzzy_decay_ms"> 6352 <term> 6353 <mallctl>stats.arenas.<i>.muzzy_decay_ms</mallctl> 6354 (<type>ssize_t</type>) 6355 <literal>r-</literal> 6356 </term> 6357 <listitem><para>Approximate time in milliseconds from the creation of a 6358 set of unused muzzy pages until an equivalent set of unused muzzy pages 6359 is purged and/or reused. See <link 6360 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 6361 for details.</para></listitem> 6362 </varlistentry> 6363 6364 <varlistentry id="stats.arenas.i.nthreads"> 6365 <term> 6366 <mallctl>stats.arenas.<i>.nthreads</mallctl> 6367 (<type>unsigned</type>) 6368 <literal>r-</literal> 6369 </term> 6370 <listitem><para>Number of threads currently assigned to 6371 arena.</para></listitem> 6372 </varlistentry> 6373 6374 <varlistentry id="stats.arenas.i.uptime"> 6375 <term> 6376 <mallctl>stats.arenas.<i>.uptime</mallctl> 6377 (<type>uint64_t</type>) 6378 <literal>r-</literal> 6379 </term> 6380 <listitem><para>Time elapsed (in nanoseconds) since the arena was 6381 created. If <i> equals <constant>0</constant> or 6382 <constant>MALLCTL_ARENAS_ALL</constant>, this is the uptime since malloc 6383 initialization.</para></listitem> 6384 </varlistentry> 6385 6386 <varlistentry id="stats.arenas.i.pactive"> 6387 <term> 6388 <mallctl>stats.arenas.<i>.pactive</mallctl> 6389 (<type>size_t</type>) 6390 <literal>r-</literal> 6391 </term> 6392 <listitem><para>Number of pages in active extents.</para></listitem> 6393 </varlistentry> 6394 6395 <varlistentry id="stats.arenas.i.pdirty"> 6396 <term> 6397 <mallctl>stats.arenas.<i>.pdirty</mallctl> 6398 (<type>size_t</type>) 6399 <literal>r-</literal> 6400 </term> 6401 <listitem><para>Number of pages within unused extents that are 6402 potentially dirty, and for which <function>madvise()</function> or 6403 similar has not been called. See <link 6404 linkend="opt.dirty_decay_ms"><mallctl>opt.dirty_decay_ms</mallctl></link> 6405 for a description of dirty pages.</para></listitem> 6406 </varlistentry> 6407 6408 <varlistentry id="stats.arenas.i.pmuzzy"> 6409 <term> 6410 <mallctl>stats.arenas.<i>.pmuzzy</mallctl> 6411 (<type>size_t</type>) 6412 <literal>r-</literal> 6413 </term> 6414 <listitem><para>Number of pages within unused extents that are muzzy. 6415 See <link 6416 linkend="opt.muzzy_decay_ms"><mallctl>opt.muzzy_decay_ms</mallctl></link> 6417 for a description of muzzy pages.</para></listitem> 6418 </varlistentry> 6419 6420 <varlistentry id="stats.arenas.i.mapped"> 6421 <term> 6422 <mallctl>stats.arenas.<i>.mapped</mallctl> 6423 (<type>size_t</type>) 6424 <literal>r-</literal> 6425 [<option>--enable-stats</option>] 6426 </term> 6427 <listitem><para>Number of mapped bytes.</para></listitem> 6428 </varlistentry> 6429 6430 <varlistentry id="stats.arenas.i.retained"> 6431 <term> 6432 <mallctl>stats.arenas.<i>.retained</mallctl> 6433 (<type>size_t</type>) 6434 <literal>r-</literal> 6435 [<option>--enable-stats</option>] 6436 </term> 6437 <listitem><para>Number of retained bytes. See <link 6438 linkend="stats.retained"><mallctl>stats.retained</mallctl></link> for 6439 details.</para></listitem> 6440 </varlistentry> 6441 6442 <varlistentry id="stats.arenas.i.extent_avail"> 6443 <term> 6444 <mallctl>stats.arenas.<i>.extent_avail</mallctl> 6445 (<type>size_t</type>) 6446 <literal>r-</literal> 6447 [<option>--enable-stats</option>] 6448 </term> 6449 <listitem><para>Number of allocated (but unused) extent structs in this 6450 arena.</para></listitem> 6451 </varlistentry> 6452 6453 <varlistentry id="stats.arenas.i.base"> 6454 <term> 6455 <mallctl>stats.arenas.<i>.base</mallctl> 6456 (<type>size_t</type>) 6457 <literal>r-</literal> 6458 [<option>--enable-stats</option>] 6459 </term> 6460 <listitem><para> 6461 Number of bytes dedicated to bootstrap-sensitive allocator metadata 6462 structures.</para></listitem> 6463 </varlistentry> 6464 6465 <varlistentry id="stats.arenas.i.internal"> 6466 <term> 6467 <mallctl>stats.arenas.<i>.internal</mallctl> 6468 (<type>size_t</type>) 6469 <literal>r-</literal> 6470 [<option>--enable-stats</option>] 6471 </term> 6472 <listitem><para>Number of bytes dedicated to internal allocations. 6473 Internal allocations differ from application-originated allocations in 6474 that they are for internal use, and that they are omitted from heap 6475 profiles.</para></listitem> 6476 </varlistentry> 6477 6478 <varlistentry id="stats.arenas.i.metadata_thp"> 6479 <term> 6480 <mallctl>stats.arenas.<i>.metadata_thp</mallctl> 6481 (<type>size_t</type>) 6482 <literal>r-</literal> 6483 [<option>--enable-stats</option>] 6484 </term> 6485 <listitem><para>Number of transparent huge pages (THP) used for 6486 metadata. See <link linkend="opt.metadata_thp">opt.metadata_thp</link> 6487 for details.</para></listitem> 6488 </varlistentry> 6489 6490 <varlistentry id="stats.arenas.i.resident"> 6491 <term> 6492 <mallctl>stats.arenas.<i>.resident</mallctl> 6493 (<type>size_t</type>) 6494 <literal>r-</literal> 6495 [<option>--enable-stats</option>] 6496 </term> 6497 <listitem><para>Maximum number of bytes in physically resident data 6498 pages mapped by the arena, comprising all pages dedicated to allocator 6499 metadata, pages backing active allocations, and unused dirty pages. 6500 This is a maximum rather than precise because pages may not actually be 6501 physically resident if they correspond to demand-zeroed virtual memory 6502 that has not yet been touched. This is a multiple of the page 6503 size.</para></listitem> 6504 </varlistentry> 6505 6506 <varlistentry id="stats.arenas.i.dirty_npurge"> 6507 <term> 6508 <mallctl>stats.arenas.<i>.dirty_npurge</mallctl> 6509 (<type>uint64_t</type>) 6510 <literal>r-</literal> 6511 [<option>--enable-stats</option>] 6512 </term> 6513 <listitem><para>Number of dirty page purge sweeps performed. 6514 </para></listitem> 6515 </varlistentry> 6516 6517 <varlistentry id="stats.arenas.i.dirty_nmadvise"> 6518 <term> 6519 <mallctl>stats.arenas.<i>.dirty_nmadvise</mallctl> 6520 (<type>uint64_t</type>) 6521 <literal>r-</literal> 6522 [<option>--enable-stats</option>] 6523 </term> 6524 <listitem><para>Number of <function>madvise()</function> or similar 6525 calls made to purge dirty pages.</para></listitem> 6526 </varlistentry> 6527 6528 <varlistentry id="stats.arenas.i.dirty_purged"> 6529 <term> 6530 <mallctl>stats.arenas.<i>.dirty_purged</mallctl> 6531 (<type>uint64_t</type>) 6532 <literal>r-</literal> 6533 [<option>--enable-stats</option>] 6534 </term> 6535 <listitem><para>Number of dirty pages purged.</para></listitem> 6536 </varlistentry> 6537 6538 <varlistentry id="stats.arenas.i.muzzy_npurge"> 6539 <term> 6540 <mallctl>stats.arenas.<i>.muzzy_npurge</mallctl> 6541 (<type>uint64_t</type>) 6542 <literal>r-</literal> 6543 [<option>--enable-stats</option>] 6544 </term> 6545 <listitem><para>Number of muzzy page purge sweeps performed. 6546 </para></listitem> 6547 </varlistentry> 6548 6549 <varlistentry id="stats.arenas.i.muzzy_nmadvise"> 6550 <term> 6551 <mallctl>stats.arenas.<i>.muzzy_nmadvise</mallctl> 6552 (<type>uint64_t</type>) 6553 <literal>r-</literal> 6554 [<option>--enable-stats</option>] 6555 </term> 6556 <listitem><para>Number of <function>madvise()</function> or similar 6557 calls made to purge muzzy pages.</para></listitem> 6558 </varlistentry> 6559 6560 <varlistentry id="stats.arenas.i.muzzy_purged"> 6561 <term> 6562 <mallctl>stats.arenas.<i>.muzzy_purged</mallctl> 6563 (<type>uint64_t</type>) 6564 <literal>r-</literal> 6565 [<option>--enable-stats</option>] 6566 </term> 6567 <listitem><para>Number of muzzy pages purged.</para></listitem> 6568 </varlistentry> 6569 6570 <varlistentry id="stats.arenas.i.small.allocated"> 6571 <term> 6572 <mallctl>stats.arenas.<i>.small.allocated</mallctl> 6573 (<type>size_t</type>) 6574 <literal>r-</literal> 6575 [<option>--enable-stats</option>] 6576 </term> 6577 <listitem><para>Number of bytes currently allocated by small objects. 6578 </para></listitem> 6579 </varlistentry> 6580 6581 <varlistentry id="stats.arenas.i.small.nmalloc"> 6582 <term> 6583 <mallctl>stats.arenas.<i>.small.nmalloc</mallctl> 6584 (<type>uint64_t</type>) 6585 <literal>r-</literal> 6586 [<option>--enable-stats</option>] 6587 </term> 6588 <listitem><para>Cumulative number of times a small allocation was 6589 requested from the arena's bins, whether to fill the relevant tcache if 6590 <link linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is 6591 enabled, or to directly satisfy an allocation request 6592 otherwise.</para></listitem> 6593 </varlistentry> 6594 6595 <varlistentry id="stats.arenas.i.small.ndalloc"> 6596 <term> 6597 <mallctl>stats.arenas.<i>.small.ndalloc</mallctl> 6598 (<type>uint64_t</type>) 6599 <literal>r-</literal> 6600 [<option>--enable-stats</option>] 6601 </term> 6602 <listitem><para>Cumulative number of times a small allocation was 6603 returned to the arena's bins, whether to flush the relevant tcache if 6604 <link linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is 6605 enabled, or to directly deallocate an allocation 6606 otherwise.</para></listitem> 6607 </varlistentry> 6608 6609 <varlistentry id="stats.arenas.i.small.nrequests"> 6610 <term> 6611 <mallctl>stats.arenas.<i>.small.nrequests</mallctl> 6612 (<type>uint64_t</type>) 6613 <literal>r-</literal> 6614 [<option>--enable-stats</option>] 6615 </term> 6616 <listitem><para>Cumulative number of allocation requests satisfied by 6617 all bin size classes.</para></listitem> 6618 </varlistentry> 6619 6620 <varlistentry id="stats.arenas.i.small.nfills"> 6621 <term> 6622 <mallctl>stats.arenas.<i>.small.nfills</mallctl> 6623 (<type>uint64_t</type>) 6624 <literal>r-</literal> 6625 [<option>--enable-stats</option>] 6626 </term> 6627 <listitem><para>Cumulative number of tcache fills by all small size 6628 classes.</para></listitem> 6629 </varlistentry> 6630 6631 <varlistentry id="stats.arenas.i.small.nflushes"> 6632 <term> 6633 <mallctl>stats.arenas.<i>.small.nflushes</mallctl> 6634 (<type>uint64_t</type>) 6635 <literal>r-</literal> 6636 [<option>--enable-stats</option>] 6637 </term> 6638 <listitem><para>Cumulative number of tcache flushes by all small size 6639 classes.</para></listitem> 6640 </varlistentry> 6641 6642 <varlistentry id="stats.arenas.i.large.allocated"> 6643 <term> 6644 <mallctl>stats.arenas.<i>.large.allocated</mallctl> 6645 (<type>size_t</type>) 6646 <literal>r-</literal> 6647 [<option>--enable-stats</option>] 6648 </term> 6649 <listitem><para>Number of bytes currently allocated by large objects. 6650 </para></listitem> 6651 </varlistentry> 6652 6653 <varlistentry id="stats.arenas.i.large.nmalloc"> 6654 <term> 6655 <mallctl>stats.arenas.<i>.large.nmalloc</mallctl> 6656 (<type>uint64_t</type>) 6657 <literal>r-</literal> 6658 [<option>--enable-stats</option>] 6659 </term> 6660 <listitem><para>Cumulative number of times a large extent was allocated 6661 from the arena, whether to fill the relevant tcache if <link 6662 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 6663 the size class is within the range being cached, or to directly satisfy 6664 an allocation request otherwise.</para></listitem> 6665 </varlistentry> 6666 6667 <varlistentry id="stats.arenas.i.large.ndalloc"> 6668 <term> 6669 <mallctl>stats.arenas.<i>.large.ndalloc</mallctl> 6670 (<type>uint64_t</type>) 6671 <literal>r-</literal> 6672 [<option>--enable-stats</option>] 6673 </term> 6674 <listitem><para>Cumulative number of times a large extent was returned 6675 to the arena, whether to flush the relevant tcache if <link 6676 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 6677 the size class is within the range being cached, or to directly 6678 deallocate an allocation otherwise.</para></listitem> 6679 </varlistentry> 6680 6681 <varlistentry id="stats.arenas.i.large.nrequests"> 6682 <term> 6683 <mallctl>stats.arenas.<i>.large.nrequests</mallctl> 6684 (<type>uint64_t</type>) 6685 <literal>r-</literal> 6686 [<option>--enable-stats</option>] 6687 </term> 6688 <listitem><para>Cumulative number of allocation requests satisfied by 6689 all large size classes.</para></listitem> 6690 </varlistentry> 6691 6692 <varlistentry id="stats.arenas.i.large.nfills"> 6693 <term> 6694 <mallctl>stats.arenas.<i>.large.nfills</mallctl> 6695 (<type>uint64_t</type>) 6696 <literal>r-</literal> 6697 [<option>--enable-stats</option>] 6698 </term> 6699 <listitem><para>Cumulative number of tcache fills by all large size 6700 classes.</para></listitem> 6701 </varlistentry> 6702 6703 <varlistentry id="stats.arenas.i.large.nflushes"> 6704 <term> 6705 <mallctl>stats.arenas.<i>.large.nflushes</mallctl> 6706 (<type>uint64_t</type>) 6707 <literal>r-</literal> 6708 [<option>--enable-stats</option>] 6709 </term> 6710 <listitem><para>Cumulative number of tcache flushes by all large size 6711 classes.</para></listitem> 6712 </varlistentry> 6713 6714 <varlistentry id="stats.arenas.i.bins.j.nmalloc"> 6715 <term> 6716 <mallctl>stats.arenas.<i>.bins.<j>.nmalloc</mallctl> 6717 (<type>uint64_t</type>) 6718 <literal>r-</literal> 6719 [<option>--enable-stats</option>] 6720 </term> 6721 <listitem><para>Cumulative number of times a bin region of the 6722 corresponding size class was allocated from the arena, whether to fill 6723 the relevant tcache if <link 6724 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled, or 6725 to directly satisfy an allocation request otherwise.</para></listitem> 6726 </varlistentry> 6727 6728 <varlistentry id="stats.arenas.i.bins.j.ndalloc"> 6729 <term> 6730 <mallctl>stats.arenas.<i>.bins.<j>.ndalloc</mallctl> 6731 (<type>uint64_t</type>) 6732 <literal>r-</literal> 6733 [<option>--enable-stats</option>] 6734 </term> 6735 <listitem><para>Cumulative number of times a bin region of the 6736 corresponding size class was returned to the arena, whether to flush the 6737 relevant tcache if <link 6738 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled, or 6739 to directly deallocate an allocation otherwise.</para></listitem> 6740 </varlistentry> 6741 6742 <varlistentry id="stats.arenas.i.bins.j.nrequests"> 6743 <term> 6744 <mallctl>stats.arenas.<i>.bins.<j>.nrequests</mallctl> 6745 (<type>uint64_t</type>) 6746 <literal>r-</literal> 6747 [<option>--enable-stats</option>] 6748 </term> 6749 <listitem><para>Cumulative number of allocation requests satisfied by 6750 bin regions of the corresponding size class.</para></listitem> 6751 </varlistentry> 6752 6753 <varlistentry id="stats.arenas.i.bins.j.curregs"> 6754 <term> 6755 <mallctl>stats.arenas.<i>.bins.<j>.curregs</mallctl> 6756 (<type>size_t</type>) 6757 <literal>r-</literal> 6758 [<option>--enable-stats</option>] 6759 </term> 6760 <listitem><para>Current number of regions for this size 6761 class.</para></listitem> 6762 </varlistentry> 6763 6764 <varlistentry id="stats.arenas.i.bins.j.nfills"> 6765 <term> 6766 <mallctl>stats.arenas.<i>.bins.<j>.nfills</mallctl> 6767 (<type>uint64_t</type>) 6768 <literal>r-</literal> 6769 </term> 6770 <listitem><para>Cumulative number of tcache fills.</para></listitem> 6771 </varlistentry> 6772 6773 <varlistentry id="stats.arenas.i.bins.j.nflushes"> 6774 <term> 6775 <mallctl>stats.arenas.<i>.bins.<j>.nflushes</mallctl> 6776 (<type>uint64_t</type>) 6777 <literal>r-</literal> 6778 </term> 6779 <listitem><para>Cumulative number of tcache flushes.</para></listitem> 6780 </varlistentry> 6781 6782 <varlistentry id="stats.arenas.i.bins.j.nslabs"> 6783 <term> 6784 <mallctl>stats.arenas.<i>.bins.<j>.nslabs</mallctl> 6785 (<type>uint64_t</type>) 6786 <literal>r-</literal> 6787 [<option>--enable-stats</option>] 6788 </term> 6789 <listitem><para>Cumulative number of slabs created.</para></listitem> 6790 </varlistentry> 6791 6792 <varlistentry id="stats.arenas.i.bins.j.nreslabs"> 6793 <term> 6794 <mallctl>stats.arenas.<i>.bins.<j>.nreslabs</mallctl> 6795 (<type>uint64_t</type>) 6796 <literal>r-</literal> 6797 [<option>--enable-stats</option>] 6798 </term> 6799 <listitem><para>Cumulative number of times the current slab from which 6800 to allocate changed.</para></listitem> 6801 </varlistentry> 6802 6803 <varlistentry id="stats.arenas.i.bins.j.curslabs"> 6804 <term> 6805 <mallctl>stats.arenas.<i>.bins.<j>.curslabs</mallctl> 6806 (<type>size_t</type>) 6807 <literal>r-</literal> 6808 [<option>--enable-stats</option>] 6809 </term> 6810 <listitem><para>Current number of slabs.</para></listitem> 6811 </varlistentry> 6812 6813 6814 <varlistentry id="stats.arenas.i.bins.j.nonfull_slabs"> 6815 <term> 6816 <mallctl>stats.arenas.<i>.bins.<j>.nonfull_slabs</mallctl> 6817 (<type>size_t</type>) 6818 <literal>r-</literal> 6819 [<option>--enable-stats</option>] 6820 </term> 6821 <listitem><para>Current number of nonfull slabs.</para></listitem> 6822 </varlistentry> 6823 6824 <varlistentry id="stats.arenas.i.bins.mutex"> 6825 <term> 6826 <mallctl>stats.arenas.<i>.bins.<j>.mutex.{counter}</mallctl> 6827 (<type>counter specific type</type>) <literal>r-</literal> 6828 [<option>--enable-stats</option>] 6829 </term> 6830 <listitem><para>Statistics on 6831 <varname>arena.<i>.bins.<j></varname> mutex (arena bin 6832 scope; bin operation related). <mallctl>{counter}</mallctl> is one of 6833 the counters in <link linkend="mutex_counters">mutex profiling 6834 counters</link>.</para></listitem> 6835 </varlistentry> 6836 6837 <varlistentry id="stats.arenas.i.extents.n"> 6838 <term> 6839 <mallctl>stats.arenas.<i>.extents.<j>.n{extent_type}</mallctl> 6840 (<type>size_t</type>) 6841 <literal>r-</literal> 6842 [<option>--enable-stats</option>] 6843 </term> 6844 <listitem><para> Number of extents of the given type in this arena in 6845 the bucket corresponding to page size index <j>. The extent type 6846 is one of dirty, muzzy, or retained.</para></listitem> 6847 </varlistentry> 6848 6849 <varlistentry id="stats.arenas.i.extents.bytes"> 6850 <term> 6851 <mallctl>stats.arenas.<i>.extents.<j>.{extent_type}_bytes</mallctl> 6852 (<type>size_t</type>) 6853 <literal>r-</literal> 6854 [<option>--enable-stats</option>] 6855 </term> 6856 <listitem><para> Sum of the bytes managed by extents of the given type 6857 in this arena in the bucket corresponding to page size index <j>. 6858 The extent type is one of dirty, muzzy, or retained.</para></listitem> 6859 </varlistentry> 6860 6861 <varlistentry id="stats.arenas.i.lextents.j.nmalloc"> 6862 <term> 6863 <mallctl>stats.arenas.<i>.lextents.<j>.nmalloc</mallctl> 6864 (<type>uint64_t</type>) 6865 <literal>r-</literal> 6866 [<option>--enable-stats</option>] 6867 </term> 6868 <listitem><para>Cumulative number of times a large extent of the 6869 corresponding size class was allocated from the arena, whether to fill 6870 the relevant tcache if <link 6871 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 6872 the size class is within the range being cached, or to directly satisfy 6873 an allocation request otherwise.</para></listitem> 6874 </varlistentry> 6875 6876 <varlistentry id="stats.arenas.i.lextents.j.ndalloc"> 6877 <term> 6878 <mallctl>stats.arenas.<i>.lextents.<j>.ndalloc</mallctl> 6879 (<type>uint64_t</type>) 6880 <literal>r-</literal> 6881 [<option>--enable-stats</option>] 6882 </term> 6883 <listitem><para>Cumulative number of times a large extent of the 6884 corresponding size class was returned to the arena, whether to flush the 6885 relevant tcache if <link 6886 linkend="opt.tcache"><mallctl>opt.tcache</mallctl></link> is enabled and 6887 the size class is within the range being cached, or to directly 6888 deallocate an allocation otherwise.</para></listitem> 6889 </varlistentry> 6890 6891 <varlistentry id="stats.arenas.i.lextents.j.nrequests"> 6892 <term> 6893 <mallctl>stats.arenas.<i>.lextents.<j>.nrequests</mallctl> 6894 (<type>uint64_t</type>) 6895 <literal>r-</literal> 6896 [<option>--enable-stats</option>] 6897 </term> 6898 <listitem><para>Cumulative number of allocation requests satisfied by 6899 large extents of the corresponding size class.</para></listitem> 6900 </varlistentry> 6901 6902 <varlistentry id="stats.arenas.i.lextents.j.curlextents"> 6903 <term> 6904 <mallctl>stats.arenas.<i>.lextents.<j>.curlextents</mallctl> 6905 (<type>size_t</type>) 6906 <literal>r-</literal> 6907 [<option>--enable-stats</option>] 6908 </term> 6909 <listitem><para>Current number of large allocations for this size class. 6910 </para></listitem> 6911 </varlistentry> 6912 6913 <varlistentry id="stats.arenas.i.mutexes.large"> 6914 <term> 6915 <mallctl>stats.arenas.<i>.mutexes.large.{counter}</mallctl> 6916 (<type>counter specific type</type>) <literal>r-</literal> 6917 [<option>--enable-stats</option>] 6918 </term> 6919 <listitem><para>Statistics on <varname>arena.<i>.large</varname> 6920 mutex (arena scope; large allocation related). 6921 <mallctl>{counter}</mallctl> is one of the counters in <link 6922 linkend="mutex_counters">mutex profiling 6923 counters</link>.</para></listitem> 6924 </varlistentry> 6925 6926 <varlistentry id="stats.arenas.i.mutexes.extent_avail"> 6927 <term> 6928 <mallctl>stats.arenas.<i>.mutexes.extent_avail.{counter}</mallctl> 6929 (<type>counter specific type</type>) <literal>r-</literal> 6930 [<option>--enable-stats</option>] 6931 </term> 6932 <listitem><para>Statistics on <varname>arena.<i>.extent_avail 6933 </varname> mutex (arena scope; extent avail related). 6934 <mallctl>{counter}</mallctl> is one of the counters in <link 6935 linkend="mutex_counters">mutex profiling 6936 counters</link>.</para></listitem> 6937 </varlistentry> 6938 6939 <varlistentry id="stats.arenas.i.mutexes.extents_dirty"> 6940 <term> 6941 <mallctl>stats.arenas.<i>.mutexes.extents_dirty.{counter}</mallctl> 6942 (<type>counter specific type</type>) <literal>r-</literal> 6943 [<option>--enable-stats</option>] 6944 </term> 6945 <listitem><para>Statistics on <varname>arena.<i>.extents_dirty 6946 </varname> mutex (arena scope; dirty extents related). 6947 <mallctl>{counter}</mallctl> is one of the counters in <link 6948 linkend="mutex_counters">mutex profiling 6949 counters</link>.</para></listitem> 6950 </varlistentry> 6951 6952 <varlistentry id="stats.arenas.i.mutexes.extents_muzzy"> 6953 <term> 6954 <mallctl>stats.arenas.<i>.mutexes.extents_muzzy.{counter}</mallctl> 6955 (<type>counter specific type</type>) <literal>r-</literal> 6956 [<option>--enable-stats</option>] 6957 </term> 6958 <listitem><para>Statistics on <varname>arena.<i>.extents_muzzy 6959 </varname> mutex (arena scope; muzzy extents related). 6960 <mallctl>{counter}</mallctl> is one of the counters in <link 6961 linkend="mutex_counters">mutex profiling 6962 counters</link>.</para></listitem> 6963 </varlistentry> 6964 6965 <varlistentry id="stats.arenas.i.mutexes.extents_retained"> 6966 <term> 6967 <mallctl>stats.arenas.<i>.mutexes.extents_retained.{counter}</mallctl> 6968 (<type>counter specific type</type>) <literal>r-</literal> 6969 [<option>--enable-stats</option>] 6970 </term> 6971 <listitem><para>Statistics on <varname>arena.<i>.extents_retained 6972 </varname> mutex (arena scope; retained extents related). 6973 <mallctl>{counter}</mallctl> is one of the counters in <link 6974 linkend="mutex_counters">mutex profiling 6975 counters</link>.</para></listitem> 6976 </varlistentry> 6977 6978 <varlistentry id="stats.arenas.i.mutexes.decay_dirty"> 6979 <term> 6980 <mallctl>stats.arenas.<i>.mutexes.decay_dirty.{counter}</mallctl> 6981 (<type>counter specific type</type>) <literal>r-</literal> 6982 [<option>--enable-stats</option>] 6983 </term> 6984 <listitem><para>Statistics on <varname>arena.<i>.decay_dirty 6985 </varname> mutex (arena scope; decay for dirty pages related). 6986 <mallctl>{counter}</mallctl> is one of the counters in <link 6987 linkend="mutex_counters">mutex profiling 6988 counters</link>.</para></listitem> 6989 </varlistentry> 6990 6991 <varlistentry id="stats.arenas.i.mutexes.decay_muzzy"> 6992 <term> 6993 <mallctl>stats.arenas.<i>.mutexes.decay_muzzy.{counter}</mallctl> 6994 (<type>counter specific type</type>) <literal>r-</literal> 6995 [<option>--enable-stats</option>] 6996 </term> 6997 <listitem><para>Statistics on <varname>arena.<i>.decay_muzzy 6998 </varname> mutex (arena scope; decay for muzzy pages related). 6999 <mallctl>{counter}</mallctl> is one of the counters in <link 7000 linkend="mutex_counters">mutex profiling 7001 counters</link>.</para></listitem> 7002 </varlistentry> 7003 7004 <varlistentry id="stats.arenas.i.mutexes.base"> 7005 <term> 7006 <mallctl>stats.arenas.<i>.mutexes.base.{counter}</mallctl> 7007 (<type>counter specific type</type>) <literal>r-</literal> 7008 [<option>--enable-stats</option>] 7009 </term> 7010 <listitem><para>Statistics on <varname>arena.<i>.base</varname> 7011 mutex (arena scope; base allocator related). 7012 <mallctl>{counter}</mallctl> is one of the counters in <link 7013 linkend="mutex_counters">mutex profiling 7014 counters</link>.</para></listitem> 7015 </varlistentry> 7016 7017 <varlistentry id="stats.arenas.i.mutexes.tcache_list"> 7018 <term> 7019 <mallctl>stats.arenas.<i>.mutexes.tcache_list.{counter}</mallctl> 7020 (<type>counter specific type</type>) <literal>r-</literal> 7021 [<option>--enable-stats</option>] 7022 </term> 7023 <listitem><para>Statistics on 7024 <varname>arena.<i>.tcache_list</varname> mutex (arena scope; 7025 tcache to arena association related). This mutex is expected to be 7026 accessed less often. <mallctl>{counter}</mallctl> is one of the 7027 counters in <link linkend="mutex_counters">mutex profiling 7028 counters</link>.</para></listitem> 7029 </varlistentry> 7030 7031 </variablelist> 7032 </refsect1> 7033 <refsect1 id="heap_profile_format"> 7034 <title>HEAP PROFILE FORMAT</title> 7035 <para>Although the heap profiling functionality was originally designed to 7036 be compatible with the 7037 <command>pprof</command> command that is developed as part of the <ulink 7038 url="http://code.google.com/p/gperftools/">gperftools 7039 package</ulink>, the addition of per thread heap profiling functionality 7040 required a different heap profile format. The <command>jeprof</command> 7041 command is derived from <command>pprof</command>, with enhancements to 7042 support the heap profile format described here.</para> 7043 7044 <para>In the following hypothetical heap profile, <constant>[...]</constant> 7045 indicates elision for the sake of compactness. <programlisting><![CDATA[ 7046heap_v2/524288 7047 t*: 28106: 56637512 [0: 0] 7048 [...] 7049 t3: 352: 16777344 [0: 0] 7050 [...] 7051 t99: 17754: 29341640 [0: 0] 7052 [...] 7053@ 0x5f86da8 0x5f5a1dc [...] 0x29e4d4e 0xa200316 0xabb2988 [...] 7054 t*: 13: 6688 [0: 0] 7055 t3: 12: 6496 [0: ] 7056 t99: 1: 192 [0: 0] 7057[...] 7058 7059MAPPED_LIBRARIES: 7060[...]]]></programlisting> The following matches the above heap profile, but most 7061tokens are replaced with <constant><description></constant> to indicate 7062descriptions of the corresponding fields. <programlisting><![CDATA[ 7063<heap_profile_format_version>/<mean_sample_interval> 7064 <aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 7065 [...] 7066 <thread_3_aggregate>: <curobjs>: <curbytes>[<cumobjs>: <cumbytes>] 7067 [...] 7068 <thread_99_aggregate>: <curobjs>: <curbytes>[<cumobjs>: <cumbytes>] 7069 [...] 7070@ <top_frame> <frame> [...] <frame> <frame> <frame> [...] 7071 <backtrace_aggregate>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 7072 <backtrace_thread_3>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 7073 <backtrace_thread_99>: <curobjs>: <curbytes> [<cumobjs>: <cumbytes>] 7074[...] 7075 7076MAPPED_LIBRARIES: 7077</proc/<pid>/maps>]]></programlisting></para> 7078 </refsect1> 7079 7080 <refsect1 id="debugging_malloc_problems"> 7081 <title>DEBUGGING MALLOC PROBLEMS</title> 7082 <para>When debugging, it is a good idea to configure/build jemalloc with 7083 the <option>--enable-debug</option> and <option>--enable-fill</option> 7084 options, and recompile the program with suitable options and symbols for 7085 debugger support. When so configured, jemalloc incorporates a wide variety 7086 of run-time assertions that catch application errors such as double-free, 7087 write-after-free, etc.</para> 7088 7089 <para>Programs often accidentally depend on <quote>uninitialized</quote> 7090 memory actually being filled with zero bytes. Junk filling 7091 (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> 7092 option) tends to expose such bugs in the form of obviously incorrect 7093 results and/or coredumps. Conversely, zero 7094 filling (see the <link 7095 linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates 7096 the symptoms of such bugs. Between these two options, it is usually 7097 possible to quickly detect, diagnose, and eliminate such bugs.</para> 7098 7099 <para>This implementation does not provide much detail about the problems 7100 it detects, because the performance impact for storing such information 7101 would be prohibitive.</para> 7102 </refsect1> 7103 <refsect1 id="diagnostic_messages"> 7104 <title>DIAGNOSTIC MESSAGES</title> 7105 <para>If any of the memory allocation/deallocation functions detect an 7106 error or warning condition, a message will be printed to file descriptor 7107 <constant>STDERR_FILENO</constant>. Errors will result in the process 7108 dumping core. If the <link 7109 linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most 7110 warnings are treated as errors.</para> 7111 7112 <para>The <varname>malloc_message</varname> variable allows the programmer 7113 to override the function which emits the text strings forming the errors 7114 and warnings if for some reason the <constant>STDERR_FILENO</constant> file 7115 descriptor is not suitable for this. 7116 <function>malloc_message()</function> takes the 7117 <parameter>cbopaque</parameter> pointer argument that is 7118 <constant>NULL</constant> unless overridden by the arguments in a call to 7119 <function>malloc_stats_print()</function>, followed by a string 7120 pointer. Please note that doing anything which tries to allocate memory in 7121 this function is likely to result in a crash or deadlock.</para> 7122 7123 <para>All messages are prefixed by 7124 <quote><computeroutput><jemalloc>: </computeroutput></quote>.</para> 7125 </refsect1> 7126 <refsect1 id="return_values"> 7127 <title>RETURN VALUES</title> 7128 <refsect2> 7129 <title>Standard API</title> 7130 <para>The <function>malloc()</function> and 7131 <function>calloc()</function> functions return a pointer to the 7132 allocated memory if successful; otherwise a <constant>NULL</constant> 7133 pointer is returned and <varname>errno</varname> is set to 7134 <errorname>ENOMEM</errorname>.</para> 7135 7136 <para>The <function>posix_memalign()</function> function 7137 returns the value 0 if successful; otherwise it returns an error value. 7138 The <function>posix_memalign()</function> function will fail 7139 if: 7140 <variablelist> 7141 <varlistentry> 7142 <term><errorname>EINVAL</errorname></term> 7143 7144 <listitem><para>The <parameter>alignment</parameter> parameter is 7145 not a power of 2 at least as large as 7146 <code language="C">sizeof(<type>void *</type>)</code>. 7147 </para></listitem> 7148 </varlistentry> 7149 <varlistentry> 7150 <term><errorname>ENOMEM</errorname></term> 7151 7152 <listitem><para>Memory allocation error.</para></listitem> 7153 </varlistentry> 7154 </variablelist> 7155 </para> 7156 7157 <para>The <function>aligned_alloc()</function> function returns 7158 a pointer to the allocated memory if successful; otherwise a 7159 <constant>NULL</constant> pointer is returned and 7160 <varname>errno</varname> is set. The 7161 <function>aligned_alloc()</function> function will fail if: 7162 <variablelist> 7163 <varlistentry> 7164 <term><errorname>EINVAL</errorname></term> 7165 7166 <listitem><para>The <parameter>alignment</parameter> parameter is 7167 not a power of 2. 7168 </para></listitem> 7169 </varlistentry> 7170 <varlistentry> 7171 <term><errorname>ENOMEM</errorname></term> 7172 7173 <listitem><para>Memory allocation error.</para></listitem> 7174 </varlistentry> 7175 </variablelist> 7176 </para> 7177 7178 <para>The <function>realloc()</function> function returns a 7179 pointer, possibly identical to <parameter>ptr</parameter>, to the 7180 allocated memory if successful; otherwise a <constant>NULL</constant> 7181 pointer is returned, and <varname>errno</varname> is set to 7182 <errorname>ENOMEM</errorname> if the error was the result of an 7183 allocation failure. The <function>realloc()</function> 7184 function always leaves the original buffer intact when an error occurs. 7185 </para> 7186 7187 <para>The <function>free()</function> function returns no 7188 value.</para> 7189 </refsect2> 7190 <refsect2> 7191 <title>Non-standard API</title> 7192 <para>The <function>mallocx()</function> and 7193 <function>rallocx()</function> functions return a pointer to 7194 the allocated memory if successful; otherwise a <constant>NULL</constant> 7195 pointer is returned to indicate insufficient contiguous memory was 7196 available to service the allocation request. </para> 7197 7198 <para>The <function>xallocx()</function> function returns the 7199 real size of the resulting resized allocation pointed to by 7200 <parameter>ptr</parameter>, which is a value less than 7201 <parameter>size</parameter> if the allocation could not be adequately 7202 grown in place. </para> 7203 7204 <para>The <function>sallocx()</function> function returns the 7205 real size of the allocation pointed to by <parameter>ptr</parameter>. 7206 </para> 7207 7208 <para>The <function>nallocx()</function> returns the real size 7209 that would result from a successful equivalent 7210 <function>mallocx()</function> function call, or zero if 7211 insufficient memory is available to perform the size computation. </para> 7212 7213 <para>The <function>mallctl()</function>, 7214 <function>mallctlnametomib()</function>, and 7215 <function>mallctlbymib()</function> functions return 0 on 7216 success; otherwise they return an error value. The functions will fail 7217 if: 7218 <variablelist> 7219 <varlistentry> 7220 <term><errorname>EINVAL</errorname></term> 7221 7222 <listitem><para><parameter>newp</parameter> is not 7223 <constant>NULL</constant>, and <parameter>newlen</parameter> is too 7224 large or too small. Alternatively, <parameter>*oldlenp</parameter> 7225 is too large or too small; in this case as much data as possible 7226 are read despite the error.</para></listitem> 7227 </varlistentry> 7228 <varlistentry> 7229 <term><errorname>ENOENT</errorname></term> 7230 7231 <listitem><para><parameter>name</parameter> or 7232 <parameter>mib</parameter> specifies an unknown/invalid 7233 value.</para></listitem> 7234 </varlistentry> 7235 <varlistentry> 7236 <term><errorname>EPERM</errorname></term> 7237 7238 <listitem><para>Attempt to read or write void value, or attempt to 7239 write read-only value.</para></listitem> 7240 </varlistentry> 7241 <varlistentry> 7242 <term><errorname>EAGAIN</errorname></term> 7243 7244 <listitem><para>A memory allocation failure 7245 occurred.</para></listitem> 7246 </varlistentry> 7247 <varlistentry> 7248 <term><errorname>EFAULT</errorname></term> 7249 7250 <listitem><para>An interface with side effects failed in some way 7251 not directly related to <function>mallctl*()</function> 7252 read/write processing.</para></listitem> 7253 </varlistentry> 7254 </variablelist> 7255 </para> 7256 7257 <para>The <function>malloc_usable_size()</function> function 7258 returns the usable size of the allocation pointed to by 7259 <parameter>ptr</parameter>. </para> 7260 </refsect2> 7261 </refsect1> 7262 <refsect1 id="environment"> 7263 <title>ENVIRONMENT</title> 7264 <para>The following environment variable affects the execution of the 7265 allocation functions: 7266 <variablelist> 7267 <varlistentry> 7268 <term><envar>MALLOC_CONF</envar></term> 7269 7270 <listitem><para>If the environment variable 7271 <envar>MALLOC_CONF</envar> is set, the characters it contains 7272 will be interpreted as options.</para></listitem> 7273 </varlistentry> 7274 </variablelist> 7275 </para> 7276 </refsect1> 7277 <refsect1 id="examples"> 7278 <title>EXAMPLES</title> 7279 <para>To dump core whenever a problem occurs: 7280 <screen>ln -s 'abort:true' /etc/malloc.conf</screen> 7281 </para> 7282 <para>To specify in the source that only one arena should be automatically 7283 created: 7284 <programlisting language="C"><![CDATA[ 7285malloc_conf = "narenas:1";]]></programlisting></para> 7286 </refsect1> 7287 <refsect1 id="see_also"> 7288 <title>SEE ALSO</title> 7289 <para><citerefentry><refentrytitle>madvise</refentrytitle> 7290 <manvolnum>2</manvolnum></citerefentry>, 7291 <citerefentry><refentrytitle>mmap</refentrytitle> 7292 <manvolnum>2</manvolnum></citerefentry>, 7293 <citerefentry><refentrytitle>sbrk</refentrytitle> 7294 <manvolnum>2</manvolnum></citerefentry>, 7295 <citerefentry><refentrytitle>utrace</refentrytitle> 7296 <manvolnum>2</manvolnum></citerefentry>, 7297 <citerefentry><refentrytitle>alloca</refentrytitle> 7298 <manvolnum>3</manvolnum></citerefentry>, 7299 <citerefentry><refentrytitle>atexit</refentrytitle> 7300 <manvolnum>3</manvolnum></citerefentry>, 7301 <citerefentry><refentrytitle>getpagesize</refentrytitle> 7302 <manvolnum>3</manvolnum></citerefentry></para> 7303 </refsect1> 7304 <refsect1 id="standards"> 7305 <title>STANDARDS</title> 7306 <para>The <function>malloc()</function>, 7307 <function>calloc()</function>, 7308 <function>realloc()</function>, and 7309 <function>free()</function> functions conform to ISO/IEC 7310 9899:1990 (<quote>ISO C90</quote>).</para> 7311 7312 <para>The <function>posix_memalign()</function> function conforms 7313 to IEEE Std 1003.1-2001 (<quote>POSIX.1</quote>).</para> 7314 </refsect1> 7315 <refsect1 id="history"> 7316 <title>HISTORY</title> 7317 <para>The <function>malloc_usable_size()</function> and 7318 <function>posix_memalign()</function> functions first appeared in FreeBSD 7319 7.0.</para> 7320 7321 <para>The <function>aligned_alloc()</function>, 7322 <function>malloc_stats_print()</function>, and 7323 <function>mallctl*()</function> functions first appeared in FreeBSD 7324 10.0.</para> 7325 7326 <para>The <function>*allocx()</function> functions first appeared in FreeBSD 7327 11.0.</para> 7328 </refsect1> 7329</refentry> 7330>>>>>>> main 7331