-
Notifications
You must be signed in to change notification settings - Fork 4
Expand file tree
/
Copy pathjemalloc.3.html
More file actions
2180 lines (2174 loc) · 189 KB
/
jemalloc.3.html
File metadata and controls
2180 lines (2174 loc) · 189 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8"?>
<html><head><title>JEMALLOC</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"/></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry"><a name="idm46072429623104"/><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>jemalloc — general purpose memory allocation functions</p></div><div class="refsect1"><a name="library"/><h2>LIBRARY</h2><p>This manual describes jemalloc 5.3.1-0-g81034ce1f1373e37dc865038e1bc8eeecf559ce8. More information
can be found at the <a class="ulink" href="http://jemalloc.net/" target="_top">jemalloc website</a>.</p></div><div class="refsynopsisdiv"><h2>SYNOPSIS</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <<code class="filename">jemalloc/jemalloc.h</code>></pre><div class="refsect2"><a name="idm46072424494016"/><h3>Standard API</h3><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">malloc</b>(</code></td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">calloc</b>(</code></td><td>size_t <var class="pdparam">number</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">posix_memalign</b>(</code></td><td>void **<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">alignment</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">aligned_alloc</b>(</code></td><td>size_t <var class="pdparam">alignment</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">realloc</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">free</b>(</code></td><td>void *<var class="pdparam">ptr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">free_sized</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">free_aligned_sized</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">alignment</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><div class="refsect2"><a name="idm46072429653248"/><h3>Non-standard API</h3><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">mallocx</b>(</code></td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">rallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">xallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">extra</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">sallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">dallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">sdallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">nallocx</b>(</code></td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctl</b>(</code></td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">oldp</var>, </td></tr><tr><td> </td><td>size_t *<var class="pdparam">oldlenp</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">newp</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">newlen</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctlnametomib</b>(</code></td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td> </td><td>size_t *<var class="pdparam">mibp</var>, </td></tr><tr><td> </td><td>size_t *<var class="pdparam">miblenp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctlbymib</b>(</code></td><td>const size_t *<var class="pdparam">mib</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">miblen</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">oldp</var>, </td></tr><tr><td> </td><td>size_t *<var class="pdparam">oldlenp</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">newp</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">newlen</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">malloc_stats_print</b>(</code></td><td>void <var class="pdparam">(*write_cb)</var>
<code>(</code>void *, const char *<code>)</code>
, </td></tr><tr><td> </td><td>void *<var class="pdparam">cbopaque</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">opts</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">malloc_usable_size</b>(</code></td><td>const void *<var class="pdparam">ptr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">(*malloc_message)</b>(</code></td><td>void *<var class="pdparam">cbopaque</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">s</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><p><span class="type">const char *</span><code class="varname">malloc_conf</code>;</p></div></div></div><div class="refsect1"><a name="description"/><h2>DESCRIPTION</h2><div class="refsect2"><a name="idm46072424313344"/><h3>Standard API</h3><p>The <code class="function">malloc()</code> function allocates
<em class="parameter"><code>size</code></em> bytes of uninitialized memory. The allocated
space is suitably aligned (after possible pointer coercion) for storage
of any type of object.</p><p>The <code class="function">calloc()</code> function allocates
space for <em class="parameter"><code>number</code></em> objects, each
<em class="parameter"><code>size</code></em> bytes in length. The result is identical to
calling <code class="function">malloc()</code> with an argument of
<em class="parameter"><code>number</code></em> * <em class="parameter"><code>size</code></em>, with the
exception that the allocated memory is explicitly initialized to zero
bytes.</p><p>The <code class="function">posix_memalign()</code> function
allocates <em class="parameter"><code>size</code></em> bytes of memory such that the
allocation's base address is a multiple of
<em class="parameter"><code>alignment</code></em>, and returns the allocation in the value
pointed to by <em class="parameter"><code>ptr</code></em>. The requested
<em class="parameter"><code>alignment</code></em> must be a power of 2 at least as large as
<code class="code">sizeof(<span class="type">void *</span>)</code>.</p><p>The <code class="function">aligned_alloc()</code> function
allocates <em class="parameter"><code>size</code></em> bytes of memory such that the
allocation's base address is a multiple of
<em class="parameter"><code>alignment</code></em>. The requested
<em class="parameter"><code>alignment</code></em> must be a power of 2. Behavior is
undefined if <em class="parameter"><code>size</code></em> is not an integral multiple of
<em class="parameter"><code>alignment</code></em>.</p><p>The <code class="function">realloc()</code> function changes the
size of the previously allocated memory referenced by
<em class="parameter"><code>ptr</code></em> to <em class="parameter"><code>size</code></em> bytes. The
contents of the memory are unchanged up to the lesser of the new and old
sizes. If the new size is larger, the contents of the newly allocated
portion of the memory are undefined. Upon success, the memory referenced
by <em class="parameter"><code>ptr</code></em> is freed and a pointer to the newly
allocated memory is returned. Note that
<code class="function">realloc()</code> may move the memory allocation,
resulting in a different return value than <em class="parameter"><code>ptr</code></em>.
If <em class="parameter"><code>ptr</code></em> is <code class="constant">NULL</code>, the
<code class="function">realloc()</code> function behaves identically to
<code class="function">malloc()</code> for the specified size.</p><p>The <code class="function">free()</code> function causes the
allocated memory referenced by <em class="parameter"><code>ptr</code></em> to be made
available for future allocations. If <em class="parameter"><code>ptr</code></em> is
<code class="constant">NULL</code>, no action occurs.</p><p>The <code class="function">free_sized()</code> function is an extension of
<code class="function">free()</code> with a <em class="parameter"><code>size</code></em> parameter
to allow the caller to pass in the allocation size as an optimization.
</p><p>The <code class="function">free_aligned_sized()</code> function accepts a
<em class="parameter"><code>ptr</code></em> which was allocated with a requested
<em class="parameter"><code>size</code></em> and <em class="parameter"><code>alignment</code></em>, causing
the allocated memory referenced by <em class="parameter"><code>ptr</code></em> to be made
available for future allocations.</p></div><div class="refsect2"><a name="idm46072424282576"/><h3>Non-standard API</h3><p>The <code class="function">mallocx()</code>,
<code class="function">rallocx()</code>,
<code class="function">xallocx()</code>,
<code class="function">sallocx()</code>,
<code class="function">dallocx()</code>,
<code class="function">sdallocx()</code>, and
<code class="function">nallocx()</code> functions all have a
<em class="parameter"><code>flags</code></em> argument that can be used to specify
options. The functions only check the options that are contextually
relevant. Use bitwise or (<code class="code">|</code>) operations to
specify one or more of the following:
</p><div class="variablelist"><dl class="variablelist"><dt><a name="MALLOCX_LG_ALIGN"/><span class="term"><code class="constant">MALLOCX_LG_ALIGN(<em class="parameter"><code>la</code></em>)
</code></span></dt><dd><p>Align the memory allocation to start at an address
that is a multiple of <code class="code">(1 <<
<em class="parameter"><code>la</code></em>)</code>. This macro does not validate
that <em class="parameter"><code>la</code></em> is within the valid
range.</p></dd><dt><a name="MALLOCX_ALIGN"/><span class="term"><code class="constant">MALLOCX_ALIGN(<em class="parameter"><code>a</code></em>)
</code></span></dt><dd><p>Align the memory allocation to start at an address
that is a multiple of <em class="parameter"><code>a</code></em>, where
<em class="parameter"><code>a</code></em> is a power of two. This macro does not
validate that <em class="parameter"><code>a</code></em> is a power of 2.
</p></dd><dt><a name="MALLOCX_ZERO"/><span class="term"><code class="constant">MALLOCX_ZERO</code></span></dt><dd><p>Initialize newly allocated memory to contain zero
bytes. In the growing reallocation case, the real size prior to
reallocation defines the boundary between untouched bytes and those
that are initialized to contain zero bytes. If this macro is
absent, newly allocated memory is uninitialized.</p></dd><dt><a name="MALLOCX_TCACHE"/><span class="term"><code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)
</code></span></dt><dd><p>Use the thread-specific cache (tcache) specified by
the identifier <em class="parameter"><code>tc</code></em>, which must have been
acquired via the <a class="link" href="#tcache.create"><quote><code class="mallctl">tcache.create</code></quote></a>
mallctl. This macro does not validate that
<em class="parameter"><code>tc</code></em> specifies a valid
identifier.</p></dd><dt><a name="MALLOC_TCACHE_NONE"/><span class="term"><code class="constant">MALLOCX_TCACHE_NONE</code></span></dt><dd><p>Do not use a thread-specific cache (tcache). Unless
<code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)</code> or
<code class="constant">MALLOCX_TCACHE_NONE</code> is specified, an
automatically managed tcache will be used under many circumstances.
This macro cannot be used in the same <em class="parameter"><code>flags</code></em>
argument as
<code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)</code>.</p></dd><dt><a name="MALLOCX_ARENA"/><span class="term"><code class="constant">MALLOCX_ARENA(<em class="parameter"><code>a</code></em>)
</code></span></dt><dd><p>Use the arena specified by the index
<em class="parameter"><code>a</code></em>. This macro has no effect for regions that
were allocated via an arena other than the one specified. This
macro does not validate that <em class="parameter"><code>a</code></em> specifies an
arena index in the valid range.</p></dd></dl></div><p>
</p><p>The <code class="function">mallocx()</code> function allocates at
least <em class="parameter"><code>size</code></em> bytes of memory, and returns a pointer
to the base address of the allocation. Behavior is undefined if
<em class="parameter"><code>size</code></em> is <code class="constant">0</code>.</p><p>The <code class="function">rallocx()</code> function resizes the
allocation at <em class="parameter"><code>ptr</code></em> to be at least
<em class="parameter"><code>size</code></em> bytes, and returns a pointer to the base
address of the resulting allocation, which may or may not have moved from
its original location. Behavior is undefined if
<em class="parameter"><code>size</code></em> is <code class="constant">0</code>.</p><p>The <code class="function">xallocx()</code> function resizes the
allocation at <em class="parameter"><code>ptr</code></em> in place to be at least
<em class="parameter"><code>size</code></em> bytes, and returns the real size of the
allocation. If <em class="parameter"><code>extra</code></em> is non-zero, an attempt is
made to resize the allocation to be at least <code class="code">(<em class="parameter"><code>size</code></em> +
<em class="parameter"><code>extra</code></em>)</code> bytes, though inability to allocate
the extra byte(s) will not by itself result in failure to resize.
Behavior is undefined if <em class="parameter"><code>size</code></em> is
<code class="constant">0</code>, or if <code class="code">(<em class="parameter"><code>size</code></em> + <em class="parameter"><code>extra</code></em>
> <code class="constant">SIZE_T_MAX</code>)</code>.</p><p>The <code class="function">sallocx()</code> function returns the
real size of the allocation at <em class="parameter"><code>ptr</code></em>.</p><p>The <code class="function">dallocx()</code> function causes the
memory referenced by <em class="parameter"><code>ptr</code></em> to be made available for
future allocations.</p><p>The <code class="function">sdallocx()</code> function is an
extension of <code class="function">dallocx()</code> with a
<em class="parameter"><code>size</code></em> parameter to allow the caller to pass in the
allocation size as an optimization. The minimum valid input size is the
original requested size of the allocation, and the maximum valid input
size is the corresponding value returned by
<code class="function">nallocx()</code> or
<code class="function">sallocx()</code>.</p><p>The <code class="function">nallocx()</code> function allocates no
memory, but it performs the same size computation as the
<code class="function">mallocx()</code> function, and returns the real
size of the allocation that would result from the equivalent
<code class="function">mallocx()</code> function call, or
<code class="constant">0</code> if the inputs exceed the maximum supported size
class and/or alignment. Behavior is undefined if
<em class="parameter"><code>size</code></em> is <code class="constant">0</code>.</p><p>The <code class="function">mallctl()</code> function provides a
general interface for introspecting the memory allocator, as well as
setting modifiable parameters and triggering actions. The
period-separated <em class="parameter"><code>name</code></em> argument specifies a
location in a tree-structured namespace; see the <a class="xref" href="#mallctl_namespace" title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for
documentation on the tree contents. To read a value, pass a pointer via
<em class="parameter"><code>oldp</code></em> to adequate space to contain the value, and a
pointer to its length via <em class="parameter"><code>oldlenp</code></em>; otherwise pass
<code class="constant">NULL</code> and <code class="constant">NULL</code>. Similarly, to
write a value, pass a pointer to the value via
<em class="parameter"><code>newp</code></em>, and its length via
<em class="parameter"><code>newlen</code></em>; otherwise pass <code class="constant">NULL</code>
and <code class="constant">0</code>.</p><p>The <code class="function">mallctlnametomib()</code> function
provides a way to avoid repeated name lookups for applications that
repeatedly query the same portion of the namespace, by translating a name
to a <span class="quote">“<span class="quote">Management Information Base</span>”</span> (MIB) that can be passed
repeatedly to <code class="function">mallctlbymib()</code>. Upon
successful return from <code class="function">mallctlnametomib()</code>,
<em class="parameter"><code>mibp</code></em> contains an array of
<em class="parameter"><code>*miblenp</code></em> integers, where
<em class="parameter"><code>*miblenp</code></em> is the lesser of the number of components
in <em class="parameter"><code>name</code></em> and the input value of
<em class="parameter"><code>*miblenp</code></em>. Thus it is possible to pass a
<em class="parameter"><code>*miblenp</code></em> that is smaller than the number of
period-separated name components, which results in a partial MIB that can
be used as the basis for constructing a complete MIB. For name
components that are integers (e.g. the 2 in
<a class="link" href="#arenas.bin.i.size"><quote><code class="mallctl">arenas.bin.2.size</code></quote></a>),
the corresponding MIB component will always be that integer. Therefore,
it is legitimate to construct code like the following: </p><pre class="programlisting">
unsigned nbins, i;
size_t mib[4];
size_t len, miblen;
len = sizeof(nbins);
mallctl("arenas.nbins", &nbins, &len, NULL, 0);
miblen = 4;
mallctlnametomib("arenas.bin.0.size", mib, &miblen);
for (i = 0; i < nbins; i++) {
size_t bin_size;
mib[2] = i;
len = sizeof(bin_size);
mallctlbymib(mib, miblen, (void *)&bin_size, &len, NULL, 0);
/* Do something with bin_size... */
}</pre><dt><a name="malloc_stats_print_opts"/></dt><dd/><p>The <code class="function">malloc_stats_print()</code> function writes
summary statistics via the <em class="parameter"><code>write_cb</code></em> callback
function pointer and <em class="parameter"><code>cbopaque</code></em> data passed to
<em class="parameter"><code>write_cb</code></em>, or <code class="function">malloc_message()</code>
if <em class="parameter"><code>write_cb</code></em> is <code class="constant">NULL</code>. The
statistics are presented in human-readable form unless <span class="quote">“<span class="quote">J</span>”</span> is
specified as a character within the <em class="parameter"><code>opts</code></em> string, in
which case the statistics are presented in <a class="ulink" href="http://www.json.org/" target="_top">JSON format</a>. This function can be
called repeatedly. General information that never changes during
execution can be omitted by specifying <span class="quote">“<span class="quote">g</span>”</span> as a character
within the <em class="parameter"><code>opts</code></em> string. Note that
<code class="function">malloc_stats_print()</code> uses the
<code class="function">mallctl*()</code> functions internally, so inconsistent
statistics can be reported if multiple threads use these functions
simultaneously. If <code class="option">--enable-stats</code> is specified during
configuration, <span class="quote">“<span class="quote">m</span>”</span>, <span class="quote">“<span class="quote">d</span>”</span>, and <span class="quote">“<span class="quote">a</span>”</span>
can be specified to omit merged arena, destroyed merged arena, and per
arena statistics, respectively; <span class="quote">“<span class="quote">b</span>”</span> and <span class="quote">“<span class="quote">l</span>”</span> can
be specified to omit per size class statistics for bins and large objects,
respectively; <span class="quote">“<span class="quote">x</span>”</span> can be specified to omit all mutex
statistics; <span class="quote">“<span class="quote">e</span>”</span> can be used to omit extent statistics.
Unrecognized characters are silently ignored. Note that thread caching
may prevent some statistics from being completely up to date, since extra
locking would be required to merge counters that track thread cache
operations.</p><p>The <code class="function">malloc_usable_size()</code> function
returns the usable size of the allocation pointed to by
<em class="parameter"><code>ptr</code></em>. The return value may be larger than the size
that was requested during allocation. The
<code class="function">malloc_usable_size()</code> function is not a
mechanism for in-place <code class="function">realloc()</code>; rather
it is provided solely as a tool for introspection purposes. Any
discrepancy between the requested allocation size and the size reported
by <code class="function">malloc_usable_size()</code> should not be
depended on, since such behavior is entirely implementation-dependent.
</p></div><div class="refsect2"><a name="idm46072424181712"/><h3>Interactions Between the Standard and Non-standard APIs</h3><p>Generally speaking it is permissible to pass pointers obtained from
the standard API to the non-standard API and vice versa (e.g. calling
<code class="function">free()</code> with a pointer returned by a call to
<code class="function">mallocx()</code>, calling <code class="function">sdallocx()</code>
with a pointer returned by a call to <code class="function">calloc()</code>).
There are however a few exceptions. In keeping with the C23 standard –
which forbids calling <code class="function">free_sized()</code> on a pointer
returned by <code class="function">aligned_alloc()</code>, mandating that either
<code class="function">free_aligned_sized()</code> or <code class="function">free()</code>
be used instead – using any combination of the standard and non-standard
APIs in an equivalent fashion (i.e. taking a pointer which was allocated
with an explicitly requested alignment and attempting to free it via an
API that accepts a size hint, without also providing the alignment hint)
is likewise forbidden.
</p></div></div><div class="refsect1"><a name="tuning"/><h2>TUNING</h2><p>Once, when the first call is made to one of the memory allocation
routines, the allocator initializes its internals based in part on various
options that can be specified at compile- or run-time.</p><p>The string specified via <code class="option">--with-malloc-conf</code>, the
string pointed to by the global variable <code class="varname">malloc_conf</code>, the
<span class="quote">“<span class="quote">name</span>”</span> of the file referenced by the symbolic link named
<code class="filename">/etc/malloc.conf</code>, and the value of the
environment variable <code class="envar">MALLOC_CONF</code>, will be interpreted, in
that order, from left to right as options. Note that
<code class="varname">malloc_conf</code> may be read before
<code class="function">main()</code> is entered, so the declaration of
<code class="varname">malloc_conf</code> should specify an initializer that contains
the final value to be read by jemalloc. <code class="option">--with-malloc-conf</code>
and <code class="varname">malloc_conf</code> are compile-time mechanisms, whereas
<code class="filename">/etc/malloc.conf</code> and
<code class="envar">MALLOC_CONF</code> can be safely set any time prior to program
invocation.</p><p>An options string is a comma-separated list of option:value pairs.
There is one key corresponding to each <a class="link" href="#opt.abort"><quote><code class="mallctl">opt.*</code></quote></a> mallctl (see the <a class="xref" href="#mallctl_namespace" title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for options
documentation). For example, <code class="literal">abort:true,narenas:1</code> sets
the <a class="link" href="#opt.abort"><quote><code class="mallctl">opt.abort</code></quote></a> and <a class="link" href="#opt.narenas"><quote><code class="mallctl">opt.narenas</code></quote></a> options. Some
options have boolean values (true/false), others have integer values (base
8, 10, or 16, depending on prefix), and yet others have raw string
values.</p></div><div class="refsect1"><a name="implementation_notes"/><h2>IMPLEMENTATION NOTES</h2><p>Traditionally, allocators have used
<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> to obtain memory, which is
suboptimal for several reasons, including race conditions, increased
fragmentation, and artificial limitations on maximum usable memory. If
<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating
system, this allocator uses both
<span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> and
<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>, in that order of preference;
otherwise only <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> is used.</p><p>This allocator uses multiple arenas in order to reduce lock
contention for threaded programs on multi-processor systems. This works
well with regard to threading scalability, but incurs some costs. There is
a small fixed per-arena overhead, and additionally, arenas manage memory
completely independently of each other, which means a small fixed increase
in overall memory fragmentation. These overheads are not generally an
issue, given the number of arenas normally used. Note that using
substantially more arenas than the default is not likely to improve
performance, mainly due to reduced cache performance. However, it may make
sense to reduce the number of arenas if an application does not make much
use of the allocation functions.</p><p>In addition to multiple arenas, this allocator supports
thread-specific caching, in order to make it possible to completely avoid
synchronization for most allocation requests. Such caching allows very fast
allocation in the common case, but it increases memory usage and
fragmentation, since a bounded number of objects can remain allocated in
each thread cache.</p><p>Memory is conceptually broken into extents. Extents are always
aligned to multiples of the page size. This alignment makes it possible to
find metadata for user objects quickly. User objects are broken into two
categories according to size: small and large. Contiguous small objects
comprise a slab, which resides within a single extent, whereas large objects
each have their own extents backing them.</p><p>Small objects are managed in groups by slabs. Each slab maintains
a bitmap to track which regions are in use. Allocation requests that are no
more than half the quantum (8 or 16, depending on architecture) are rounded
up to the nearest power of two that is at least <code class="code">sizeof(<span class="type">double</span>)</code>. All other object size
classes are multiples of the quantum, spaced such that there are four size
classes for each doubling in size, which limits internal fragmentation to
approximately 20% for all but the smallest size classes. Small size classes
are smaller than four times the page size, and large size classes extend
from four times the page size up to the largest size class that does not
exceed <code class="constant">PTRDIFF_MAX</code>.</p><p>Allocations are packed tightly together, which can be an issue for
multi-threaded applications. If you need to assure that allocations do not
suffer from cacheline sharing, round your allocation requests up to the
nearest multiple of the cacheline size, or specify cacheline alignment when
allocating.</p><p>The <code class="function">realloc()</code>,
<code class="function">rallocx()</code>, and
<code class="function">xallocx()</code> functions may resize allocations
without moving them under limited circumstances. Unlike the
<code class="function">*allocx()</code> API, the standard API does not
officially round up the usable size of an allocation to the nearest size
class, so technically it is necessary to call
<code class="function">realloc()</code> to grow e.g. a 9-byte allocation to
16 bytes, or shrink a 16-byte allocation to 9 bytes. Growth and shrinkage
trivially succeeds in place as long as the pre-size and post-size both round
up to the same size class. No other API guarantees are made regarding
in-place resizing, but the current implementation also tries to resize large
allocations in place, as long as the pre-size and post-size are both large.
For shrinkage to succeed, the extent allocator must support splitting (see
<a class="link" href="#arena.i.extent_hooks"><quote><code class="mallctl">arena.<i>.extent_hooks</code></quote></a>).
Growth only succeeds if the trailing memory is currently available, and the
extent allocator supports merging.</p><p>Assuming 4 KiB pages and a 16-byte quantum on a 64-bit system, the
size classes in each category are as shown in <a class="xref" href="#size_classes" title="Table 1. Size classes">Table 1</a>.</p><div class="table"><a name="size_classes"/><p class="title"><b>Table 1. Size classes</b></p><div class="table-contents"><table class="table" summary="Size classes" border="1"><colgroup><col align="left" class="c1"/><col align="right" class="c2"/><col align="left" class="c3"/></colgroup><thead><tr><th align="left">Category</th><th align="right">Spacing</th><th align="left">Size</th></tr></thead><tbody><tr><td rowspan="9" align="left">Small</td><td align="right">lg</td><td align="left">[8]</td></tr><tr><td align="right">16</td><td align="left">[16, 32, 48, 64, 80, 96, 112, 128]</td></tr><tr><td align="right">32</td><td align="left">[160, 192, 224, 256]</td></tr><tr><td align="right">64</td><td align="left">[320, 384, 448, 512]</td></tr><tr><td align="right">128</td><td align="left">[640, 768, 896, 1024]</td></tr><tr><td align="right">256</td><td align="left">[1280, 1536, 1792, 2048]</td></tr><tr><td align="right">512</td><td align="left">[2560, 3072, 3584, 4096]</td></tr><tr><td align="right">1 KiB</td><td align="left">[5 KiB, 6 KiB, 7 KiB, 8 KiB]</td></tr><tr><td align="right">2 KiB</td><td align="left">[10 KiB, 12 KiB, 14 KiB]</td></tr><tr><td rowspan="16" align="left">Large</td><td align="right">2 KiB</td><td align="left">[16 KiB]</td></tr><tr><td align="right">4 KiB</td><td align="left">[20 KiB, 24 KiB, 28 KiB, 32 KiB]</td></tr><tr><td align="right">8 KiB</td><td align="left">[40 KiB, 48 KiB, 56 KiB, 64 KiB]</td></tr><tr><td align="right">16 KiB</td><td align="left">[80 KiB, 96 KiB, 112 KiB, 128 KiB]</td></tr><tr><td align="right">32 KiB</td><td align="left">[160 KiB, 192 KiB, 224 KiB, 256 KiB]</td></tr><tr><td align="right">64 KiB</td><td align="left">[320 KiB, 384 KiB, 448 KiB, 512 KiB]</td></tr><tr><td align="right">128 KiB</td><td align="left">[640 KiB, 768 KiB, 896 KiB, 1 MiB]</td></tr><tr><td align="right">256 KiB</td><td align="left">[1280 KiB, 1536 KiB, 1792 KiB, 2 MiB]</td></tr><tr><td align="right">512 KiB</td><td align="left">[2560 KiB, 3 MiB, 3584 KiB, 4 MiB]</td></tr><tr><td align="right">1 MiB</td><td align="left">[5 MiB, 6 MiB, 7 MiB, 8 MiB]</td></tr><tr><td align="right">2 MiB</td><td align="left">[10 MiB, 12 MiB, 14 MiB, 16 MiB]</td></tr><tr><td align="right">4 MiB</td><td align="left">[20 MiB, 24 MiB, 28 MiB, 32 MiB]</td></tr><tr><td align="right">8 MiB</td><td align="left">[40 MiB, 48 MiB, 56 MiB, 64 MiB]</td></tr><tr><td align="right">...</td><td align="left">...</td></tr><tr><td align="right">512 PiB</td><td align="left">[2560 PiB, 3 EiB, 3584 PiB, 4 EiB]</td></tr><tr><td align="right">1 EiB</td><td align="left">[5 EiB, 6 EiB, 7 EiB]</td></tr></tbody></table></div></div><br class="table-break"/></div><div class="refsect1"><a name="mallctl_namespace"/><h2>MALLCTL NAMESPACE</h2><p>The following names are defined in the namespace accessible via the
<code class="function">mallctl*()</code> functions. Value types are specified in
parentheses, their readable/writable statuses are encoded as
<code class="literal">rw</code>, <code class="literal">r-</code>, <code class="literal">-w</code>, or
<code class="literal">--</code>, and required build configuration flags follow, if
any. A name element encoded as <code class="literal"><i></code> or
<code class="literal"><j></code> indicates an integer component, where the
integer varies from 0 to some upper value that must be determined via
introspection. In the case of <quote><code class="mallctl">stats.arenas.<i>.*</code></quote>
and <quote><code class="mallctl">arena.<i>.{initialized,purge,decay,dss}</code></quote>,
<code class="literal"><i></code> equal to
<code class="constant">MALLCTL_ARENAS_ALL</code> can be used to operate on all arenas
or access the summation of statistics from all arenas; similarly
<code class="literal"><i></code> equal to
<code class="constant">MALLCTL_ARENAS_DESTROYED</code> can be used to access the
summation of statistics from all destroyed arenas. These constants can be
utilized either via <code class="function">mallctlnametomib()</code> followed by
<code class="function">mallctlbymib()</code>, or via code such as the following:
</p><pre class="programlisting">
#define STRINGIFY_HELPER(x) #x
#define STRINGIFY(x) STRINGIFY_HELPER(x)
mallctl("arena." STRINGIFY(MALLCTL_ARENAS_ALL) ".decay",
NULL, NULL, NULL, 0);</pre><p>
Take special note of the <a class="link" href="#epoch"><quote><code class="mallctl">epoch</code></quote></a> mallctl, which controls
refreshing of cached dynamic statistics.</p><div class="variablelist"><dl class="variablelist"><dt><a name="version"/><span class="term">
<quote><code class="mallctl">version</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Return the jemalloc version string.</p></dd><dt><a name="epoch"/><span class="term">
<quote><code class="mallctl">epoch</code></quote>
(<span class="type">uint64_t</span>)
<code class="literal">rw</code>
</span></dt><dd><p>If a value is passed in, refresh the data from which
the <code class="function">mallctl*()</code> functions report values,
and increment the epoch. Return the current epoch. This is useful for
detecting whether another thread caused a refresh.</p></dd><dt><a name="background_thread"/><span class="term">
<quote><code class="mallctl">background_thread</code></quote>
(<span class="type">bool</span>)
<code class="literal">rw</code>
</span></dt><dd><p>Enable/disable internal background worker threads. When
set to true, background threads are created on demand (the number of
background threads will be no more than the number of CPUs or active
arenas). Threads run periodically, and handle <a class="link" href="#arena.i.decay">purging</a> asynchronously. When switching
off, background threads are terminated synchronously. Note that after
<span class="citerefentry"><span class="refentrytitle">fork</span>(2)</span>
function, the state in the child process will be disabled regardless
the state in parent process. See <a class="link" href="#stats.background_thread.num_threads"><quote><code class="mallctl">stats.background_thread</code></quote></a>
for related stats. <a class="link" href="#opt.background_thread"><quote><code class="mallctl">opt.background_thread</code></quote></a>
can be used to set the default option. This option is only available on
selected pthread-based platforms.</p></dd><dt><a name="max_background_threads"/><span class="term">
<quote><code class="mallctl">max_background_threads</code></quote>
(<span class="type">size_t</span>)
<code class="literal">rw</code>
</span></dt><dd><p>Maximum number of background worker threads that will
be created. This value is capped at <a class="link" href="#opt.max_background_threads"><quote><code class="mallctl">opt.max_background_threads</code></quote></a> at
startup.</p></dd><dt><a name="config.cache_oblivious"/><span class="term">
<quote><code class="mallctl">config.cache_oblivious</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-cache-oblivious</code> was specified
during build configuration.</p></dd><dt><a name="config.debug"/><span class="term">
<quote><code class="mallctl">config.debug</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-debug</code> was specified during
build configuration.</p></dd><dt><a name="config.fill"/><span class="term">
<quote><code class="mallctl">config.fill</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-fill</code> was specified during
build configuration.</p></dd><dt><a name="config.lazy_lock"/><span class="term">
<quote><code class="mallctl">config.lazy_lock</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-lazy-lock</code> was specified
during build configuration.</p></dd><dt><a name="config.malloc_conf"/><span class="term">
<quote><code class="mallctl">config.malloc_conf</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Embedded configure-time-specified run-time options
string, empty unless <code class="option">--with-malloc-conf</code> was specified
during build configuration.</p></dd><dt><a name="config.prof"/><span class="term">
<quote><code class="mallctl">config.prof</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-prof</code> was specified during
build configuration.</p></dd><dt><a name="config.prof_libgcc"/><span class="term">
<quote><code class="mallctl">config.prof_libgcc</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--disable-prof-libgcc</code> was not
specified during build configuration.</p></dd><dt><a name="config.prof_libunwind"/><span class="term">
<quote><code class="mallctl">config.prof_libunwind</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-prof-libunwind</code> was specified
during build configuration.</p></dd><dt><a name="config.stats"/><span class="term">
<quote><code class="mallctl">config.stats</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-stats</code> was specified during
build configuration.</p></dd><dt><a name="config.utrace"/><span class="term">
<quote><code class="mallctl">config.utrace</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-utrace</code> was specified during
build configuration.</p></dd><dt><a name="config.xmalloc"/><span class="term">
<quote><code class="mallctl">config.xmalloc</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p><code class="option">--enable-xmalloc</code> was specified during
build configuration.</p></dd><dt><a name="opt.abort"/><span class="term">
<quote><code class="mallctl">opt.abort</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Abort-on-warning enabled/disabled. If true, most
warnings are fatal. Note that runtime option warnings are not included
(see <a class="link" href="#opt.abort_conf"><quote><code class="mallctl">opt.abort_conf</code></quote></a> for
that). The process will call
<span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span> in these cases. This option is
disabled by default unless <code class="option">--enable-debug</code> is
specified during configuration, in which case it is enabled by default.
</p></dd><dt><a name="opt.confirm_conf"/><span class="term">
<quote><code class="mallctl">opt.confirm_conf</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Confirm-runtime-options-when-program-starts
enabled/disabled. If true, the string specified via
<code class="option">--with-malloc-conf</code>, the string pointed to by the
global variable <code class="varname">malloc_conf</code>, the <span class="quote">“<span class="quote">name</span>”</span>
of the file referenced by the symbolic link named
<code class="filename">/etc/malloc.conf</code>, and the value of
the environment variable <code class="envar">MALLOC_CONF</code>, will be printed in
order. Then, each option being set will be individually printed. This
option is disabled by default.</p></dd><dt><a name="opt.abort_conf"/><span class="term">
<quote><code class="mallctl">opt.abort_conf</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Abort-on-invalid-configuration enabled/disabled. If
true, invalid runtime options are fatal. The process will call
<span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span> in these cases. This option is
disabled by default unless <code class="option">--enable-debug</code> is
specified during configuration, in which case it is enabled by default.
</p></dd><dt><a name="opt.cache_oblivious"/><span class="term">
<quote><code class="mallctl">opt.cache_oblivious</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Enable / Disable cache-oblivious large allocation
alignment, for large requests with no alignment constraints. If this
feature is disabled, all large allocations are page-aligned as an
implementation artifact, which can severely harm CPU cache utilization.
However, the cache-oblivious layout comes at the cost of one extra page
per large allocation, which in the most extreme case increases physical
memory usage for the 16 KiB size class to 20 KiB. This option is enabled
by default.</p></dd><dt><a name="opt.metadata_thp"/><span class="term">
<quote><code class="mallctl">opt.metadata_thp</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Controls whether to allow jemalloc to use transparent
huge page (THP) for internal metadata (see <a class="link" href="#stats.metadata">stats.metadata</a>). <span class="quote">“<span class="quote">always</span>”</span>
allows such usage. <span class="quote">“<span class="quote">auto</span>”</span> uses no THP initially, but may
begin to do so when metadata usage reaches certain level. The default
is <span class="quote">“<span class="quote">disabled</span>”</span>.</p></dd><dt><a name="opt.trust_madvise"/><span class="term">
<quote><code class="mallctl">opt.trust_madvise</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>If true, do not perform runtime check for MADV_DONTNEED,
to check that it actually zeros pages. The default is disabled on Linux
and enabled elsewhere.</p></dd><dt><a name="opt.retain"/><span class="term">
<quote><code class="mallctl">opt.retain</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>If true, retain unused virtual memory for later reuse
rather than discarding it by calling
<span class="citerefentry"><span class="refentrytitle">munmap</span>(2)</span> or equivalent (see <a class="link" href="#stats.retained">stats.retained</a> for related details).
It also makes jemalloc use <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> or equivalent in a more greedy way, mapping larger
chunks in one go. This option is disabled by default unless discarding
virtual memory is known to trigger platform-specific performance
problems, namely 1) for [64-bit] Linux, which has a quirk in its virtual
memory allocation algorithm that causes semi-permanent VM map holes
under normal jemalloc operation; and 2) for [64-bit] Windows, which
disallows split / merged regions with
<em class="parameter"><code><code class="constant">MEM_RELEASE</code></code></em>. Although the
same issues may present on 32-bit platforms as well, retaining virtual
memory for 32-bit Linux and Windows is disabled by default due to the
practical possibility of address space exhaustion. </p></dd><dt><a name="opt.dss"/><span class="term">
<quote><code class="mallctl">opt.dss</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p>dss (<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>) allocation precedence as
related to <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> allocation. The following
settings are supported if
<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating
system: <span class="quote">“<span class="quote">disabled</span>”</span>, <span class="quote">“<span class="quote">primary</span>”</span>, and
<span class="quote">“<span class="quote">secondary</span>”</span>; otherwise only <span class="quote">“<span class="quote">disabled</span>”</span> is
supported. The default is <span class="quote">“<span class="quote">secondary</span>”</span> if
<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating
system; <span class="quote">“<span class="quote">disabled</span>”</span> otherwise.
</p></dd><dt><a name="opt.narenas"/><span class="term">
<quote><code class="mallctl">opt.narenas</code></quote>
(<span class="type">unsigned</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Maximum number of arenas to use for automatic
multiplexing of threads and arenas. The default is four times the
number of CPUs, or one if there is a single CPU.</p></dd><dt><a name="opt.oversize_threshold"/><span class="term">
<quote><code class="mallctl">opt.oversize_threshold</code></quote>
(<span class="type">size_t</span>)
<code class="literal">r-</code>
</span></dt><dd><p>The threshold in bytes of which requests are considered
oversize. Allocation requests with greater sizes are fulfilled from a
dedicated arena (automatically managed, however not within
<code class="literal">narenas</code>), in order to reduce fragmentation by not
mixing huge allocations with small ones. In addition, the decay API
guarantees on the extents greater than the specified threshold may be
overridden. Note that requests with arena index specified via
<code class="constant">MALLOCX_ARENA</code>, or threads associated with explicit
arenas will not be considered. The default threshold is 8MiB. Values
not within large size classes disables this feature.</p></dd><dt><a name="opt.percpu_arena"/><span class="term">
<quote><code class="mallctl">opt.percpu_arena</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Per CPU arena mode. Use the <span class="quote">“<span class="quote">percpu</span>”</span>
setting to enable this feature, which uses number of CPUs to determine
number of arenas, and bind threads to arenas dynamically based on the
CPU the thread runs on currently. <span class="quote">“<span class="quote">phycpu</span>”</span> setting uses
one arena per physical CPU, which means the two hyper threads on the
same CPU share one arena. Note that no runtime checking regarding the
availability of hyper threading is done at the moment. When set to
<span class="quote">“<span class="quote">disabled</span>”</span>, narenas and thread to arena association will
not be impacted by this option. The default is <span class="quote">“<span class="quote">disabled</span>”</span>.
</p></dd><dt><a name="opt.background_thread"/><span class="term">
<quote><code class="mallctl">opt.background_thread</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Internal background worker threads enabled/disabled.
Because of potential circular dependencies, enabling background thread
using this option may cause crash or deadlock during initialization. For
a reliable way to use this feature, see <a class="link" href="#background_thread">background_thread</a> for dynamic control
options and details. This option is disabled by
default.</p></dd><dt><a name="opt.max_background_threads"/><span class="term">
<quote><code class="mallctl">opt.max_background_threads</code></quote>
(<span class="type">size_t</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Maximum number of background threads that will be created
if <a class="link" href="#background_thread">background_thread</a> is set.
Defaults to 4.</p></dd><dt><a name="opt.dirty_decay_ms"/><span class="term">
<quote><code class="mallctl">opt.dirty_decay_ms</code></quote>
(<span class="type">ssize_t</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Approximate time in milliseconds from the creation of a
set of unused dirty pages until an equivalent set of unused dirty pages
is purged (i.e. converted to muzzy via e.g.
<code class="function">madvise(<em class="parameter"><code>...</code></em><em class="parameter"><code><code class="constant">MADV_FREE</code></code></em>)</code>
if supported by the operating system, or converted to clean otherwise)
and/or reused. Dirty pages are defined as previously having been
potentially written to by the application, and therefore consuming
physical memory, yet having no current use. The pages are incrementally
purged according to a sigmoidal decay curve that starts and ends with
zero purge rate. A decay time of 0 causes all unused dirty pages to be
purged immediately upon creation. A decay time of -1 disables purging.
The default decay time is 10 seconds. See <a class="link" href="#arenas.dirty_decay_ms"><quote><code class="mallctl">arenas.dirty_decay_ms</code></quote></a>
and <a class="link" href="#arena.i.dirty_decay_ms"><quote><code class="mallctl">arena.<i>.dirty_decay_ms</code></quote></a>
for related dynamic control options. See <a class="link" href="#opt.muzzy_decay_ms"><quote><code class="mallctl">opt.muzzy_decay_ms</code></quote></a>
for a description of muzzy pages. Note that when the <a class="link" href="#opt.oversize_threshold"><quote><code class="mallctl">oversize_threshold</code></quote></a>
feature is enabled, the arenas reserved for oversize requests may have
its own default decay settings.</p></dd><dt><a name="opt.muzzy_decay_ms"/><span class="term">
<quote><code class="mallctl">opt.muzzy_decay_ms</code></quote>
(<span class="type">ssize_t</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Approximate time in milliseconds from the creation of a
set of unused muzzy pages until an equivalent set of unused muzzy pages
is purged (i.e. converted to clean) and/or reused. Muzzy pages are
defined as previously having been unused dirty pages that were
subsequently purged in a manner that left them subject to the
reclamation whims of the operating system (e.g.
<code class="function">madvise(<em class="parameter"><code>...</code></em><em class="parameter"><code><code class="constant">MADV_FREE</code></code></em>)</code>),
and therefore in an indeterminate state. The pages are incrementally
purged according to a sigmoidal decay curve that starts and ends with
zero purge rate. A decay time of 0 causes all unused muzzy pages to be
purged immediately upon creation. A decay time of -1 disables purging.
Muzzy decay is disabled by default (with decay time 0). See <a class="link" href="#arenas.muzzy_decay_ms"><quote><code class="mallctl">arenas.muzzy_decay_ms</code></quote></a>
and <a class="link" href="#arena.i.muzzy_decay_ms"><quote><code class="mallctl">arena.<i>.muzzy_decay_ms</code></quote></a>
for related dynamic control options.</p></dd><dt><a name="opt.lg_extent_max_active_fit"/><span class="term">
<quote><code class="mallctl">opt.lg_extent_max_active_fit</code></quote>
(<span class="type">size_t</span>)
<code class="literal">r-</code>
</span></dt><dd><p>When reusing dirty extents, this determines the (log
base 2 of the) maximum ratio between the size of the active extent
selected (to split off from) and the size of the requested allocation.
This prevents the splitting of large active extents for smaller
allocations, which can reduce fragmentation over the long run
(especially for non-active extents). Lower value may reduce
fragmentation, at the cost of extra active extents. The default value
is 6, which gives a maximum ratio of 64 (2^6).</p></dd><dt><a name="opt.stats_print"/><span class="term">
<quote><code class="mallctl">opt.stats_print</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Enable/disable statistics printing at exit. If
enabled, the <code class="function">malloc_stats_print()</code>
function is called at program exit via an
<span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function. <a class="link" href="#opt.stats_print_opts"><quote><code class="mallctl">opt.stats_print_opts</code></quote></a>
can be combined to specify output options. If
<code class="option">--enable-stats</code> is specified during configuration, this
has the potential to cause deadlock for a multi-threaded process that
exits while one or more threads are executing in the memory allocation
functions. Furthermore, <code class="function">atexit()</code> may
allocate memory during application initialization and then deadlock
internally when jemalloc in turn calls
<code class="function">atexit()</code>, so this option is not
universally usable (though the application can register its own
<code class="function">atexit()</code> function with equivalent
functionality). Therefore, this option should only be used with care;
it is primarily intended as a performance tuning aid during application
development. This option is disabled by default.</p></dd><dt><a name="opt.stats_print_opts"/><span class="term">
<quote><code class="mallctl">opt.stats_print_opts</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Options (the <em class="parameter"><code>opts</code></em> string) to pass
to the <code class="function">malloc_stats_print()</code> at exit (enabled
through <a class="link" href="#opt.stats_print"><quote><code class="mallctl">opt.stats_print</code></quote></a>). See
available options in <a class="link" href="#malloc_stats_print_opts"><code class="function">malloc_stats_print()</code></a>.
Has no effect unless <a class="link" href="#opt.stats_print"><quote><code class="mallctl">opt.stats_print</code></quote></a> is
enabled. The default is <span class="quote">“<span class="quote"/>”</span>.</p></dd><dt><a name="opt.stats_interval"/><span class="term">
<quote><code class="mallctl">opt.stats_interval</code></quote>
(<span class="type">int64_t</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Average interval between statistics outputs, as measured
in bytes of allocation activity. The actual interval may be sporadic
because decentralized event counters are used to avoid synchronization
bottlenecks. The output may be triggered on any thread, which then
calls <code class="function">malloc_stats_print()</code>. <a class="link" href="#opt.stats_interval_opts"><quote><code class="mallctl">opt.stats_interval_opts</code></quote></a>
can be combined to specify output options. By default,
interval-triggered stats output is disabled (encoded as
-1).</p></dd><dt><a name="opt.stats_interval_opts"/><span class="term">
<quote><code class="mallctl">opt.stats_interval_opts</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Options (the <em class="parameter"><code>opts</code></em> string) to pass
to the <code class="function">malloc_stats_print()</code> for interval based
statistics printing (enabled
through <a class="link" href="#opt.stats_interval"><quote><code class="mallctl">opt.stats_interval</code></quote></a>). See
available options in <a class="link" href="#malloc_stats_print_opts"><code class="function">malloc_stats_print()</code></a>.
Has no effect unless <a class="link" href="#opt.stats_interval"><quote><code class="mallctl">opt.stats_interval</code></quote></a> is
enabled. The default is <span class="quote">“<span class="quote"/>”</span>.</p></dd><dt><a name="opt.junk"/><span class="term">
<quote><code class="mallctl">opt.junk</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
[<code class="option">--enable-fill</code>]
</span></dt><dd><p>Junk filling. If set to <span class="quote">“<span class="quote">alloc</span>”</span>, each byte
of uninitialized allocated memory will be initialized to
<code class="literal">0xa5</code>. If set to <span class="quote">“<span class="quote">free</span>”</span>, all deallocated
memory will be initialized to <code class="literal">0x5a</code>. If set to
<span class="quote">“<span class="quote">true</span>”</span>, both allocated and deallocated memory will be
initialized, and if set to <span class="quote">“<span class="quote">false</span>”</span>, junk filling be
disabled entirely. This is intended for debugging and will impact
performance negatively. This option is <span class="quote">“<span class="quote">false</span>”</span> by default
unless <code class="option">--enable-debug</code> is specified during
configuration, in which case it is <span class="quote">“<span class="quote">true</span>”</span> by
default.</p></dd><dt><a name="opt.zero"/><span class="term">
<quote><code class="mallctl">opt.zero</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-fill</code>]
</span></dt><dd><p>Zero filling enabled/disabled. If enabled, each byte
of uninitialized allocated memory will be initialized to 0. Note that
this initialization only happens once for each byte, so
<code class="function">realloc()</code> and
<code class="function">rallocx()</code> calls do not zero memory that
was previously allocated. This is intended for debugging and will
impact performance negatively. This option is disabled by default.
</p></dd><dt><a name="opt.utrace"/><span class="term">
<quote><code class="mallctl">opt.utrace</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-utrace</code>]
</span></dt><dd><p>Allocation tracing based on
<span class="citerefentry"><span class="refentrytitle">utrace</span>(2)</span> enabled/disabled. This option
is disabled by default.</p></dd><dt><a name="opt.xmalloc"/><span class="term">
<quote><code class="mallctl">opt.xmalloc</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-xmalloc</code>]
</span></dt><dd><p>Abort-on-out-of-memory enabled/disabled. If enabled,
rather than returning failure for any allocation function, display a
diagnostic message on <code class="constant">STDERR_FILENO</code> and cause the
program to drop core (using
<span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span>). If an application is
designed to depend on this behavior, set the option at compile time by
including the following in the source code:
</p><pre class="programlisting">
malloc_conf = "xmalloc:true";</pre><p>
This option is disabled by default.</p></dd><dt><a name="opt.tcache"/><span class="term">
<quote><code class="mallctl">opt.tcache</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Thread-specific caching (tcache) enabled/disabled. When
there are multiple threads, each thread uses a tcache for objects up to
a certain size. Thread-specific caching allows many allocations to be
satisfied without performing any thread synchronization, at the cost of
increased memory use. See the <a class="link" href="#opt.tcache_max"><quote><code class="mallctl">opt.tcache_max</code></quote></a>
option for related tuning information. This option is enabled by
default.</p></dd><dt><a name="opt.tcache_max"/><span class="term">
<quote><code class="mallctl">opt.tcache_max</code></quote>
(<span class="type">size_t</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Maximum size class to cache in the thread-specific cache
(tcache). At a minimum, the first size class is cached; and at a
maximum, size classes up to 8 MiB can be cached. The default maximum is
32 KiB (2^15). As a convenience, this may also be set by specifying
lg_tcache_max, which will be taken to be the base-2 logarithm of the
setting of tcache_max.</p></dd><dt><a name="opt.thp"/><span class="term">
<quote><code class="mallctl">opt.thp</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Transparent hugepage (THP) mode. Settings "always",
"never" and "default" are available if THP is supported by the operating
system. The "always" setting enables transparent hugepage for all user
memory mappings with
<em class="parameter"><code><code class="constant">MADV_HUGEPAGE</code></code></em>; "never"
ensures no transparent hugepage with
<em class="parameter"><code><code class="constant">MADV_NOHUGEPAGE</code></code></em>; the default
setting "default" makes no changes. Note that: this option does not
affect THP for jemalloc internal metadata (see <a class="link" href="#opt.metadata_thp"><quote><code class="mallctl">opt.metadata_thp</code></quote></a>);
in addition, for arenas with customized <a class="link" href="#arena.i.extent_hooks"><quote><code class="mallctl">extent_hooks</code></quote></a>,
this option is bypassed as it is implemented as part of the default
extent hooks.</p></dd><dt><a name="opt.prof_bt_max"/><span class="term">
<quote><code class="mallctl">opt.prof_bt_max</code></quote>
(<span class="type">unsigned</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Maximum number of stack frames to record in profiling
backtraces. The default is 128.</p></dd><dt><a name="opt.prof"/><span class="term">
<quote><code class="mallctl">opt.prof</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Memory profiling enabled/disabled. If enabled, profile
memory allocation activity. See the <a class="link" href="#opt.prof_active"><quote><code class="mallctl">opt.prof_active</code></quote></a>
option for on-the-fly activation/deactivation. See the <a class="link" href="#opt.lg_prof_sample"><quote><code class="mallctl">opt.lg_prof_sample</code></quote></a>
option for probabilistic sampling control. See the <a class="link" href="#opt.prof_accum"><quote><code class="mallctl">opt.prof_accum</code></quote></a>
option for control of cumulative sample reporting. See the <a class="link" href="#opt.lg_prof_interval"><quote><code class="mallctl">opt.lg_prof_interval</code></quote></a>
option for information on interval-triggered profile dumping, the <a class="link" href="#opt.prof_gdump"><quote><code class="mallctl">opt.prof_gdump</code></quote></a>
option for information on high-water-triggered profile dumping, and the
<a class="link" href="#opt.prof_final"><quote><code class="mallctl">opt.prof_final</code></quote></a>
option for final profile dumping. Profile output is compatible with
the <span class="command"><strong>jeprof</strong></span> command, which is based on the
<span class="command"><strong>pprof</strong></span> that is developed as part of the <a class="ulink" href="http://code.google.com/p/gperftools/" target="_top">gperftools
package</a>. See <a class="link" href="#heap_profile_format" title="HEAP PROFILE FORMAT">HEAP PROFILE
FORMAT</a> for heap profile format documentation.</p></dd><dt><a name="opt.prof_prefix"/><span class="term">
<quote><code class="mallctl">opt.prof_prefix</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Filename prefix for profile dumps. If the prefix is
set to the empty string, no automatic dumps will occur; this is
primarily useful for disabling the automatic final heap dump (which
also disables leak reporting, if enabled). The default prefix is
<code class="filename">jeprof</code>. This prefix value can be overridden by
<a class="link" href="#prof.prefix"><quote><code class="mallctl">prof.prefix</code></quote></a>.
</p></dd><dt><a name="opt.prof_active"/><span class="term">
<quote><code class="mallctl">opt.prof_active</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Profiling activated/deactivated. This is a secondary
control mechanism that makes it possible to start the application with
profiling enabled (see the <a class="link" href="#opt.prof"><quote><code class="mallctl">opt.prof</code></quote></a> option) but
inactive, then toggle profiling at any time during program execution
with the <a class="link" href="#prof.active"><quote><code class="mallctl">prof.active</code></quote></a> mallctl.
This option is enabled by default.</p></dd><dt><a name="opt.prof_thread_active_init"/><span class="term">
<quote><code class="mallctl">opt.prof_thread_active_init</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Initial setting for <a class="link" href="#thread.prof.active"><quote><code class="mallctl">thread.prof.active</code></quote></a>
in newly created threads. The initial setting for newly created threads
can also be changed during execution via the <a class="link" href="#prof.thread_active_init"><quote><code class="mallctl">prof.thread_active_init</code></quote></a>
mallctl. This option is enabled by default.</p></dd><dt><a name="opt.lg_prof_sample"/><span class="term">
<quote><code class="mallctl">opt.lg_prof_sample</code></quote>
(<span class="type">size_t</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Average interval (log base 2) between allocation
samples, as measured in bytes of allocation activity. Increasing the
sampling interval decreases profile fidelity, but also decreases the
computational overhead. The default sample interval is 512 KiB (2^19
B).</p></dd><dt><a name="opt.prof_accum"/><span class="term">
<quote><code class="mallctl">opt.prof_accum</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Reporting of cumulative object/byte counts in profile
dumps enabled/disabled. If this option is enabled, every unique
backtrace must be stored for the duration of execution. Depending on
the application, this can impose a large memory overhead, and the
cumulative counts are not always of interest. This option is disabled
by default.</p></dd><dt><a name="opt.prof_pid_namespace"/><span class="term">
<quote><code class="mallctl">opt.prof_pid_namespace</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Enable adding the pid namespace to the profile
filename. Profiles are dumped to files named according to the pattern
<code class="filename"><prefix>.<pid_namespace>.<pid>.<seq>.i<iseq>.heap</code>,
where <code class="literal"><prefix></code> is controlled by the <a class="link" href="#opt.prof_prefix"><quote><code class="mallctl">opt.prof_prefix</code></quote></a> and
<a class="link" href="#prof.prefix"><quote><code class="mallctl">prof.prefix</code></quote></a>
options.
</p></dd><dt><a name="opt.lg_prof_interval"/><span class="term">
<quote><code class="mallctl">opt.lg_prof_interval</code></quote>
(<span class="type">ssize_t</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Average interval (log base 2) between memory profile
dumps, as measured in bytes of allocation activity. The actual
interval between dumps may be sporadic because decentralized allocation
counters are used to avoid synchronization bottlenecks. Profiles are
dumped to files named according to the pattern
<code class="filename"><prefix>.<pid>.<seq>.i<iseq>.heap</code>,
where <code class="literal"><prefix></code> is controlled by the
<a class="link" href="#opt.prof_prefix"><quote><code class="mallctl">opt.prof_prefix</code></quote></a> and
<a class="link" href="#prof.prefix"><quote><code class="mallctl">prof.prefix</code></quote></a>
options. By default, interval-triggered profile dumping is disabled
(encoded as -1).
</p></dd><dt><a name="opt.prof_gdump"/><span class="term">
<quote><code class="mallctl">opt.prof_gdump</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Set the initial state of <a class="link" href="#prof.gdump"><quote><code class="mallctl">prof.gdump</code></quote></a>, which when
enabled triggers a memory profile dump every time the total virtual
memory exceeds the previous maximum. This option is disabled by
default.</p></dd><dt><a name="opt.prof_final"/><span class="term">
<quote><code class="mallctl">opt.prof_final</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Use an
<span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function to dump final memory
usage to a file named according to the pattern
<code class="filename"><prefix>.<pid>.<seq>.f.heap</code>,
where <code class="literal"><prefix></code> is controlled by the <a class="link" href="#opt.prof_prefix"><quote><code class="mallctl">opt.prof_prefix</code></quote></a> and
<a class="link" href="#prof.prefix"><quote><code class="mallctl">prof.prefix</code></quote></a>
options. Note that <code class="function">atexit()</code> may allocate
memory during application initialization and then deadlock internally
when jemalloc in turn calls <code class="function">atexit()</code>, so
this option is not universally usable (though the application can
register its own <code class="function">atexit()</code> function with
equivalent functionality). This option is disabled by
default.</p></dd><dt><a name="opt.prof_leak"/><span class="term">
<quote><code class="mallctl">opt.prof_leak</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Leak reporting enabled/disabled. If enabled, use an
<span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function to report memory leaks
detected by allocation sampling. See the
<a class="link" href="#opt.prof"><quote><code class="mallctl">opt.prof</code></quote></a> option for
information on analyzing heap profile output. Works only when combined
with <a class="link" href="#opt.prof_final"><quote><code class="mallctl">opt.prof_final</code></quote>
</a>, otherwise does nothing. This option is disabled by default.
</p></dd><dt><a name="opt.prof_leak_error"/><span class="term">
<quote><code class="mallctl">opt.prof_leak_error</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
[<code class="option">--enable-prof</code>]
</span></dt><dd><p>Similar to <a class="link" href="#opt.prof_leak"><quote><code class="mallctl">
opt.prof_leak</code></quote></a>, but makes the process exit with error
code 1 if a memory leak is detected. This option supersedes
<a class="link" href="#opt.prof_leak"><quote><code class="mallctl">opt.prof_leak</code></quote></a>,
meaning that if both are specified, this option takes precedence. When
enabled, also enables <a class="link" href="#opt.prof_leak"><quote><code class="mallctl">
opt.prof_leak</code></quote></a>. Works only when combined with
<a class="link" href="#opt.prof_final"><quote><code class="mallctl">opt.prof_final</code></quote></a>,
otherwise does nothing. This option is disabled by default.
</p></dd><dt><a name="opt.zero_realloc"/><span class="term">
<quote><code class="mallctl">opt.zero_realloc</code></quote>
(<span class="type">const char *</span>)
<code class="literal">r-</code>
</span></dt><dd><p> Determines the behavior of
<code class="function">realloc()</code> when passed a value of zero for the new
size. <span class="quote">“<span class="quote">alloc</span>”</span> treats this as an allocation of size zero
(and returns a non-null result except in case of resource exhaustion).
<span class="quote">“<span class="quote">free</span>”</span> treats this as a deallocation of the pointer, and
returns <code class="constant">NULL</code> without setting
<code class="varname">errno</code>. <span class="quote">“<span class="quote">abort</span>”</span> aborts the process if
zero is passed. The default is <span class="quote">“<span class="quote">free</span>”</span> on Linux and
Windows, and <span class="quote">“<span class="quote">alloc</span>”</span> elsewhere.</p><p>There is considerable divergence of behaviors across
implementations in handling this case. Many have the behavior of
<span class="quote">“<span class="quote">free</span>”</span>. This can introduce security vulnerabilities, since
a <code class="constant">NULL</code> return value indicates failure, and the
continued validity of the passed-in pointer (per POSIX and C11).
<span class="quote">“<span class="quote">alloc</span>”</span> is safe, but can cause leaks in programs that
expect the common behavior. Programs intended to be portable and
leak-free cannot assume either behavior, and must therefore never call
realloc with a size of 0. The <span class="quote">“<span class="quote">abort</span>”</span> option enables these
testing this behavior.</p></dd><dt><a name="opt.debug_double_free_max_scan"/><span class="term">
<quote><code class="mallctl">opt.debug_double_free_max_scan</code></quote>
(<span class="type">unsigned</span>)
<code class="literal">r-</code>
[<code class="option">--enable-debug</code>]
</span></dt><dd><p>Maximum number of cached pointers to scan in the
thread cache when checking for double-free errors on deallocation.
When debug is enabled, each deallocation into the tcache scans up to
this many recently cached pointers to detect whether the same pointer
is being freed twice. Setting this to 0 disables the check. This
option is set to 0 and has no effect when debug is not enabled. The
default is 32.</p></dd><dt><a name="opt.disable_large_size_classes"/><span class="term">
<quote><code class="mallctl">opt.disable_large_size_classes</code></quote>
(<span class="type">bool</span>)
<code class="literal">r-</code>
</span></dt><dd><p>When enabled (the default), large allocations
(i.e. allocations of size >= <code class="constant">SC_LARGE_MINCLASS</code>)
are rounded up to the nearest page boundary rather than the nearest
large size class. This minimizes memory overhead, especially when
using hugepages, at the cost of disabling the standard large size
class hierarchy.</p></dd><dt><a name="opt.process_madvise_max_batch"/><span class="term">
<quote><code class="mallctl">opt.process_madvise_max_batch</code></quote>
(<span class="type">size_t</span>)
<code class="literal">r-</code>
</span></dt><dd><p>Maximum number of memory regions to include in each
<span class="citerefentry"><span class="refentrytitle">process_madvise</span>(2)</span> batch call. When set to 0
(the default), process_madvise is not used, and the standard
<span class="citerefentry"><span class="refentrytitle">madvise</span>(2)</span> is used instead. Setting this
to a positive value enables batched purging via process_madvise, which
can reduce the number of system calls needed for
purging.</p></dd><dt><a name="thread.arena"/><span class="term">
<quote><code class="mallctl">thread.arena</code></quote>
(<span class="type">unsigned</span>)
<code class="literal">rw</code>
</span></dt><dd><p>Get or set the arena associated with the calling
thread. If the specified arena was not initialized beforehand (see the
<a class="link" href="#arena.i.initialized"><quote><code class="mallctl">arena.i.initialized</code></quote></a>
mallctl), it will be automatically initialized as a side effect of
calling this interface.</p></dd><dt><a name="thread.allocated"/><span class="term">
<quote><code class="mallctl">thread.allocated</code></quote>
(<span class="type">uint64_t</span>)
<code class="literal">r-</code>
[<code class="option">--enable-stats</code>]
</span></dt><dd><p>Get the total number of bytes ever allocated by the
calling thread. This counter has the potential to wrap around; it is
up to the application to appropriately interpret the counter in such
cases.</p></dd><dt><a name="thread.allocatedp"/><span class="term">
<quote><code class="mallctl">thread.allocatedp</code></quote>
(<span class="type">uint64_t *</span>)
<code class="literal">r-</code>
[<code class="option">--enable-stats</code>]
</span></dt><dd><p>Get a pointer to the the value that is returned by the
<a class="link" href="#thread.allocated"><quote><code class="mallctl">thread.allocated</code></quote></a>
mallctl. This is useful for avoiding the overhead of repeated
<code class="function">mallctl*()</code> calls. Note that the underlying counter
should not be modified by the application.</p></dd><dt><a name="thread.deallocated"/><span class="term">
<quote><code class="mallctl">thread.deallocated</code></quote>
(<span class="type">uint64_t</span>)
<code class="literal">r-</code>
[<code class="option">--enable-stats</code>]
</span></dt><dd><p>Get the total number of bytes ever deallocated by the
calling thread. This counter has the potential to wrap around; it is
up to the application to appropriately interpret the counter in such
cases.</p></dd><dt><a name="thread.deallocatedp"/><span class="term">
<quote><code class="mallctl">thread.deallocatedp</code></quote>
(<span class="type">uint64_t *</span>)
<code class="literal">r-</code>
[<code class="option">--enable-stats</code>]
</span></dt><dd><p>Get a pointer to the the value that is returned by the
<a class="link" href="#thread.deallocated"><quote><code class="mallctl">thread.deallocated</code></quote></a>
mallctl. This is useful for avoiding the overhead of repeated
<code class="function">mallctl*()</code> calls. Note that the underlying counter
should not be modified by the application.</p></dd><dt><a name="thread.peak.read"/><span class="term">
<quote><code class="mallctl">thread.peak.read</code></quote>
(<span class="type">uint64_t</span>)
<code class="literal">r-</code>
[<code class="option">--enable-stats</code>]
</span></dt><dd><p>Get an approximation of the maximum value of the
difference between the number of bytes allocated and the number of bytes
deallocated by the calling thread since the last call to <a class="link" href="#thread.peak.reset"><quote><code class="mallctl">thread.peak.reset</code></quote></a>,
or since the thread's creation if it has not called <a class="link" href="#thread.peak.reset"><quote><code class="mallctl">thread.peak.reset</code></quote></a>.
No guarantees are made about the quality of the approximation, but
jemalloc currently endeavors to maintain accuracy to within one hundred
kilobytes.
</p></dd><dt><a name="thread.peak.reset"/><span class="term">
<quote><code class="mallctl">thread.peak.reset</code></quote>
(<span class="type">void</span>)
<code class="literal">--</code>
[<code class="option">--enable-stats</code>]
</span></dt><dd><p>Resets the counter for net bytes allocated in the calling
thread to zero. This affects subsequent calls to <a class="link" href="#thread.peak.read"><quote><code class="mallctl">thread.peak.read</code></quote></a>,
but not the values returned by <a class="link" href="#thread.allocated"><quote><code class="mallctl">thread.allocated</code></quote></a>
or <a class="link" href="#thread.deallocated"><quote><code class="mallctl">thread.deallocated</code></quote></a>.
</p></dd><dt><a name="thread.tcache.enabled"/><span class="term">
<quote><code class="mallctl">thread.tcache.enabled</code></quote>
(<span class="type">bool</span>)
<code class="literal">rw</code>
</span></dt><dd><p>Enable/disable calling thread's tcache. The tcache is
implicitly flushed as a side effect of becoming
disabled (see <a class="link" href="#thread.tcache.flush"><quote><code class="mallctl">thread.tcache.flush</code></quote></a>).
</p></dd><dt><a name="thread.tcache.flush"/><span class="term">
<quote><code class="mallctl">thread.tcache.flush</code></quote>
(<span class="type">void</span>)
<code class="literal">--</code>
</span></dt><dd><p>Flush calling thread's thread-specific cache (tcache).
This interface releases all cached objects and internal data structures
associated with the calling thread's tcache. Ordinarily, this interface