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