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