Debian Codegraph @

extra/gperftools/gperftools-2.15/README

raw
1 gperftools
2 ----------
3 (originally Google Performance Tools)
4
5 The fastest malloc we’ve seen; works particularly well with threads
6 and STL. Also: thread-friendly heap-checker, heap-profiler, and
7 cpu-profiler.
8
9
10 OVERVIEW
11 ---------
12
13 gperftools is a collection of a high-performance multi-threaded
14 malloc() implementation, plus some pretty nifty performance analysis
15 tools.
16
17 gperftools is distributed under the terms of the BSD License. Join our
18 mailing list at [email protected] for updates:
19 https://groups.google.com/forum/#!forum/gperftools
20
21 gperftools was original home for pprof program. But do note that
22 original pprof (which is still included with gperftools) is now
23 deprecated in favor of Go version at https://github.com/google/pprof
24
25
26 TCMALLOC
27 --------
28 Just link in -ltcmalloc or -ltcmalloc_minimal to get the advantages of
29 tcmalloc -- a replacement for malloc and new. See below for some
30 environment variables you can use with tcmalloc, as well.
31
32 tcmalloc functionality is available on all systems we've tested; see
33 INSTALL for more details. See README_windows.txt for instructions on
34 using tcmalloc on Windows.
35
36 when compiling. gcc makes some optimizations assuming it is using its
37 own, built-in malloc; that assumption obviously isn't true with
38 tcmalloc. In practice, we haven't seen any problems with this, but
39 the expected risk is highest for users who register their own malloc
40 hooks with tcmalloc (using gperftools/malloc_hook.h). The risk is
41 lowest for folks who use tcmalloc_minimal (or, of course, who pass in
42 the above flags :-) ).
43
44
45 HEAP PROFILER
46 -------------
47 See docs/heapprofile.html for information about how to use tcmalloc's
48 heap profiler and analyze its output.
49
50 As a quick-start, do the following after installing this package:
51
52 1) Link your executable with -ltcmalloc
53 2) Run your executable with the HEAPPROFILE environment var set:
54 $ HEAPPROFILE=/tmp/heapprof <path/to/binary> [binary args]
55 3) Run pprof to analyze the heap usage
56 $ pprof <path/to/binary> /tmp/heapprof.0045.heap # run 'ls' to see options
57 $ pprof --gv <path/to/binary> /tmp/heapprof.0045.heap
58
59 You can also use LD_PRELOAD to heap-profile an executable that you
60 didn't compile.
61
62 There are other environment variables, besides HEAPPROFILE, you can
63 set to adjust the heap-profiler behavior; c.f. "ENVIRONMENT VARIABLES"
64 below.
65
66 The heap profiler is available on all unix-based systems we've tested;
67 see INSTALL for more details. It is not currently available on Windows.
68
69
70 HEAP CHECKER
71 ------------
72
73 Please note that as of gperftools-2.11 this is deprecated. You should
74 consider asan and other sanitizers instead.
75
76 See docs/heap_checker.html for information about how to use tcmalloc's
77 heap checker.
78
79 In order to catch all heap leaks, tcmalloc must be linked *last* into
80 your executable. The heap checker may mischaracterize some memory
81 accesses in libraries listed after it on the link line. For instance,
82 it may report these libraries as leaking memory when they're not.
83 (See the source code for more details.)
84
85 Here's a quick-start for how to use:
86
87 As a quick-start, do the following after installing this package:
88
89 1) Link your executable with -ltcmalloc
90 2) Run your executable with the HEAPCHECK environment var set:
91 $ HEAPCHECK=1 <path/to/binary> [binary args]
92
93 Other values for HEAPCHECK: normal (equivalent to "1"), strict, draconian
94
95 You can also use LD_PRELOAD to heap-check an executable that you
96 didn't compile.
97
98 The heap checker is only available on Linux at this time; see INSTALL
99 for more details.
100
101
102 CPU PROFILER
103 ------------
104 See docs/cpuprofile.html for information about how to use the CPU
105 profiler and analyze its output.
106
107 As a quick-start, do the following after installing this package:
108
109 1) Link your executable with -lprofiler
110 2) Run your executable with the CPUPROFILE environment var set:
111 $ CPUPROFILE=/tmp/prof.out <path/to/binary> [binary args]
112 3) Run pprof to analyze the CPU usage
113 $ pprof <path/to/binary> /tmp/prof.out # -pg-like text output
114 $ pprof --gv <path/to/binary> /tmp/prof.out # really cool graphical output
115
116 There are other environment variables, besides CPUPROFILE, you can set
117 to adjust the cpu-profiler behavior; cf "ENVIRONMENT VARIABLES" below.
118
119 The CPU profiler is available on all unix-based systems we've tested;
120 see INSTALL for more details. It is not currently available on Windows.
121
122 NOTE: CPU profiling doesn't work after fork (unless you immediately
123 do an exec()-like call afterwards). Furthermore, if you do
124 fork, and the child calls exit(), it may corrupt the profile
125 data. You can use _exit() to work around this. We hope to have
126 a fix for both problems in the next release of perftools
127 (hopefully perftools 1.2).
128
129
130 EVERYTHING IN ONE
131 -----------------
132 If you want the CPU profiler, heap profiler, and heap leak-checker to
133 all be available for your application, you can do:
134 gcc -o myapp ... -lprofiler -ltcmalloc
135
136 However, if you have a reason to use the static versions of the
137 library, this two-library linking won't work:
138 gcc -o myapp ... /usr/lib/libprofiler.a /usr/lib/libtcmalloc.a # errors!
139
140 Instead, use the special libtcmalloc_and_profiler library, which we
141 make for just this purpose:
142 gcc -o myapp ... /usr/lib/libtcmalloc_and_profiler.a
143
144
145 CONFIGURATION OPTIONS
146 ---------------------
147 For advanced users, there are several flags you can pass to
148 './configure' that tweak tcmalloc performance. (These are in addition
149 to the environment variables you can set at runtime to affect
150 tcmalloc, described below.) See the INSTALL file for details.
151
152
153 ENVIRONMENT VARIABLES
154 ---------------------
155 The cpu profiler, heap checker, and heap profiler will lie dormant,
156 using no memory or CPU, until you turn them on. (Thus, there's no
157 harm in linking -lprofiler into every application, and also -ltcmalloc
158 assuming you're ok using the non-libc malloc library.)
159
160 The easiest way to turn them on is by setting the appropriate
161 environment variables. We have several variables that let you
162 enable/disable features as well as tweak parameters.
163
164 Here are some of the most important variables:
165
166 HEAPPROFILE=<pre> -- turns on heap profiling and dumps data using this prefix
167 HEAPCHECK=<type> -- turns on heap checking with strictness 'type'
168 CPUPROFILE=<file> -- turns on cpu profiling and dumps data to this file.
169 PROFILESELECTED=1 -- if set, cpu-profiler will only profile regions of code
170 surrounded with ProfilerEnable()/ProfilerDisable().
171 CPUPROFILE_FREQUENCY=x-- how many interrupts/second the cpu-profiler samples.
172
173 PERFTOOLS_VERBOSE=<level> -- the higher level, the more messages malloc emits
174 MALLOCSTATS=<level> -- prints memory-use stats at program-exit
175
176 For a full list of variables, see the documentation pages:
177 docs/cpuprofile.html
178 docs/heapprofile.html
179 docs/heap_checker.html
180
181 See also TCMALLOC_STACKTRACE_METHOD_VERBOSE and
182 TCMALLOC_STACKTRACE_METHOD environment variables briefly documented in
183 our INSTALL file and on our wiki page at:
184 https://github.com/gperftools/gperftools/wiki/gperftools'-stacktrace-capturing-methods-and-their-issues
185
186
187 COMPILING ON NON-LINUX SYSTEMS
188 ------------------------------
189
190 Perftools was developed and tested on x86, aarch64 and riscv Linux
191 systems, and it works in its full generality only on those systems.
192
193 However, we've successfully ported much of the tcmalloc library to
194 FreeBSD, Solaris x86 (not tested recently though), and Mac OS X
195 (aarch64; x86 and ppc have not been tested recently); and we've ported
196 the basic functionality in tcmalloc_minimal to Windows. See INSTALL
197 for details. See README_windows.txt for details on the Windows port.
198
199
200 ---
201 Originally written: 17 May 2011
202 Last refreshed: 10 Aug 2023