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