The Tor Browser / file comparison

comparison: memory/jemalloc/src/doc/jemalloc.xml.in

memory/jemalloc/src/doc/jemalloc.xml.in

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:b38c3ca27a7e
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>malloc_usable_size</refname>
37 <refname>malloc_stats_print</refname>
38 <refname>mallctl</refname>
39 <refname>mallctlnametomib</refname>
40 <refname>mallctlbymib</refname>
41 <refname>allocm</refname>
42 <refname>rallocm</refname>
43 <refname>sallocm</refname>
44 <refname>dallocm</refname>
45 <refname>nallocm</refname>
46 -->
47 <refpurpose>general purpose memory allocation functions</refpurpose>
48 </refnamediv>
49 <refsect1 id="library">
50 <title>LIBRARY</title>
51 <para>This manual describes jemalloc @jemalloc_version@. More information
52 can be found at the <ulink
53 url="http://www.canonware.com/jemalloc/">jemalloc website</ulink>.</para>
54 </refsect1>
55 <refsynopsisdiv>
56 <title>SYNOPSIS</title>
57 <funcsynopsis>
58 <funcsynopsisinfo>#include &lt;<filename class="headerfile">stdlib.h</filename>&gt;
59 #include &lt;<filename class="headerfile">jemalloc/jemalloc.h</filename>&gt;</funcsynopsisinfo>
60 <refsect2>
61 <title>Standard API</title>
62 <funcprototype>
63 <funcdef>void *<function>malloc</function></funcdef>
64 <paramdef>size_t <parameter>size</parameter></paramdef>
65 </funcprototype>
66 <funcprototype>
67 <funcdef>void *<function>calloc</function></funcdef>
68 <paramdef>size_t <parameter>number</parameter></paramdef>
69 <paramdef>size_t <parameter>size</parameter></paramdef>
70 </funcprototype>
71 <funcprototype>
72 <funcdef>int <function>posix_memalign</function></funcdef>
73 <paramdef>void **<parameter>ptr</parameter></paramdef>
74 <paramdef>size_t <parameter>alignment</parameter></paramdef>
75 <paramdef>size_t <parameter>size</parameter></paramdef>
76 </funcprototype>
77 <funcprototype>
78 <funcdef>void *<function>aligned_alloc</function></funcdef>
79 <paramdef>size_t <parameter>alignment</parameter></paramdef>
80 <paramdef>size_t <parameter>size</parameter></paramdef>
81 </funcprototype>
82 <funcprototype>
83 <funcdef>void *<function>realloc</function></funcdef>
84 <paramdef>void *<parameter>ptr</parameter></paramdef>
85 <paramdef>size_t <parameter>size</parameter></paramdef>
86 </funcprototype>
87 <funcprototype>
88 <funcdef>void <function>free</function></funcdef>
89 <paramdef>void *<parameter>ptr</parameter></paramdef>
90 </funcprototype>
91 </refsect2>
92 <refsect2>
93 <title>Non-standard API</title>
94 <funcprototype>
95 <funcdef>size_t <function>malloc_usable_size</function></funcdef>
96 <paramdef>const void *<parameter>ptr</parameter></paramdef>
97 </funcprototype>
98 <funcprototype>
99 <funcdef>void <function>malloc_stats_print</function></funcdef>
100 <paramdef>void <parameter>(*write_cb)</parameter>
101 <funcparams>void *, const char *</funcparams>
102 </paramdef>
103 <paramdef>void *<parameter>cbopaque</parameter></paramdef>
104 <paramdef>const char *<parameter>opts</parameter></paramdef>
105 </funcprototype>
106 <funcprototype>
107 <funcdef>int <function>mallctl</function></funcdef>
108 <paramdef>const char *<parameter>name</parameter></paramdef>
109 <paramdef>void *<parameter>oldp</parameter></paramdef>
110 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef>
111 <paramdef>void *<parameter>newp</parameter></paramdef>
112 <paramdef>size_t <parameter>newlen</parameter></paramdef>
113 </funcprototype>
114 <funcprototype>
115 <funcdef>int <function>mallctlnametomib</function></funcdef>
116 <paramdef>const char *<parameter>name</parameter></paramdef>
117 <paramdef>size_t *<parameter>mibp</parameter></paramdef>
118 <paramdef>size_t *<parameter>miblenp</parameter></paramdef>
119 </funcprototype>
120 <funcprototype>
121 <funcdef>int <function>mallctlbymib</function></funcdef>
122 <paramdef>const size_t *<parameter>mib</parameter></paramdef>
123 <paramdef>size_t <parameter>miblen</parameter></paramdef>
124 <paramdef>void *<parameter>oldp</parameter></paramdef>
125 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef>
126 <paramdef>void *<parameter>newp</parameter></paramdef>
127 <paramdef>size_t <parameter>newlen</parameter></paramdef>
128 </funcprototype>
129 <funcprototype>
130 <funcdef>void <function>(*malloc_message)</function></funcdef>
131 <paramdef>void *<parameter>cbopaque</parameter></paramdef>
132 <paramdef>const char *<parameter>s</parameter></paramdef>
133 </funcprototype>
134 <para><type>const char *</type><varname>malloc_conf</varname>;</para>
135 </refsect2>
136 <refsect2>
137 <title>Experimental API</title>
138 <funcprototype>
139 <funcdef>int <function>allocm</function></funcdef>
140 <paramdef>void **<parameter>ptr</parameter></paramdef>
141 <paramdef>size_t *<parameter>rsize</parameter></paramdef>
142 <paramdef>size_t <parameter>size</parameter></paramdef>
143 <paramdef>int <parameter>flags</parameter></paramdef>
144 </funcprototype>
145 <funcprototype>
146 <funcdef>int <function>rallocm</function></funcdef>
147 <paramdef>void **<parameter>ptr</parameter></paramdef>
148 <paramdef>size_t *<parameter>rsize</parameter></paramdef>
149 <paramdef>size_t <parameter>size</parameter></paramdef>
150 <paramdef>size_t <parameter>extra</parameter></paramdef>
151 <paramdef>int <parameter>flags</parameter></paramdef>
152 </funcprototype>
153 <funcprototype>
154 <funcdef>int <function>sallocm</function></funcdef>
155 <paramdef>const void *<parameter>ptr</parameter></paramdef>
156 <paramdef>size_t *<parameter>rsize</parameter></paramdef>
157 <paramdef>int <parameter>flags</parameter></paramdef>
158 </funcprototype>
159 <funcprototype>
160 <funcdef>int <function>dallocm</function></funcdef>
161 <paramdef>void *<parameter>ptr</parameter></paramdef>
162 <paramdef>int <parameter>flags</parameter></paramdef>
163 </funcprototype>
164 <funcprototype>
165 <funcdef>int <function>nallocm</function></funcdef>
166 <paramdef>size_t *<parameter>rsize</parameter></paramdef>
167 <paramdef>size_t <parameter>size</parameter></paramdef>
168 <paramdef>int <parameter>flags</parameter></paramdef>
169 </funcprototype>
170 </refsect2>
171 </funcsynopsis>
172 </refsynopsisdiv>
173 <refsect1 id="description">
174 <title>DESCRIPTION</title>
175 <refsect2>
176 <title>Standard API</title>
177
178 <para>The <function>malloc<parameter/></function> function allocates
179 <parameter>size</parameter> bytes of uninitialized memory. The allocated
180 space is suitably aligned (after possible pointer coercion) for storage
181 of any type of object.</para>
182
183 <para>The <function>calloc<parameter/></function> function allocates
184 space for <parameter>number</parameter> objects, each
185 <parameter>size</parameter> bytes in length. The result is identical to
186 calling <function>malloc<parameter/></function> with an argument of
187 <parameter>number</parameter> * <parameter>size</parameter>, with the
188 exception that the allocated memory is explicitly initialized to zero
189 bytes.</para>
190
191 <para>The <function>posix_memalign<parameter/></function> function
192 allocates <parameter>size</parameter> bytes of memory such that the
193 allocation's base address is an even multiple of
194 <parameter>alignment</parameter>, and returns the allocation in the value
195 pointed to by <parameter>ptr</parameter>. The requested
196 <parameter>alignment</parameter> must be a power of 2 at least as large
197 as <code language="C">sizeof(<type>void *</type>)</code>.</para>
198
199 <para>The <function>aligned_alloc<parameter/></function> function
200 allocates <parameter>size</parameter> bytes of memory such that the
201 allocation's base address is an even multiple of
202 <parameter>alignment</parameter>. The requested
203 <parameter>alignment</parameter> must be a power of 2. Behavior is
204 undefined if <parameter>size</parameter> is not an integral multiple of
205 <parameter>alignment</parameter>.</para>
206
207 <para>The <function>realloc<parameter/></function> function changes the
208 size of the previously allocated memory referenced by
209 <parameter>ptr</parameter> to <parameter>size</parameter> bytes. The
210 contents of the memory are unchanged up to the lesser of the new and old
211 sizes. If the new size is larger, the contents of the newly allocated
212 portion of the memory are undefined. Upon success, the memory referenced
213 by <parameter>ptr</parameter> is freed and a pointer to the newly
214 allocated memory is returned. Note that
215 <function>realloc<parameter/></function> may move the memory allocation,
216 resulting in a different return value than <parameter>ptr</parameter>.
217 If <parameter>ptr</parameter> is <constant>NULL</constant>, the
218 <function>realloc<parameter/></function> function behaves identically to
219 <function>malloc<parameter/></function> for the specified size.</para>
220
221 <para>The <function>free<parameter/></function> function causes the
222 allocated memory referenced by <parameter>ptr</parameter> to be made
223 available for future allocations. If <parameter>ptr</parameter> is
224 <constant>NULL</constant>, no action occurs.</para>
225 </refsect2>
226 <refsect2>
227 <title>Non-standard API</title>
228
229 <para>The <function>malloc_usable_size<parameter/></function> function
230 returns the usable size of the allocation pointed to by
231 <parameter>ptr</parameter>. The return value may be larger than the size
232 that was requested during allocation. The
233 <function>malloc_usable_size<parameter/></function> function is not a
234 mechanism for in-place <function>realloc<parameter/></function>; rather
235 it is provided solely as a tool for introspection purposes. Any
236 discrepancy between the requested allocation size and the size reported
237 by <function>malloc_usable_size<parameter/></function> should not be
238 depended on, since such behavior is entirely implementation-dependent.
239 </para>
240
241 <para>The <function>malloc_stats_print<parameter/></function> function
242 writes human-readable summary statistics via the
243 <parameter>write_cb</parameter> callback function pointer and
244 <parameter>cbopaque</parameter> data passed to
245 <parameter>write_cb</parameter>, or
246 <function>malloc_message<parameter/></function> if
247 <parameter>write_cb</parameter> is <constant>NULL</constant>. This
248 function can be called repeatedly. General information that never
249 changes during execution can be omitted by specifying "g" as a character
250 within the <parameter>opts</parameter> string. Note that
251 <function>malloc_message<parameter/></function> uses the
252 <function>mallctl*<parameter/></function> functions internally, so
253 inconsistent statistics can be reported if multiple threads use these
254 functions simultaneously. If <option>--enable-stats</option> is
255 specified during configuration, &ldquo;m&rdquo; and &ldquo;a&rdquo; can
256 be specified to omit merged arena and per arena statistics, respectively;
257 &ldquo;b&rdquo; and &ldquo;l&rdquo; can be specified to omit per size
258 class statistics for bins and large objects, respectively. Unrecognized
259 characters are silently ignored. Note that thread caching may prevent
260 some statistics from being completely up to date, since extra locking
261 would be required to merge counters that track thread cache operations.
262 </para>
263
264 <para>The <function>mallctl<parameter/></function> function provides a
265 general interface for introspecting the memory allocator, as well as
266 setting modifiable parameters and triggering actions. The
267 period-separated <parameter>name</parameter> argument specifies a
268 location in a tree-structured namespace; see the <xref
269 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for
270 documentation on the tree contents. To read a value, pass a pointer via
271 <parameter>oldp</parameter> to adequate space to contain the value, and a
272 pointer to its length via <parameter>oldlenp</parameter>; otherwise pass
273 <constant>NULL</constant> and <constant>NULL</constant>. Similarly, to
274 write a value, pass a pointer to the value via
275 <parameter>newp</parameter>, and its length via
276 <parameter>newlen</parameter>; otherwise pass <constant>NULL</constant>
277 and <constant>0</constant>.</para>
278
279 <para>The <function>mallctlnametomib<parameter/></function> function
280 provides a way to avoid repeated name lookups for applications that
281 repeatedly query the same portion of the namespace, by translating a name
282 to a &ldquo;Management Information Base&rdquo; (MIB) that can be passed
283 repeatedly to <function>mallctlbymib<parameter/></function>. Upon
284 successful return from <function>mallctlnametomib<parameter/></function>,
285 <parameter>mibp</parameter> contains an array of
286 <parameter>*miblenp</parameter> integers, where
287 <parameter>*miblenp</parameter> is the lesser of the number of components
288 in <parameter>name</parameter> and the input value of
289 <parameter>*miblenp</parameter>. Thus it is possible to pass a
290 <parameter>*miblenp</parameter> that is smaller than the number of
291 period-separated name components, which results in a partial MIB that can
292 be used as the basis for constructing a complete MIB. For name
293 components that are integers (e.g. the 2 in
294 <link
295 linkend="arenas.bin.i.size"><mallctl>arenas.bin.2.size</mallctl></link>),
296 the corresponding MIB component will always be that integer. Therefore,
297 it is legitimate to construct code like the following: <programlisting
298 language="C"><![CDATA[
299 unsigned nbins, i;
300
301 int mib[4];
302 size_t len, miblen;
303
304 len = sizeof(nbins);
305 mallctl("arenas.nbins", &nbins, &len, NULL, 0);
306
307 miblen = 4;
308 mallnametomib("arenas.bin.0.size", mib, &miblen);
309 for (i = 0; i < nbins; i++) {
310 size_t bin_size;
311
312 mib[2] = i;
313 len = sizeof(bin_size);
314 mallctlbymib(mib, miblen, &bin_size, &len, NULL, 0);
315 /* Do something with bin_size... */
316 }]]></programlisting></para>
317 </refsect2>
318 <refsect2>
319 <title>Experimental API</title>
320 <para>The experimental API is subject to change or removal without regard
321 for backward compatibility. If <option>--disable-experimental</option>
322 is specified during configuration, the experimental API is
323 omitted.</para>
324
325 <para>The <function>allocm<parameter/></function>,
326 <function>rallocm<parameter/></function>,
327 <function>sallocm<parameter/></function>,
328 <function>dallocm<parameter/></function>, and
329 <function>nallocm<parameter/></function> functions all have a
330 <parameter>flags</parameter> argument that can be used to specify
331 options. The functions only check the options that are contextually
332 relevant. Use bitwise or (<code language="C">|</code>) operations to
333 specify one or more of the following:
334 <variablelist>
335 <varlistentry>
336 <term><constant>ALLOCM_LG_ALIGN(<parameter>la</parameter>)
337 </constant></term>
338
339 <listitem><para>Align the memory allocation to start at an address
340 that is a multiple of <code language="C">(1 &lt;&lt;
341 <parameter>la</parameter>)</code>. This macro does not validate
342 that <parameter>la</parameter> is within the valid
343 range.</para></listitem>
344 </varlistentry>
345 <varlistentry>
346 <term><constant>ALLOCM_ALIGN(<parameter>a</parameter>)
347 </constant></term>
348
349 <listitem><para>Align the memory allocation to start at an address
350 that is a multiple of <parameter>a</parameter>, where
351 <parameter>a</parameter> is a power of two. This macro does not
352 validate that <parameter>a</parameter> is a power of 2.
353 </para></listitem>
354 </varlistentry>
355 <varlistentry>
356 <term><constant>ALLOCM_ZERO</constant></term>
357
358 <listitem><para>Initialize newly allocated memory to contain zero
359 bytes. In the growing reallocation case, the real size prior to
360 reallocation defines the boundary between untouched bytes and those
361 that are initialized to contain zero bytes. If this option is
362 absent, newly allocated memory is uninitialized.</para></listitem>
363 </varlistentry>
364 <varlistentry>
365 <term><constant>ALLOCM_NO_MOVE</constant></term>
366
367 <listitem><para>For reallocation, fail rather than moving the
368 object. This constraint can apply to both growth and
369 shrinkage.</para></listitem>
370 </varlistentry>
371 <varlistentry>
372 <term><constant>ALLOCM_ARENA(<parameter>a</parameter>)
373 </constant></term>
374
375 <listitem><para>Use the arena specified by the index
376 <parameter>a</parameter>. This macro does not validate that
377 <parameter>a</parameter> specifies an arena in the valid
378 range.</para></listitem>
379 </varlistentry>
380 </variablelist>
381 </para>
382
383 <para>The <function>allocm<parameter/></function> function allocates at
384 least <parameter>size</parameter> bytes of memory, sets
385 <parameter>*ptr</parameter> to the base address of the allocation, and
386 sets <parameter>*rsize</parameter> to the real size of the allocation if
387 <parameter>rsize</parameter> is not <constant>NULL</constant>. Behavior
388 is undefined if <parameter>size</parameter> is
389 <constant>0</constant>.</para>
390
391 <para>The <function>rallocm<parameter/></function> function resizes the
392 allocation at <parameter>*ptr</parameter> to be at least
393 <parameter>size</parameter> bytes, sets <parameter>*ptr</parameter> to
394 the base address of the allocation if it moved, and sets
395 <parameter>*rsize</parameter> to the real size of the allocation if
396 <parameter>rsize</parameter> is not <constant>NULL</constant>. If
397 <parameter>extra</parameter> is non-zero, an attempt is made to resize
398 the allocation to be at least <code
399 language="C"><parameter>size</parameter> +
400 <parameter>extra</parameter>)</code> bytes, though inability to allocate
401 the extra byte(s) will not by itself result in failure. Behavior is
402 undefined if <parameter>size</parameter> is <constant>0</constant>, or if
403 <code language="C">(<parameter>size</parameter> +
404 <parameter>extra</parameter> &gt;
405 <constant>SIZE_T_MAX</constant>)</code>.</para>
406
407 <para>The <function>sallocm<parameter/></function> function sets
408 <parameter>*rsize</parameter> to the real size of the allocation.</para>
409
410 <para>The <function>dallocm<parameter/></function> function causes the
411 memory referenced by <parameter>ptr</parameter> to be made available for
412 future allocations.</para>
413
414 <para>The <function>nallocm<parameter/></function> function allocates no
415 memory, but it performs the same size computation as the
416 <function>allocm<parameter/></function> function, and if
417 <parameter>rsize</parameter> is not <constant>NULL</constant> it sets
418 <parameter>*rsize</parameter> to the real size of the allocation that
419 would result from the equivalent <function>allocm<parameter/></function>
420 function call. Behavior is undefined if
421 <parameter>size</parameter> is <constant>0</constant>.</para>
422 </refsect2>
423 </refsect1>
424 <refsect1 id="tuning">
425 <title>TUNING</title>
426 <para>Once, when the first call is made to one of the memory allocation
427 routines, the allocator initializes its internals based in part on various
428 options that can be specified at compile- or run-time.</para>
429
430 <para>The string pointed to by the global variable
431 <varname>malloc_conf</varname>, the &ldquo;name&rdquo; of the file
432 referenced by the symbolic link named <filename
433 class="symlink">/etc/malloc.conf</filename>, and the value of the
434 environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in
435 that order, from left to right as options.</para>
436
437 <para>An options string is a comma-separated list of option:value pairs.
438 There is one key corresponding to each <link
439 linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the <xref
440 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for options
441 documentation). For example, <literal>abort:true,narenas:1</literal> sets
442 the <link linkend="opt.abort"><mallctl>opt.abort</mallctl></link> and <link
443 linkend="opt.narenas"><mallctl>opt.narenas</mallctl></link> options. Some
444 options have boolean values (true/false), others have integer values (base
445 8, 10, or 16, depending on prefix), and yet others have raw string
446 values.</para>
447 </refsect1>
448 <refsect1 id="implementation_notes">
449 <title>IMPLEMENTATION NOTES</title>
450 <para>Traditionally, allocators have used
451 <citerefentry><refentrytitle>sbrk</refentrytitle>
452 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is
453 suboptimal for several reasons, including race conditions, increased
454 fragmentation, and artificial limitations on maximum usable memory. If
455 <option>--enable-dss</option> is specified during configuration, this
456 allocator uses both <citerefentry><refentrytitle>mmap</refentrytitle>
457 <manvolnum>2</manvolnum></citerefentry> and
458 <citerefentry><refentrytitle>sbrk</refentrytitle>
459 <manvolnum>2</manvolnum></citerefentry>, in that order of preference;
460 otherwise only <citerefentry><refentrytitle>mmap</refentrytitle>
461 <manvolnum>2</manvolnum></citerefentry> is used.</para>
462
463 <para>This allocator uses multiple arenas in order to reduce lock
464 contention for threaded programs on multi-processor systems. This works
465 well with regard to threading scalability, but incurs some costs. There is
466 a small fixed per-arena overhead, and additionally, arenas manage memory
467 completely independently of each other, which means a small fixed increase
468 in overall memory fragmentation. These overheads are not generally an
469 issue, given the number of arenas normally used. Note that using
470 substantially more arenas than the default is not likely to improve
471 performance, mainly due to reduced cache performance. However, it may make
472 sense to reduce the number of arenas if an application does not make much
473 use of the allocation functions.</para>
474
475 <para>In addition to multiple arenas, unless
476 <option>--disable-tcache</option> is specified during configuration, this
477 allocator supports thread-specific caching for small and large objects, in
478 order to make it possible to completely avoid synchronization for most
479 allocation requests. Such caching allows very fast allocation in the
480 common case, but it increases memory usage and fragmentation, since a
481 bounded number of objects can remain allocated in each thread cache.</para>
482
483 <para>Memory is conceptually broken into equal-sized chunks, where the
484 chunk size is a power of two that is greater than the page size. Chunks
485 are always aligned to multiples of the chunk size. This alignment makes it
486 possible to find metadata for user objects very quickly.</para>
487
488 <para>User objects are broken into three categories according to size:
489 small, large, and huge. Small objects are smaller than one page. Large
490 objects are smaller than the chunk size. Huge objects are a multiple of
491 the chunk size. Small and large objects are managed by arenas; huge
492 objects are managed separately in a single data structure that is shared by
493 all threads. Huge objects are used by applications infrequently enough
494 that this single data structure is not a scalability issue.</para>
495
496 <para>Each chunk that is managed by an arena tracks its contents as runs of
497 contiguous pages (unused, backing a set of small objects, or backing one
498 large object). The combination of chunk alignment and chunk page maps
499 makes it possible to determine all metadata regarding small and large
500 allocations in constant time.</para>
501
502 <para>Small objects are managed in groups by page runs. Each run maintains
503 a frontier and free list to track which regions are in use. Allocation
504 requests that are no more than half the quantum (8 or 16, depending on
505 architecture) are rounded up to the nearest power of two that is at least
506 <code language="C">sizeof(<type>double</type>)</code>. All other small
507 object size classes are multiples of the quantum, spaced such that internal
508 fragmentation is limited to approximately 25% for all but the smallest size
509 classes. Allocation requests that are larger than the maximum small size
510 class, but small enough to fit in an arena-managed chunk (see the <link
511 linkend="opt.lg_chunk"><mallctl>opt.lg_chunk</mallctl></link> option), are
512 rounded up to the nearest run size. Allocation requests that are too large
513 to fit in an arena-managed chunk are rounded up to the nearest multiple of
514 the chunk size.</para>
515
516 <para>Allocations are packed tightly together, which can be an issue for
517 multi-threaded applications. If you need to assure that allocations do not
518 suffer from cacheline sharing, round your allocation requests up to the
519 nearest multiple of the cacheline size, or specify cacheline alignment when
520 allocating.</para>
521
522 <para>Assuming 4 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 64-bit
523 system, the size classes in each category are as shown in <xref
524 linkend="size_classes" xrefstyle="template:Table %n"/>.</para>
525
526 <table xml:id="size_classes" frame="all">
527 <title>Size classes</title>
528 <tgroup cols="3" colsep="1" rowsep="1">
529 <colspec colname="c1" align="left"/>
530 <colspec colname="c2" align="right"/>
531 <colspec colname="c3" align="left"/>
532 <thead>
533 <row>
534 <entry>Category</entry>
535 <entry>Spacing</entry>
536 <entry>Size</entry>
537 </row>
538 </thead>
539 <tbody>
540 <row>
541 <entry morerows="6">Small</entry>
542 <entry>lg</entry>
543 <entry>[8]</entry>
544 </row>
545 <row>
546 <entry>16</entry>
547 <entry>[16, 32, 48, ..., 128]</entry>
548 </row>
549 <row>
550 <entry>32</entry>
551 <entry>[160, 192, 224, 256]</entry>
552 </row>
553 <row>
554 <entry>64</entry>
555 <entry>[320, 384, 448, 512]</entry>
556 </row>
557 <row>
558 <entry>128</entry>
559 <entry>[640, 768, 896, 1024]</entry>
560 </row>
561 <row>
562 <entry>256</entry>
563 <entry>[1280, 1536, 1792, 2048]</entry>
564 </row>
565 <row>
566 <entry>512</entry>
567 <entry>[2560, 3072, 3584]</entry>
568 </row>
569 <row>
570 <entry>Large</entry>
571 <entry>4 KiB</entry>
572 <entry>[4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB]</entry>
573 </row>
574 <row>
575 <entry>Huge</entry>
576 <entry>4 MiB</entry>
577 <entry>[4 MiB, 8 MiB, 12 MiB, ...]</entry>
578 </row>
579 </tbody>
580 </tgroup>
581 </table>
582 </refsect1>
583 <refsect1 id="mallctl_namespace">
584 <title>MALLCTL NAMESPACE</title>
585 <para>The following names are defined in the namespace accessible via the
586 <function>mallctl*<parameter/></function> functions. Value types are
587 specified in parentheses, their readable/writable statuses are encoded as
588 <literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or
589 <literal>--</literal>, and required build configuration flags follow, if
590 any. A name element encoded as <literal>&lt;i&gt;</literal> or
591 <literal>&lt;j&gt;</literal> indicates an integer component, where the
592 integer varies from 0 to some upper value that must be determined via
593 introspection. In the case of <mallctl>stats.arenas.&lt;i&gt;.*</mallctl>,
594 <literal>&lt;i&gt;</literal> equal to <link
595 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> can be
596 used to access the summation of statistics from all arenas. Take special
597 note of the <link linkend="epoch"><mallctl>epoch</mallctl></link> mallctl,
598 which controls refreshing of cached dynamic statistics.</para>
599
600 <variablelist>
601 <varlistentry>
602 <term>
603 <mallctl>version</mallctl>
604 (<type>const char *</type>)
605 <literal>r-</literal>
606 </term>
607 <listitem><para>Return the jemalloc version string.</para></listitem>
608 </varlistentry>
609
610 <varlistentry id="epoch">
611 <term>
612 <mallctl>epoch</mallctl>
613 (<type>uint64_t</type>)
614 <literal>rw</literal>
615 </term>
616 <listitem><para>If a value is passed in, refresh the data from which
617 the <function>mallctl*<parameter/></function> functions report values,
618 and increment the epoch. Return the current epoch. This is useful for
619 detecting whether another thread caused a refresh.</para></listitem>
620 </varlistentry>
621
622 <varlistentry>
623 <term>
624 <mallctl>config.debug</mallctl>
625 (<type>bool</type>)
626 <literal>r-</literal>
627 </term>
628 <listitem><para><option>--enable-debug</option> was specified during
629 build configuration.</para></listitem>
630 </varlistentry>
631
632 <varlistentry>
633 <term>
634 <mallctl>config.dss</mallctl>
635 (<type>bool</type>)
636 <literal>r-</literal>
637 </term>
638 <listitem><para><option>--enable-dss</option> was specified during
639 build configuration.</para></listitem>
640 </varlistentry>
641
642 <varlistentry>
643 <term>
644 <mallctl>config.fill</mallctl>
645 (<type>bool</type>)
646 <literal>r-</literal>
647 </term>
648 <listitem><para><option>--enable-fill</option> was specified during
649 build configuration.</para></listitem>
650 </varlistentry>
651
652 <varlistentry>
653 <term>
654 <mallctl>config.lazy_lock</mallctl>
655 (<type>bool</type>)
656 <literal>r-</literal>
657 </term>
658 <listitem><para><option>--enable-lazy-lock</option> was specified
659 during build configuration.</para></listitem>
660 </varlistentry>
661
662 <varlistentry>
663 <term>
664 <mallctl>config.mremap</mallctl>
665 (<type>bool</type>)
666 <literal>r-</literal>
667 </term>
668 <listitem><para><option>--enable-mremap</option> was specified during
669 build configuration.</para></listitem>
670 </varlistentry>
671
672 <varlistentry>
673 <term>
674 <mallctl>config.munmap</mallctl>
675 (<type>bool</type>)
676 <literal>r-</literal>
677 </term>
678 <listitem><para><option>--enable-munmap</option> was specified during
679 build configuration.</para></listitem>
680 </varlistentry>
681
682 <varlistentry>
683 <term>
684 <mallctl>config.prof</mallctl>
685 (<type>bool</type>)
686 <literal>r-</literal>
687 </term>
688 <listitem><para><option>--enable-prof</option> was specified during
689 build configuration.</para></listitem>
690 </varlistentry>
691
692 <varlistentry>
693 <term>
694 <mallctl>config.prof_libgcc</mallctl>
695 (<type>bool</type>)
696 <literal>r-</literal>
697 </term>
698 <listitem><para><option>--disable-prof-libgcc</option> was not
699 specified during build configuration.</para></listitem>
700 </varlistentry>
701
702 <varlistentry>
703 <term>
704 <mallctl>config.prof_libunwind</mallctl>
705 (<type>bool</type>)
706 <literal>r-</literal>
707 </term>
708 <listitem><para><option>--enable-prof-libunwind</option> was specified
709 during build configuration.</para></listitem>
710 </varlistentry>
711
712 <varlistentry>
713 <term>
714 <mallctl>config.stats</mallctl>
715 (<type>bool</type>)
716 <literal>r-</literal>
717 </term>
718 <listitem><para><option>--enable-stats</option> was specified during
719 build configuration.</para></listitem>
720 </varlistentry>
721
722 <varlistentry>
723 <term>
724 <mallctl>config.tcache</mallctl>
725 (<type>bool</type>)
726 <literal>r-</literal>
727 </term>
728 <listitem><para><option>--disable-tcache</option> was not specified
729 during build configuration.</para></listitem>
730 </varlistentry>
731
732 <varlistentry>
733 <term>
734 <mallctl>config.tls</mallctl>
735 (<type>bool</type>)
736 <literal>r-</literal>
737 </term>
738 <listitem><para><option>--disable-tls</option> was not specified during
739 build configuration.</para></listitem>
740 </varlistentry>
741
742 <varlistentry>
743 <term>
744 <mallctl>config.utrace</mallctl>
745 (<type>bool</type>)
746 <literal>r-</literal>
747 </term>
748 <listitem><para><option>--enable-utrace</option> was specified during
749 build configuration.</para></listitem>
750 </varlistentry>
751
752 <varlistentry>
753 <term>
754 <mallctl>config.valgrind</mallctl>
755 (<type>bool</type>)
756 <literal>r-</literal>
757 </term>
758 <listitem><para><option>--enable-valgrind</option> was specified during
759 build configuration.</para></listitem>
760 </varlistentry>
761
762 <varlistentry>
763 <term>
764 <mallctl>config.xmalloc</mallctl>
765 (<type>bool</type>)
766 <literal>r-</literal>
767 </term>
768 <listitem><para><option>--enable-xmalloc</option> was specified during
769 build configuration.</para></listitem>
770 </varlistentry>
771
772 <varlistentry id="opt.abort">
773 <term>
774 <mallctl>opt.abort</mallctl>
775 (<type>bool</type>)
776 <literal>r-</literal>
777 </term>
778 <listitem><para>Abort-on-warning enabled/disabled. If true, most
779 warnings are fatal. The process will call
780 <citerefentry><refentrytitle>abort</refentrytitle>
781 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is
782 disabled by default unless <option>--enable-debug</option> is
783 specified during configuration, in which case it is enabled by default.
784 </para></listitem>
785 </varlistentry>
786
787 <varlistentry id="opt.lg_chunk">
788 <term>
789 <mallctl>opt.lg_chunk</mallctl>
790 (<type>size_t</type>)
791 <literal>r-</literal>
792 </term>
793 <listitem><para>Virtual memory chunk size (log base 2). The default
794 chunk size is 4 MiB (2^22).</para></listitem>
795 </varlistentry>
796
797 <varlistentry id="opt.dss">
798 <term>
799 <mallctl>opt.dss</mallctl>
800 (<type>const char *</type>)
801 <literal>r-</literal>
802 </term>
803 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle>
804 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as
805 related to <citerefentry><refentrytitle>mmap</refentrytitle>
806 <manvolnum>2</manvolnum></citerefentry> allocation. The following
807 settings are supported: &ldquo;disabled&rdquo;, &ldquo;primary&rdquo;,
808 and &ldquo;secondary&rdquo; (default).</para></listitem>
809 </varlistentry>
810
811 <varlistentry id="opt.narenas">
812 <term>
813 <mallctl>opt.narenas</mallctl>
814 (<type>size_t</type>)
815 <literal>r-</literal>
816 </term>
817 <listitem><para>Maximum number of arenas to use for automatic
818 multiplexing of threads and arenas. The default is four times the
819 number of CPUs, or one if there is a single CPU.</para></listitem>
820 </varlistentry>
821
822 <varlistentry id="opt.lg_dirty_mult">
823 <term>
824 <mallctl>opt.lg_dirty_mult</mallctl>
825 (<type>ssize_t</type>)
826 <literal>r-</literal>
827 </term>
828 <listitem><para>Per-arena minimum ratio (log base 2) of active to dirty
829 pages. Some dirty unused pages may be allowed to accumulate, within
830 the limit set by the ratio (or one chunk worth of dirty pages,
831 whichever is greater), before informing the kernel about some of those
832 pages via <citerefentry><refentrytitle>madvise</refentrytitle>
833 <manvolnum>2</manvolnum></citerefentry> or a similar system call. This
834 provides the kernel with sufficient information to recycle dirty pages
835 if physical memory becomes scarce and the pages remain unused. The
836 default minimum ratio is 8:1 (2^3:1); an option value of -1 will
837 disable dirty page purging.</para></listitem>
838 </varlistentry>
839
840 <varlistentry id="opt.stats_print">
841 <term>
842 <mallctl>opt.stats_print</mallctl>
843 (<type>bool</type>)
844 <literal>r-</literal>
845 </term>
846 <listitem><para>Enable/disable statistics printing at exit. If
847 enabled, the <function>malloc_stats_print<parameter/></function>
848 function is called at program exit via an
849 <citerefentry><refentrytitle>atexit</refentrytitle>
850 <manvolnum>3</manvolnum></citerefentry> function. If
851 <option>--enable-stats</option> is specified during configuration, this
852 has the potential to cause deadlock for a multi-threaded process that
853 exits while one or more threads are executing in the memory allocation
854 functions. Therefore, this option should only be used with care; it is
855 primarily intended as a performance tuning aid during application
856 development. This option is disabled by default.</para></listitem>
857 </varlistentry>
858
859 <varlistentry id="opt.junk">
860 <term>
861 <mallctl>opt.junk</mallctl>
862 (<type>bool</type>)
863 <literal>r-</literal>
864 [<option>--enable-fill</option>]
865 </term>
866 <listitem><para>Junk filling enabled/disabled. If enabled, each byte
867 of uninitialized allocated memory will be initialized to
868 <literal>0xa5</literal>. All deallocated memory will be initialized to
869 <literal>0x5a</literal>. This is intended for debugging and will
870 impact performance negatively. This option is disabled by default
871 unless <option>--enable-debug</option> is specified during
872 configuration, in which case it is enabled by default unless running
873 inside <ulink
874 url="http://valgrind.org/">Valgrind</ulink>.</para></listitem>
875 </varlistentry>
876
877 <varlistentry id="opt.quarantine">
878 <term>
879 <mallctl>opt.quarantine</mallctl>
880 (<type>size_t</type>)
881 <literal>r-</literal>
882 [<option>--enable-fill</option>]
883 </term>
884 <listitem><para>Per thread quarantine size in bytes. If non-zero, each
885 thread maintains a FIFO object quarantine that stores up to the
886 specified number of bytes of memory. The quarantined memory is not
887 freed until it is released from quarantine, though it is immediately
888 junk-filled if the <link
889 linkend="opt.junk"><mallctl>opt.junk</mallctl></link> option is
890 enabled. This feature is of particular use in combination with <ulink
891 url="http://valgrind.org/">Valgrind</ulink>, which can detect attempts
892 to access quarantined objects. This is intended for debugging and will
893 impact performance negatively. The default quarantine size is 0 unless
894 running inside Valgrind, in which case the default is 16
895 MiB.</para></listitem>
896 </varlistentry>
897
898 <varlistentry id="opt.redzone">
899 <term>
900 <mallctl>opt.redzone</mallctl>
901 (<type>bool</type>)
902 <literal>r-</literal>
903 [<option>--enable-fill</option>]
904 </term>
905 <listitem><para>Redzones enabled/disabled. If enabled, small
906 allocations have redzones before and after them. Furthermore, if the
907 <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> option is
908 enabled, the redzones are checked for corruption during deallocation.
909 However, the primary intended purpose of this feature is to be used in
910 combination with <ulink url="http://valgrind.org/">Valgrind</ulink>,
911 which needs redzones in order to do effective buffer overflow/underflow
912 detection. This option is intended for debugging and will impact
913 performance negatively. This option is disabled by
914 default unless running inside Valgrind.</para></listitem>
915 </varlistentry>
916
917 <varlistentry id="opt.zero">
918 <term>
919 <mallctl>opt.zero</mallctl>
920 (<type>bool</type>)
921 <literal>r-</literal>
922 [<option>--enable-fill</option>]
923 </term>
924 <listitem><para>Zero filling enabled/disabled. If enabled, each byte
925 of uninitialized allocated memory will be initialized to 0. Note that
926 this initialization only happens once for each byte, so
927 <function>realloc<parameter/></function> and
928 <function>rallocm<parameter/></function> calls do not zero memory that
929 was previously allocated. This is intended for debugging and will
930 impact performance negatively. This option is disabled by default.
931 </para></listitem>
932 </varlistentry>
933
934 <varlistentry id="opt.utrace">
935 <term>
936 <mallctl>opt.utrace</mallctl>
937 (<type>bool</type>)
938 <literal>r-</literal>
939 [<option>--enable-utrace</option>]
940 </term>
941 <listitem><para>Allocation tracing based on
942 <citerefentry><refentrytitle>utrace</refentrytitle>
943 <manvolnum>2</manvolnum></citerefentry> enabled/disabled. This option
944 is disabled by default.</para></listitem>
945 </varlistentry>
946
947 <varlistentry id="opt.valgrind">
948 <term>
949 <mallctl>opt.valgrind</mallctl>
950 (<type>bool</type>)
951 <literal>r-</literal>
952 [<option>--enable-valgrind</option>]
953 </term>
954 <listitem><para><ulink url="http://valgrind.org/">Valgrind</ulink>
955 support enabled/disabled. This option is vestigal because jemalloc
956 auto-detects whether it is running inside Valgrind. This option is
957 disabled by default, unless running inside Valgrind.</para></listitem>
958 </varlistentry>
959
960 <varlistentry id="opt.xmalloc">
961 <term>
962 <mallctl>opt.xmalloc</mallctl>
963 (<type>bool</type>)
964 <literal>r-</literal>
965 [<option>--enable-xmalloc</option>]
966 </term>
967 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled,
968 rather than returning failure for any allocation function, display a
969 diagnostic message on <constant>STDERR_FILENO</constant> and cause the
970 program to drop core (using
971 <citerefentry><refentrytitle>abort</refentrytitle>
972 <manvolnum>3</manvolnum></citerefentry>). If an application is
973 designed to depend on this behavior, set the option at compile time by
974 including the following in the source code:
975 <programlisting language="C"><![CDATA[
976 malloc_conf = "xmalloc:true";]]></programlisting>
977 This option is disabled by default.</para></listitem>
978 </varlistentry>
979
980 <varlistentry id="opt.tcache">
981 <term>
982 <mallctl>opt.tcache</mallctl>
983 (<type>bool</type>)
984 <literal>r-</literal>
985 [<option>--enable-tcache</option>]
986 </term>
987 <listitem><para>Thread-specific caching enabled/disabled. When there
988 are multiple threads, each thread uses a thread-specific cache for
989 objects up to a certain size. Thread-specific caching allows many
990 allocations to be satisfied without performing any thread
991 synchronization, at the cost of increased memory use. See the
992 <link
993 linkend="opt.lg_tcache_max"><mallctl>opt.lg_tcache_max</mallctl></link>
994 option for related tuning information. This option is enabled by
995 default unless running inside <ulink
996 url="http://valgrind.org/">Valgrind</ulink>.</para></listitem>
997 </varlistentry>
998
999 <varlistentry id="opt.lg_tcache_max">
1000 <term>
1001 <mallctl>opt.lg_tcache_max</mallctl>
1002 (<type>size_t</type>)
1003 <literal>r-</literal>
1004 [<option>--enable-tcache</option>]
1005 </term>
1006 <listitem><para>Maximum size class (log base 2) to cache in the
1007 thread-specific cache. At a minimum, all small size classes are
1008 cached, and at a maximum all large size classes are cached. The
1009 default maximum is 32 KiB (2^15).</para></listitem>
1010 </varlistentry>
1011
1012 <varlistentry id="opt.prof">
1013 <term>
1014 <mallctl>opt.prof</mallctl>
1015 (<type>bool</type>)
1016 <literal>r-</literal>
1017 [<option>--enable-prof</option>]
1018 </term>
1019 <listitem><para>Memory profiling enabled/disabled. If enabled, profile
1020 memory allocation activity. See the <link
1021 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link>
1022 option for on-the-fly activation/deactivation. See the <link
1023 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link>
1024 option for probabilistic sampling control. See the <link
1025 linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link>
1026 option for control of cumulative sample reporting. See the <link
1027 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link>
1028 option for information on interval-triggered profile dumping, the <link
1029 linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link>
1030 option for information on high-water-triggered profile dumping, and the
1031 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link>
1032 option for final profile dumping. Profile output is compatible with
1033 the included <command>pprof</command> Perl script, which originates
1034 from the <ulink url="http://code.google.com/p/gperftools/">gperftools
1035 package</ulink>.</para></listitem>
1036 </varlistentry>
1037
1038 <varlistentry id="opt.prof_prefix">
1039 <term>
1040 <mallctl>opt.prof_prefix</mallctl>
1041 (<type>const char *</type>)
1042 <literal>r-</literal>
1043 [<option>--enable-prof</option>]
1044 </term>
1045 <listitem><para>Filename prefix for profile dumps. If the prefix is
1046 set to the empty string, no automatic dumps will occur; this is
1047 primarily useful for disabling the automatic final heap dump (which
1048 also disables leak reporting, if enabled). The default prefix is
1049 <filename>jeprof</filename>.</para></listitem>
1050 </varlistentry>
1051
1052 <varlistentry id="opt.prof_active">
1053 <term>
1054 <mallctl>opt.prof_active</mallctl>
1055 (<type>bool</type>)
1056 <literal>r-</literal>
1057 [<option>--enable-prof</option>]
1058 </term>
1059 <listitem><para>Profiling activated/deactivated. This is a secondary
1060 control mechanism that makes it possible to start the application with
1061 profiling enabled (see the <link
1062 linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but
1063 inactive, then toggle profiling at any time during program execution
1064 with the <link
1065 linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl.
1066 This option is enabled by default.</para></listitem>
1067 </varlistentry>
1068
1069 <varlistentry id="opt.lg_prof_sample">
1070 <term>
1071 <mallctl>opt.lg_prof_sample</mallctl>
1072 (<type>ssize_t</type>)
1073 <literal>r-</literal>
1074 [<option>--enable-prof</option>]
1075 </term>
1076 <listitem><para>Average interval (log base 2) between allocation
1077 samples, as measured in bytes of allocation activity. Increasing the
1078 sampling interval decreases profile fidelity, but also decreases the
1079 computational overhead. The default sample interval is 512 KiB (2^19
1080 B).</para></listitem>
1081 </varlistentry>
1082
1083 <varlistentry id="opt.prof_accum">
1084 <term>
1085 <mallctl>opt.prof_accum</mallctl>
1086 (<type>bool</type>)
1087 <literal>r-</literal>
1088 [<option>--enable-prof</option>]
1089 </term>
1090 <listitem><para>Reporting of cumulative object/byte counts in profile
1091 dumps enabled/disabled. If this option is enabled, every unique
1092 backtrace must be stored for the duration of execution. Depending on
1093 the application, this can impose a large memory overhead, and the
1094 cumulative counts are not always of interest. This option is disabled
1095 by default.</para></listitem>
1096 </varlistentry>
1097
1098 <varlistentry id="opt.lg_prof_interval">
1099 <term>
1100 <mallctl>opt.lg_prof_interval</mallctl>
1101 (<type>ssize_t</type>)
1102 <literal>r-</literal>
1103 [<option>--enable-prof</option>]
1104 </term>
1105 <listitem><para>Average interval (log base 2) between memory profile
1106 dumps, as measured in bytes of allocation activity. The actual
1107 interval between dumps may be sporadic because decentralized allocation
1108 counters are used to avoid synchronization bottlenecks. Profiles are
1109 dumped to files named according to the pattern
1110 <filename>&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.i&lt;iseq&gt;.heap</filename>,
1111 where <literal>&lt;prefix&gt;</literal> is controlled by the
1112 <link
1113 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link>
1114 option. By default, interval-triggered profile dumping is disabled
1115 (encoded as -1).
1116 </para></listitem>
1117 </varlistentry>
1118
1119 <varlistentry id="opt.prof_gdump">
1120 <term>
1121 <mallctl>opt.prof_gdump</mallctl>
1122 (<type>bool</type>)
1123 <literal>r-</literal>
1124 [<option>--enable-prof</option>]
1125 </term>
1126 <listitem><para>Trigger a memory profile dump every time the total
1127 virtual memory exceeds the previous maximum. Profiles are dumped to
1128 files named according to the pattern
1129 <filename>&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.u&lt;useq&gt;.heap</filename>,
1130 where <literal>&lt;prefix&gt;</literal> is controlled by the <link
1131 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link>
1132 option. This option is disabled by default.</para></listitem>
1133 </varlistentry>
1134
1135 <varlistentry id="opt.prof_final">
1136 <term>
1137 <mallctl>opt.prof_final</mallctl>
1138 (<type>bool</type>)
1139 <literal>r-</literal>
1140 [<option>--enable-prof</option>]
1141 </term>
1142 <listitem><para>Use an
1143 <citerefentry><refentrytitle>atexit</refentrytitle>
1144 <manvolnum>3</manvolnum></citerefentry> function to dump final memory
1145 usage to a file named according to the pattern
1146 <filename>&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.f.heap</filename>,
1147 where <literal>&lt;prefix&gt;</literal> is controlled by the <link
1148 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link>
1149 option. This option is enabled by default.</para></listitem>
1150 </varlistentry>
1151
1152 <varlistentry id="opt.prof_leak">
1153 <term>
1154 <mallctl>opt.prof_leak</mallctl>
1155 (<type>bool</type>)
1156 <literal>r-</literal>
1157 [<option>--enable-prof</option>]
1158 </term>
1159 <listitem><para>Leak reporting enabled/disabled. If enabled, use an
1160 <citerefentry><refentrytitle>atexit</refentrytitle>
1161 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks
1162 detected by allocation sampling. See the
1163 <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for
1164 information on analyzing heap profile output. This option is disabled
1165 by default.</para></listitem>
1166 </varlistentry>
1167
1168 <varlistentry>
1169 <term>
1170 <mallctl>thread.arena</mallctl>
1171 (<type>unsigned</type>)
1172 <literal>rw</literal>
1173 </term>
1174 <listitem><para>Get or set the arena associated with the calling
1175 thread. If the specified arena was not initialized beforehand (see the
1176 <link
1177 linkend="arenas.initialized"><mallctl>arenas.initialized</mallctl></link>
1178 mallctl), it will be automatically initialized as a side effect of
1179 calling this interface.</para></listitem>
1180 </varlistentry>
1181
1182 <varlistentry id="thread.allocated">
1183 <term>
1184 <mallctl>thread.allocated</mallctl>
1185 (<type>uint64_t</type>)
1186 <literal>r-</literal>
1187 [<option>--enable-stats</option>]
1188 </term>
1189 <listitem><para>Get the total number of bytes ever allocated by the
1190 calling thread. This counter has the potential to wrap around; it is
1191 up to the application to appropriately interpret the counter in such
1192 cases.</para></listitem>
1193 </varlistentry>
1194
1195 <varlistentry>
1196 <term>
1197 <mallctl>thread.allocatedp</mallctl>
1198 (<type>uint64_t *</type>)
1199 <literal>r-</literal>
1200 [<option>--enable-stats</option>]
1201 </term>
1202 <listitem><para>Get a pointer to the the value that is returned by the
1203 <link
1204 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link>
1205 mallctl. This is useful for avoiding the overhead of repeated
1206 <function>mallctl*<parameter/></function> calls.</para></listitem>
1207 </varlistentry>
1208
1209 <varlistentry id="thread.deallocated">
1210 <term>
1211 <mallctl>thread.deallocated</mallctl>
1212 (<type>uint64_t</type>)
1213 <literal>r-</literal>
1214 [<option>--enable-stats</option>]
1215 </term>
1216 <listitem><para>Get the total number of bytes ever deallocated by the
1217 calling thread. This counter has the potential to wrap around; it is
1218 up to the application to appropriately interpret the counter in such
1219 cases.</para></listitem>
1220 </varlistentry>
1221
1222 <varlistentry>
1223 <term>
1224 <mallctl>thread.deallocatedp</mallctl>
1225 (<type>uint64_t *</type>)
1226 <literal>r-</literal>
1227 [<option>--enable-stats</option>]
1228 </term>
1229 <listitem><para>Get a pointer to the the value that is returned by the
1230 <link
1231 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link>
1232 mallctl. This is useful for avoiding the overhead of repeated
1233 <function>mallctl*<parameter/></function> calls.</para></listitem>
1234 </varlistentry>
1235
1236 <varlistentry>
1237 <term>
1238 <mallctl>thread.tcache.enabled</mallctl>
1239 (<type>bool</type>)
1240 <literal>rw</literal>
1241 [<option>--enable-tcache</option>]
1242 </term>
1243 <listitem><para>Enable/disable calling thread's tcache. The tcache is
1244 implicitly flushed as a side effect of becoming
1245 disabled (see <link
1246 lenkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>).
1247 </para></listitem>
1248 </varlistentry>
1249
1250 <varlistentry>
1251 <term>
1252 <mallctl>thread.tcache.flush</mallctl>
1253 (<type>void</type>)
1254 <literal>--</literal>
1255 [<option>--enable-tcache</option>]
1256 </term>
1257 <listitem><para>Flush calling thread's tcache. This interface releases
1258 all cached objects and internal data structures associated with the
1259 calling thread's thread-specific cache. Ordinarily, this interface
1260 need not be called, since automatic periodic incremental garbage
1261 collection occurs, and the thread cache is automatically discarded when
1262 a thread exits. However, garbage collection is triggered by allocation
1263 activity, so it is possible for a thread that stops
1264 allocating/deallocating to retain its cache indefinitely, in which case
1265 the developer may find manual flushing useful.</para></listitem>
1266 </varlistentry>
1267
1268 <varlistentry id="arena.i.purge">
1269 <term>
1270 <mallctl>arena.&lt;i&gt;.purge</mallctl>
1271 (<type>unsigned</type>)
1272 <literal>--</literal>
1273 </term>
1274 <listitem><para>Purge unused dirty pages for arena &lt;i&gt;, or for
1275 all arenas if &lt;i&gt; equals <link
1276 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link>.
1277 </para></listitem>
1278 </varlistentry>
1279
1280 <varlistentry id="arena.i.dss">
1281 <term>
1282 <mallctl>arena.&lt;i&gt;.dss</mallctl>
1283 (<type>const char *</type>)
1284 <literal>rw</literal>
1285 </term>
1286 <listitem><para>Set the precedence of dss allocation as related to mmap
1287 allocation for arena &lt;i&gt;, or for all arenas if &lt;i&gt; equals
1288 <link
1289 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link>. See
1290 <link linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for supported
1291 settings.
1292 </para></listitem>
1293 </varlistentry>
1294
1295 <varlistentry id="arenas.narenas">
1296 <term>
1297 <mallctl>arenas.narenas</mallctl>
1298 (<type>unsigned</type>)
1299 <literal>r-</literal>
1300 </term>
1301 <listitem><para>Current limit on number of arenas.</para></listitem>
1302 </varlistentry>
1303
1304 <varlistentry id="arenas.initialized">
1305 <term>
1306 <mallctl>arenas.initialized</mallctl>
1307 (<type>bool *</type>)
1308 <literal>r-</literal>
1309 </term>
1310 <listitem><para>An array of <link
1311 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link>
1312 booleans. Each boolean indicates whether the corresponding arena is
1313 initialized.</para></listitem>
1314 </varlistentry>
1315
1316 <varlistentry>
1317 <term>
1318 <mallctl>arenas.quantum</mallctl>
1319 (<type>size_t</type>)
1320 <literal>r-</literal>
1321 </term>
1322 <listitem><para>Quantum size.</para></listitem>
1323 </varlistentry>
1324
1325 <varlistentry>
1326 <term>
1327 <mallctl>arenas.page</mallctl>
1328 (<type>size_t</type>)
1329 <literal>r-</literal>
1330 </term>
1331 <listitem><para>Page size.</para></listitem>
1332 </varlistentry>
1333
1334 <varlistentry>
1335 <term>
1336 <mallctl>arenas.tcache_max</mallctl>
1337 (<type>size_t</type>)
1338 <literal>r-</literal>
1339 [<option>--enable-tcache</option>]
1340 </term>
1341 <listitem><para>Maximum thread-cached size class.</para></listitem>
1342 </varlistentry>
1343
1344 <varlistentry>
1345 <term>
1346 <mallctl>arenas.nbins</mallctl>
1347 (<type>unsigned</type>)
1348 <literal>r-</literal>
1349 </term>
1350 <listitem><para>Number of bin size classes.</para></listitem>
1351 </varlistentry>
1352
1353 <varlistentry>
1354 <term>
1355 <mallctl>arenas.nhbins</mallctl>
1356 (<type>unsigned</type>)
1357 <literal>r-</literal>
1358 [<option>--enable-tcache</option>]
1359 </term>
1360 <listitem><para>Total number of thread cache bin size
1361 classes.</para></listitem>
1362 </varlistentry>
1363
1364 <varlistentry id="arenas.bin.i.size">
1365 <term>
1366 <mallctl>arenas.bin.&lt;i&gt;.size</mallctl>
1367 (<type>size_t</type>)
1368 <literal>r-</literal>
1369 </term>
1370 <listitem><para>Maximum size supported by size class.</para></listitem>
1371 </varlistentry>
1372
1373 <varlistentry>
1374 <term>
1375 <mallctl>arenas.bin.&lt;i&gt;.nregs</mallctl>
1376 (<type>uint32_t</type>)
1377 <literal>r-</literal>
1378 </term>
1379 <listitem><para>Number of regions per page run.</para></listitem>
1380 </varlistentry>
1381
1382 <varlistentry>
1383 <term>
1384 <mallctl>arenas.bin.&lt;i&gt;.run_size</mallctl>
1385 (<type>size_t</type>)
1386 <literal>r-</literal>
1387 </term>
1388 <listitem><para>Number of bytes per page run.</para></listitem>
1389 </varlistentry>
1390
1391 <varlistentry>
1392 <term>
1393 <mallctl>arenas.nlruns</mallctl>
1394 (<type>size_t</type>)
1395 <literal>r-</literal>
1396 </term>
1397 <listitem><para>Total number of large size classes.</para></listitem>
1398 </varlistentry>
1399
1400 <varlistentry>
1401 <term>
1402 <mallctl>arenas.lrun.&lt;i&gt;.size</mallctl>
1403 (<type>size_t</type>)
1404 <literal>r-</literal>
1405 </term>
1406 <listitem><para>Maximum size supported by this large size
1407 class.</para></listitem>
1408 </varlistentry>
1409
1410 <varlistentry>
1411 <term>
1412 <mallctl>arenas.purge</mallctl>
1413 (<type>unsigned</type>)
1414 <literal>-w</literal>
1415 </term>
1416 <listitem><para>Purge unused dirty pages for the specified arena, or
1417 for all arenas if none is specified.</para></listitem>
1418 </varlistentry>
1419
1420 <varlistentry>
1421 <term>
1422 <mallctl>arenas.extend</mallctl>
1423 (<type>unsigned</type>)
1424 <literal>r-</literal>
1425 </term>
1426 <listitem><para>Extend the array of arenas by appending a new arena,
1427 and returning the new arena index.</para></listitem>
1428 </varlistentry>
1429
1430 <varlistentry id="prof.active">
1431 <term>
1432 <mallctl>prof.active</mallctl>
1433 (<type>bool</type>)
1434 <literal>rw</literal>
1435 [<option>--enable-prof</option>]
1436 </term>
1437 <listitem><para>Control whether sampling is currently active. See the
1438 <link
1439 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link>
1440 option for additional information.
1441 </para></listitem>
1442 </varlistentry>
1443
1444 <varlistentry>
1445 <term>
1446 <mallctl>prof.dump</mallctl>
1447 (<type>const char *</type>)
1448 <literal>-w</literal>
1449 [<option>--enable-prof</option>]
1450 </term>
1451 <listitem><para>Dump a memory profile to the specified file, or if NULL
1452 is specified, to a file according to the pattern
1453 <filename>&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.m&lt;mseq&gt;.heap</filename>,
1454 where <literal>&lt;prefix&gt;</literal> is controlled by the
1455 <link
1456 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link>
1457 option.</para></listitem>
1458 </varlistentry>
1459
1460 <varlistentry>
1461 <term>
1462 <mallctl>prof.interval</mallctl>
1463 (<type>uint64_t</type>)
1464 <literal>r-</literal>
1465 [<option>--enable-prof</option>]
1466 </term>
1467 <listitem><para>Average number of bytes allocated between
1468 inverval-based profile dumps. See the
1469 <link
1470 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link>
1471 option for additional information.</para></listitem>
1472 </varlistentry>
1473
1474 <varlistentry id="stats.cactive">
1475 <term>
1476 <mallctl>stats.cactive</mallctl>
1477 (<type>size_t *</type>)
1478 <literal>r-</literal>
1479 [<option>--enable-stats</option>]
1480 </term>
1481 <listitem><para>Pointer to a counter that contains an approximate count
1482 of the current number of bytes in active pages. The estimate may be
1483 high, but never low, because each arena rounds up to the nearest
1484 multiple of the chunk size when computing its contribution to the
1485 counter. Note that the <link
1486 linkend="epoch"><mallctl>epoch</mallctl></link> mallctl has no bearing
1487 on this counter. Furthermore, counter consistency is maintained via
1488 atomic operations, so it is necessary to use an atomic operation in
1489 order to guarantee a consistent read when dereferencing the pointer.
1490 </para></listitem>
1491 </varlistentry>
1492
1493 <varlistentry id="stats.allocated">
1494 <term>
1495 <mallctl>stats.allocated</mallctl>
1496 (<type>size_t</type>)
1497 <literal>r-</literal>
1498 [<option>--enable-stats</option>]
1499 </term>
1500 <listitem><para>Total number of bytes allocated by the
1501 application.</para></listitem>
1502 </varlistentry>
1503
1504 <varlistentry id="stats.active">
1505 <term>
1506 <mallctl>stats.active</mallctl>
1507 (<type>size_t</type>)
1508 <literal>r-</literal>
1509 [<option>--enable-stats</option>]
1510 </term>
1511 <listitem><para>Total number of bytes in active pages allocated by the
1512 application. This is a multiple of the page size, and greater than or
1513 equal to <link
1514 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>.
1515 This does not include <link linkend="stats.arenas.i.pdirty">
1516 <mallctl>stats.arenas.&lt;i&gt;.pdirty</mallctl></link> and pages
1517 entirely devoted to allocator metadata.</para></listitem>
1518 </varlistentry>
1519
1520 <varlistentry>
1521 <term>
1522 <mallctl>stats.mapped</mallctl>
1523 (<type>size_t</type>)
1524 <literal>r-</literal>
1525 [<option>--enable-stats</option>]
1526 </term>
1527 <listitem><para>Total number of bytes in chunks mapped on behalf of the
1528 application. This is a multiple of the chunk size, and is at least as
1529 large as <link
1530 linkend="stats.active"><mallctl>stats.active</mallctl></link>. This
1531 does not include inactive chunks.</para></listitem>
1532 </varlistentry>
1533
1534 <varlistentry>
1535 <term>
1536 <mallctl>stats.chunks.current</mallctl>
1537 (<type>size_t</type>)
1538 <literal>r-</literal>
1539 [<option>--enable-stats</option>]
1540 </term>
1541 <listitem><para>Total number of chunks actively mapped on behalf of the
1542 application. This does not include inactive chunks.
1543 </para></listitem>
1544 </varlistentry>
1545
1546 <varlistentry>
1547 <term>
1548 <mallctl>stats.chunks.total</mallctl>
1549 (<type>uint64_t</type>)
1550 <literal>r-</literal>
1551 [<option>--enable-stats</option>]
1552 </term>
1553 <listitem><para>Cumulative number of chunks allocated.</para></listitem>
1554 </varlistentry>
1555
1556 <varlistentry>
1557 <term>
1558 <mallctl>stats.chunks.high</mallctl>
1559 (<type>size_t</type>)
1560 <literal>r-</literal>
1561 [<option>--enable-stats</option>]
1562 </term>
1563 <listitem><para>Maximum number of active chunks at any time thus far.
1564 </para></listitem>
1565 </varlistentry>
1566
1567 <varlistentry>
1568 <term>
1569 <mallctl>stats.huge.allocated</mallctl>
1570 (<type>size_t</type>)
1571 <literal>r-</literal>
1572 [<option>--enable-stats</option>]
1573 </term>
1574 <listitem><para>Number of bytes currently allocated by huge objects.
1575 </para></listitem>
1576 </varlistentry>
1577
1578 <varlistentry>
1579 <term>
1580 <mallctl>stats.huge.nmalloc</mallctl>
1581 (<type>uint64_t</type>)
1582 <literal>r-</literal>
1583 [<option>--enable-stats</option>]
1584 </term>
1585 <listitem><para>Cumulative number of huge allocation requests.
1586 </para></listitem>
1587 </varlistentry>
1588
1589 <varlistentry>
1590 <term>
1591 <mallctl>stats.huge.ndalloc</mallctl>
1592 (<type>uint64_t</type>)
1593 <literal>r-</literal>
1594 [<option>--enable-stats</option>]
1595 </term>
1596 <listitem><para>Cumulative number of huge deallocation requests.
1597 </para></listitem>
1598 </varlistentry>
1599
1600 <varlistentry>
1601 <term>
1602 <mallctl>stats.arenas.&lt;i&gt;.dss</mallctl>
1603 (<type>const char *</type>)
1604 <literal>r-</literal>
1605 </term>
1606 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle>
1607 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as
1608 related to <citerefentry><refentrytitle>mmap</refentrytitle>
1609 <manvolnum>2</manvolnum></citerefentry> allocation. See <link
1610 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for details.
1611 </para></listitem>
1612 </varlistentry>
1613
1614 <varlistentry>
1615 <term>
1616 <mallctl>stats.arenas.&lt;i&gt;.nthreads</mallctl>
1617 (<type>unsigned</type>)
1618 <literal>r-</literal>
1619 </term>
1620 <listitem><para>Number of threads currently assigned to
1621 arena.</para></listitem>
1622 </varlistentry>
1623
1624 <varlistentry>
1625 <term>
1626 <mallctl>stats.arenas.&lt;i&gt;.pactive</mallctl>
1627 (<type>size_t</type>)
1628 <literal>r-</literal>
1629 </term>
1630 <listitem><para>Number of pages in active runs.</para></listitem>
1631 </varlistentry>
1632
1633 <varlistentry id="stats.arenas.i.pdirty">
1634 <term>
1635 <mallctl>stats.arenas.&lt;i&gt;.pdirty</mallctl>
1636 (<type>size_t</type>)
1637 <literal>r-</literal>
1638 </term>
1639 <listitem><para>Number of pages within unused runs that are potentially
1640 dirty, and for which <function>madvise<parameter>...</parameter>
1641 <parameter><constant>MADV_DONTNEED</constant></parameter></function> or
1642 similar has not been called.</para></listitem>
1643 </varlistentry>
1644
1645 <varlistentry>
1646 <term>
1647 <mallctl>stats.arenas.&lt;i&gt;.mapped</mallctl>
1648 (<type>size_t</type>)
1649 <literal>r-</literal>
1650 [<option>--enable-stats</option>]
1651 </term>
1652 <listitem><para>Number of mapped bytes.</para></listitem>
1653 </varlistentry>
1654
1655 <varlistentry>
1656 <term>
1657 <mallctl>stats.arenas.&lt;i&gt;.npurge</mallctl>
1658 (<type>uint64_t</type>)
1659 <literal>r-</literal>
1660 [<option>--enable-stats</option>]
1661 </term>
1662 <listitem><para>Number of dirty page purge sweeps performed.
1663 </para></listitem>
1664 </varlistentry>
1665
1666 <varlistentry>
1667 <term>
1668 <mallctl>stats.arenas.&lt;i&gt;.nmadvise</mallctl>
1669 (<type>uint64_t</type>)
1670 <literal>r-</literal>
1671 [<option>--enable-stats</option>]
1672 </term>
1673 <listitem><para>Number of <function>madvise<parameter>...</parameter>
1674 <parameter><constant>MADV_DONTNEED</constant></parameter></function> or
1675 similar calls made to purge dirty pages.</para></listitem>
1676 </varlistentry>
1677
1678 <varlistentry>
1679 <term>
1680 <mallctl>stats.arenas.&lt;i&gt;.npurged</mallctl>
1681 (<type>uint64_t</type>)
1682 <literal>r-</literal>
1683 [<option>--enable-stats</option>]
1684 </term>
1685 <listitem><para>Number of pages purged.</para></listitem>
1686 </varlistentry>
1687
1688 <varlistentry>
1689 <term>
1690 <mallctl>stats.arenas.&lt;i&gt;.small.allocated</mallctl>
1691 (<type>size_t</type>)
1692 <literal>r-</literal>
1693 [<option>--enable-stats</option>]
1694 </term>
1695 <listitem><para>Number of bytes currently allocated by small objects.
1696 </para></listitem>
1697 </varlistentry>
1698
1699 <varlistentry>
1700 <term>
1701 <mallctl>stats.arenas.&lt;i&gt;.small.nmalloc</mallctl>
1702 (<type>uint64_t</type>)
1703 <literal>r-</literal>
1704 [<option>--enable-stats</option>]
1705 </term>
1706 <listitem><para>Cumulative number of allocation requests served by
1707 small bins.</para></listitem>
1708 </varlistentry>
1709
1710 <varlistentry>
1711 <term>
1712 <mallctl>stats.arenas.&lt;i&gt;.small.ndalloc</mallctl>
1713 (<type>uint64_t</type>)
1714 <literal>r-</literal>
1715 [<option>--enable-stats</option>]
1716 </term>
1717 <listitem><para>Cumulative number of small objects returned to bins.
1718 </para></listitem>
1719 </varlistentry>
1720
1721 <varlistentry>
1722 <term>
1723 <mallctl>stats.arenas.&lt;i&gt;.small.nrequests</mallctl>
1724 (<type>uint64_t</type>)
1725 <literal>r-</literal>
1726 [<option>--enable-stats</option>]
1727 </term>
1728 <listitem><para>Cumulative number of small allocation requests.
1729 </para></listitem>
1730 </varlistentry>
1731
1732 <varlistentry>
1733 <term>
1734 <mallctl>stats.arenas.&lt;i&gt;.large.allocated</mallctl>
1735 (<type>size_t</type>)
1736 <literal>r-</literal>
1737 [<option>--enable-stats</option>]
1738 </term>
1739 <listitem><para>Number of bytes currently allocated by large objects.
1740 </para></listitem>
1741 </varlistentry>
1742
1743 <varlistentry>
1744 <term>
1745 <mallctl>stats.arenas.&lt;i&gt;.large.nmalloc</mallctl>
1746 (<type>uint64_t</type>)
1747 <literal>r-</literal>
1748 [<option>--enable-stats</option>]
1749 </term>
1750 <listitem><para>Cumulative number of large allocation requests served
1751 directly by the arena.</para></listitem>
1752 </varlistentry>
1753
1754 <varlistentry>
1755 <term>
1756 <mallctl>stats.arenas.&lt;i&gt;.large.ndalloc</mallctl>
1757 (<type>uint64_t</type>)
1758 <literal>r-</literal>
1759 [<option>--enable-stats</option>]
1760 </term>
1761 <listitem><para>Cumulative number of large deallocation requests served
1762 directly by the arena.</para></listitem>
1763 </varlistentry>
1764
1765 <varlistentry>
1766 <term>
1767 <mallctl>stats.arenas.&lt;i&gt;.large.nrequests</mallctl>
1768 (<type>uint64_t</type>)
1769 <literal>r-</literal>
1770 [<option>--enable-stats</option>]
1771 </term>
1772 <listitem><para>Cumulative number of large allocation requests.
1773 </para></listitem>
1774 </varlistentry>
1775
1776 <varlistentry>
1777 <term>
1778 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.allocated</mallctl>
1779 (<type>size_t</type>)
1780 <literal>r-</literal>
1781 [<option>--enable-stats</option>]
1782 </term>
1783 <listitem><para>Current number of bytes allocated by
1784 bin.</para></listitem>
1785 </varlistentry>
1786
1787 <varlistentry>
1788 <term>
1789 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nmalloc</mallctl>
1790 (<type>uint64_t</type>)
1791 <literal>r-</literal>
1792 [<option>--enable-stats</option>]
1793 </term>
1794 <listitem><para>Cumulative number of allocations served by bin.
1795 </para></listitem>
1796 </varlistentry>
1797
1798 <varlistentry>
1799 <term>
1800 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.ndalloc</mallctl>
1801 (<type>uint64_t</type>)
1802 <literal>r-</literal>
1803 [<option>--enable-stats</option>]
1804 </term>
1805 <listitem><para>Cumulative number of allocations returned to bin.
1806 </para></listitem>
1807 </varlistentry>
1808
1809 <varlistentry>
1810 <term>
1811 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nrequests</mallctl>
1812 (<type>uint64_t</type>)
1813 <literal>r-</literal>
1814 [<option>--enable-stats</option>]
1815 </term>
1816 <listitem><para>Cumulative number of allocation
1817 requests.</para></listitem>
1818 </varlistentry>
1819
1820 <varlistentry>
1821 <term>
1822 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nfills</mallctl>
1823 (<type>uint64_t</type>)
1824 <literal>r-</literal>
1825 [<option>--enable-stats</option> <option>--enable-tcache</option>]
1826 </term>
1827 <listitem><para>Cumulative number of tcache fills.</para></listitem>
1828 </varlistentry>
1829
1830 <varlistentry>
1831 <term>
1832 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nflushes</mallctl>
1833 (<type>uint64_t</type>)
1834 <literal>r-</literal>
1835 [<option>--enable-stats</option> <option>--enable-tcache</option>]
1836 </term>
1837 <listitem><para>Cumulative number of tcache flushes.</para></listitem>
1838 </varlistentry>
1839
1840 <varlistentry>
1841 <term>
1842 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nruns</mallctl>
1843 (<type>uint64_t</type>)
1844 <literal>r-</literal>
1845 [<option>--enable-stats</option>]
1846 </term>
1847 <listitem><para>Cumulative number of runs created.</para></listitem>
1848 </varlistentry>
1849
1850 <varlistentry>
1851 <term>
1852 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nreruns</mallctl>
1853 (<type>uint64_t</type>)
1854 <literal>r-</literal>
1855 [<option>--enable-stats</option>]
1856 </term>
1857 <listitem><para>Cumulative number of times the current run from which
1858 to allocate changed.</para></listitem>
1859 </varlistentry>
1860
1861 <varlistentry>
1862 <term>
1863 <mallctl>stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.curruns</mallctl>
1864 (<type>size_t</type>)
1865 <literal>r-</literal>
1866 [<option>--enable-stats</option>]
1867 </term>
1868 <listitem><para>Current number of runs.</para></listitem>
1869 </varlistentry>
1870
1871 <varlistentry>
1872 <term>
1873 <mallctl>stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.nmalloc</mallctl>
1874 (<type>uint64_t</type>)
1875 <literal>r-</literal>
1876 [<option>--enable-stats</option>]
1877 </term>
1878 <listitem><para>Cumulative number of allocation requests for this size
1879 class served directly by the arena.</para></listitem>
1880 </varlistentry>
1881
1882 <varlistentry>
1883 <term>
1884 <mallctl>stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.ndalloc</mallctl>
1885 (<type>uint64_t</type>)
1886 <literal>r-</literal>
1887 [<option>--enable-stats</option>]
1888 </term>
1889 <listitem><para>Cumulative number of deallocation requests for this
1890 size class served directly by the arena.</para></listitem>
1891 </varlistentry>
1892
1893 <varlistentry>
1894 <term>
1895 <mallctl>stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.nrequests</mallctl>
1896 (<type>uint64_t</type>)
1897 <literal>r-</literal>
1898 [<option>--enable-stats</option>]
1899 </term>
1900 <listitem><para>Cumulative number of allocation requests for this size
1901 class.</para></listitem>
1902 </varlistentry>
1903
1904 <varlistentry>
1905 <term>
1906 <mallctl>stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.curruns</mallctl>
1907 (<type>size_t</type>)
1908 <literal>r-</literal>
1909 [<option>--enable-stats</option>]
1910 </term>
1911 <listitem><para>Current number of runs for this size class.
1912 </para></listitem>
1913 </varlistentry>
1914 </variablelist>
1915 </refsect1>
1916 <refsect1 id="debugging_malloc_problems">
1917 <title>DEBUGGING MALLOC PROBLEMS</title>
1918 <para>When debugging, it is a good idea to configure/build jemalloc with
1919 the <option>--enable-debug</option> and <option>--enable-fill</option>
1920 options, and recompile the program with suitable options and symbols for
1921 debugger support. When so configured, jemalloc incorporates a wide variety
1922 of run-time assertions that catch application errors such as double-free,
1923 write-after-free, etc.</para>
1924
1925 <para>Programs often accidentally depend on &ldquo;uninitialized&rdquo;
1926 memory actually being filled with zero bytes. Junk filling
1927 (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link>
1928 option) tends to expose such bugs in the form of obviously incorrect
1929 results and/or coredumps. Conversely, zero
1930 filling (see the <link
1931 linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates
1932 the symptoms of such bugs. Between these two options, it is usually
1933 possible to quickly detect, diagnose, and eliminate such bugs.</para>
1934
1935 <para>This implementation does not provide much detail about the problems
1936 it detects, because the performance impact for storing such information
1937 would be prohibitive. However, jemalloc does integrate with the most
1938 excellent <ulink url="http://valgrind.org/">Valgrind</ulink> tool if the
1939 <option>--enable-valgrind</option> configuration option is enabled.</para>
1940 </refsect1>
1941 <refsect1 id="diagnostic_messages">
1942 <title>DIAGNOSTIC MESSAGES</title>
1943 <para>If any of the memory allocation/deallocation functions detect an
1944 error or warning condition, a message will be printed to file descriptor
1945 <constant>STDERR_FILENO</constant>. Errors will result in the process
1946 dumping core. If the <link
1947 linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most
1948 warnings are treated as errors.</para>
1949
1950 <para>The <varname>malloc_message</varname> variable allows the programmer
1951 to override the function which emits the text strings forming the errors
1952 and warnings if for some reason the <constant>STDERR_FILENO</constant> file
1953 descriptor is not suitable for this.
1954 <function>malloc_message<parameter/></function> takes the
1955 <parameter>cbopaque</parameter> pointer argument that is
1956 <constant>NULL</constant> unless overridden by the arguments in a call to
1957 <function>malloc_stats_print<parameter/></function>, followed by a string
1958 pointer. Please note that doing anything which tries to allocate memory in
1959 this function is likely to result in a crash or deadlock.</para>
1960
1961 <para>All messages are prefixed by
1962 &ldquo;<computeroutput>&lt;jemalloc&gt;: </computeroutput>&rdquo;.</para>
1963 </refsect1>
1964 <refsect1 id="return_values">
1965 <title>RETURN VALUES</title>
1966 <refsect2>
1967 <title>Standard API</title>
1968 <para>The <function>malloc<parameter/></function> and
1969 <function>calloc<parameter/></function> functions return a pointer to the
1970 allocated memory if successful; otherwise a <constant>NULL</constant>
1971 pointer is returned and <varname>errno</varname> is set to
1972 <errorname>ENOMEM</errorname>.</para>
1973
1974 <para>The <function>posix_memalign<parameter/></function> function
1975 returns the value 0 if successful; otherwise it returns an error value.
1976 The <function>posix_memalign<parameter/></function> function will fail
1977 if:
1978 <variablelist>
1979 <varlistentry>
1980 <term><errorname>EINVAL</errorname></term>
1981
1982 <listitem><para>The <parameter>alignment</parameter> parameter is
1983 not a power of 2 at least as large as
1984 <code language="C">sizeof(<type>void *</type>)</code>.
1985 </para></listitem>
1986 </varlistentry>
1987 <varlistentry>
1988 <term><errorname>ENOMEM</errorname></term>
1989
1990 <listitem><para>Memory allocation error.</para></listitem>
1991 </varlistentry>
1992 </variablelist>
1993 </para>
1994
1995 <para>The <function>aligned_alloc<parameter/></function> function returns
1996 a pointer to the allocated memory if successful; otherwise a
1997 <constant>NULL</constant> pointer is returned and
1998 <varname>errno</varname> is set. The
1999 <function>aligned_alloc<parameter/></function> function will fail if:
2000 <variablelist>
2001 <varlistentry>
2002 <term><errorname>EINVAL</errorname></term>
2003
2004 <listitem><para>The <parameter>alignment</parameter> parameter is
2005 not a power of 2.
2006 </para></listitem>
2007 </varlistentry>
2008 <varlistentry>
2009 <term><errorname>ENOMEM</errorname></term>
2010
2011 <listitem><para>Memory allocation error.</para></listitem>
2012 </varlistentry>
2013 </variablelist>
2014 </para>
2015
2016 <para>The <function>realloc<parameter/></function> function returns a
2017 pointer, possibly identical to <parameter>ptr</parameter>, to the
2018 allocated memory if successful; otherwise a <constant>NULL</constant>
2019 pointer is returned, and <varname>errno</varname> is set to
2020 <errorname>ENOMEM</errorname> if the error was the result of an
2021 allocation failure. The <function>realloc<parameter/></function>
2022 function always leaves the original buffer intact when an error occurs.
2023 </para>
2024
2025 <para>The <function>free<parameter/></function> function returns no
2026 value.</para>
2027 </refsect2>
2028 <refsect2>
2029 <title>Non-standard API</title>
2030 <para>The <function>malloc_usable_size<parameter/></function> function
2031 returns the usable size of the allocation pointed to by
2032 <parameter>ptr</parameter>. </para>
2033
2034 <para>The <function>mallctl<parameter/></function>,
2035 <function>mallctlnametomib<parameter/></function>, and
2036 <function>mallctlbymib<parameter/></function> functions return 0 on
2037 success; otherwise they return an error value. The functions will fail
2038 if:
2039 <variablelist>
2040 <varlistentry>
2041 <term><errorname>EINVAL</errorname></term>
2042
2043 <listitem><para><parameter>newp</parameter> is not
2044 <constant>NULL</constant>, and <parameter>newlen</parameter> is too
2045 large or too small. Alternatively, <parameter>*oldlenp</parameter>
2046 is too large or too small; in this case as much data as possible
2047 are read despite the error.</para></listitem>
2048 </varlistentry>
2049 <varlistentry>
2050 <term><errorname>ENOMEM</errorname></term>
2051
2052 <listitem><para><parameter>*oldlenp</parameter> is too short to
2053 hold the requested value.</para></listitem>
2054 </varlistentry>
2055 <varlistentry>
2056 <term><errorname>ENOENT</errorname></term>
2057
2058 <listitem><para><parameter>name</parameter> or
2059 <parameter>mib</parameter> specifies an unknown/invalid
2060 value.</para></listitem>
2061 </varlistentry>
2062 <varlistentry>
2063 <term><errorname>EPERM</errorname></term>
2064
2065 <listitem><para>Attempt to read or write void value, or attempt to
2066 write read-only value.</para></listitem>
2067 </varlistentry>
2068 <varlistentry>
2069 <term><errorname>EAGAIN</errorname></term>
2070
2071 <listitem><para>A memory allocation failure
2072 occurred.</para></listitem>
2073 </varlistentry>
2074 <varlistentry>
2075 <term><errorname>EFAULT</errorname></term>
2076
2077 <listitem><para>An interface with side effects failed in some way
2078 not directly related to <function>mallctl*<parameter/></function>
2079 read/write processing.</para></listitem>
2080 </varlistentry>
2081 </variablelist>
2082 </para>
2083 </refsect2>
2084 <refsect2>
2085 <title>Experimental API</title>
2086 <para>The <function>allocm<parameter/></function>,
2087 <function>rallocm<parameter/></function>,
2088 <function>sallocm<parameter/></function>,
2089 <function>dallocm<parameter/></function>, and
2090 <function>nallocm<parameter/></function> functions return
2091 <constant>ALLOCM_SUCCESS</constant> on success; otherwise they return an
2092 error value. The <function>allocm<parameter/></function>,
2093 <function>rallocm<parameter/></function>, and
2094 <function>nallocm<parameter/></function> functions will fail if:
2095 <variablelist>
2096 <varlistentry>
2097 <term><errorname>ALLOCM_ERR_OOM</errorname></term>
2098
2099 <listitem><para>Out of memory. Insufficient contiguous memory was
2100 available to service the allocation request. The
2101 <function>allocm<parameter/></function> function additionally sets
2102 <parameter>*ptr</parameter> to <constant>NULL</constant>, whereas
2103 the <function>rallocm<parameter/></function> function leaves
2104 <constant>*ptr</constant> unmodified.</para></listitem>
2105 </varlistentry>
2106 </variablelist>
2107 The <function>rallocm<parameter/></function> function will also
2108 fail if:
2109 <variablelist>
2110 <varlistentry>
2111 <term><errorname>ALLOCM_ERR_NOT_MOVED</errorname></term>
2112
2113 <listitem><para><constant>ALLOCM_NO_MOVE</constant> was specified,
2114 but the reallocation request could not be serviced without moving
2115 the object.</para></listitem>
2116 </varlistentry>
2117 </variablelist>
2118 </para>
2119 </refsect2>
2120 </refsect1>
2121 <refsect1 id="environment">
2122 <title>ENVIRONMENT</title>
2123 <para>The following environment variable affects the execution of the
2124 allocation functions:
2125 <variablelist>
2126 <varlistentry>
2127 <term><envar>MALLOC_CONF</envar></term>
2128
2129 <listitem><para>If the environment variable
2130 <envar>MALLOC_CONF</envar> is set, the characters it contains
2131 will be interpreted as options.</para></listitem>
2132 </varlistentry>
2133 </variablelist>
2134 </para>
2135 </refsect1>
2136 <refsect1 id="examples">
2137 <title>EXAMPLES</title>
2138 <para>To dump core whenever a problem occurs:
2139 <screen>ln -s 'abort:true' /etc/malloc.conf</screen>
2140 </para>
2141 <para>To specify in the source a chunk size that is 16 MiB:
2142 <programlisting language="C"><![CDATA[
2143 malloc_conf = "lg_chunk:24";]]></programlisting></para>
2144 </refsect1>
2145 <refsect1 id="see_also">
2146 <title>SEE ALSO</title>
2147 <para><citerefentry><refentrytitle>madvise</refentrytitle>
2148 <manvolnum>2</manvolnum></citerefentry>,
2149 <citerefentry><refentrytitle>mmap</refentrytitle>
2150 <manvolnum>2</manvolnum></citerefentry>,
2151 <citerefentry><refentrytitle>sbrk</refentrytitle>
2152 <manvolnum>2</manvolnum></citerefentry>,
2153 <citerefentry><refentrytitle>utrace</refentrytitle>
2154 <manvolnum>2</manvolnum></citerefentry>,
2155 <citerefentry><refentrytitle>alloca</refentrytitle>
2156 <manvolnum>3</manvolnum></citerefentry>,
2157 <citerefentry><refentrytitle>atexit</refentrytitle>
2158 <manvolnum>3</manvolnum></citerefentry>,
2159 <citerefentry><refentrytitle>getpagesize</refentrytitle>
2160 <manvolnum>3</manvolnum></citerefentry></para>
2161 </refsect1>
2162 <refsect1 id="standards">
2163 <title>STANDARDS</title>
2164 <para>The <function>malloc<parameter/></function>,
2165 <function>calloc<parameter/></function>,
2166 <function>realloc<parameter/></function>, and
2167 <function>free<parameter/></function> functions conform to ISO/IEC
2168 9899:1990 (&ldquo;ISO C90&rdquo;).</para>
2169
2170 <para>The <function>posix_memalign<parameter/></function> function conforms
2171 to IEEE Std 1003.1-2001 (&ldquo;POSIX.1&rdquo;).</para>
2172 </refsect1>
2173 </refentry>

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial