feat add gperftools
This commit is contained in:
tqcq
202
3party/gperftools/README
Normal file
202
3party/gperftools/README
Normal file
@@ -0,0 +1,202 @@
|
||||
gperftools
|
||||
----------
|
||||
(originally Google Performance Tools)
|
||||
|
||||
The fastest malloc we’ve seen; works particularly well with threads
|
||||
and STL. Also: thread-friendly heap-checker, heap-profiler, and
|
||||
cpu-profiler.
|
||||
|
||||
|
||||
OVERVIEW
|
||||
---------
|
||||
|
||||
gperftools is a collection of a high-performance multi-threaded
|
||||
malloc() implementation, plus some pretty nifty performance analysis
|
||||
tools.
|
||||
|
||||
gperftools is distributed under the terms of the BSD License. Join our
|
||||
mailing list at gperftools@googlegroups.com for updates:
|
||||
https://groups.google.com/forum/#!forum/gperftools
|
||||
|
||||
gperftools was original home for pprof program. But do note that
|
||||
original pprof (which is still included with gperftools) is now
|
||||
deprecated in favor of Go version at https://github.com/google/pprof
|
||||
|
||||
|
||||
TCMALLOC
|
||||
--------
|
||||
Just link in -ltcmalloc or -ltcmalloc_minimal to get the advantages of
|
||||
tcmalloc -- a replacement for malloc and new. See below for some
|
||||
environment variables you can use with tcmalloc, as well.
|
||||
|
||||
tcmalloc functionality is available on all systems we've tested; see
|
||||
INSTALL for more details. See README_windows.txt for instructions on
|
||||
using tcmalloc on Windows.
|
||||
|
||||
when compiling. gcc makes some optimizations assuming it is using its
|
||||
own, built-in malloc; that assumption obviously isn't true with
|
||||
tcmalloc. In practice, we haven't seen any problems with this, but
|
||||
the expected risk is highest for users who register their own malloc
|
||||
hooks with tcmalloc (using gperftools/malloc_hook.h). The risk is
|
||||
lowest for folks who use tcmalloc_minimal (or, of course, who pass in
|
||||
the above flags :-) ).
|
||||
|
||||
|
||||
HEAP PROFILER
|
||||
-------------
|
||||
See docs/heapprofile.html for information about how to use tcmalloc's
|
||||
heap profiler and analyze its output.
|
||||
|
||||
As a quick-start, do the following after installing this package:
|
||||
|
||||
1) Link your executable with -ltcmalloc
|
||||
2) Run your executable with the HEAPPROFILE environment var set:
|
||||
$ HEAPPROFILE=/tmp/heapprof <path/to/binary> [binary args]
|
||||
3) Run pprof to analyze the heap usage
|
||||
$ pprof <path/to/binary> /tmp/heapprof.0045.heap # run 'ls' to see options
|
||||
$ pprof --gv <path/to/binary> /tmp/heapprof.0045.heap
|
||||
|
||||
You can also use LD_PRELOAD to heap-profile an executable that you
|
||||
didn't compile.
|
||||
|
||||
There are other environment variables, besides HEAPPROFILE, you can
|
||||
set to adjust the heap-profiler behavior; c.f. "ENVIRONMENT VARIABLES"
|
||||
below.
|
||||
|
||||
The heap profiler is available on all unix-based systems we've tested;
|
||||
see INSTALL for more details. It is not currently available on Windows.
|
||||
|
||||
|
||||
HEAP CHECKER
|
||||
------------
|
||||
|
||||
Please note that as of gperftools-2.11 this is deprecated. You should
|
||||
consider asan and other sanitizers instead.
|
||||
|
||||
See docs/heap_checker.html for information about how to use tcmalloc's
|
||||
heap checker.
|
||||
|
||||
In order to catch all heap leaks, tcmalloc must be linked *last* into
|
||||
your executable. The heap checker may mischaracterize some memory
|
||||
accesses in libraries listed after it on the link line. For instance,
|
||||
it may report these libraries as leaking memory when they're not.
|
||||
(See the source code for more details.)
|
||||
|
||||
Here's a quick-start for how to use:
|
||||
|
||||
As a quick-start, do the following after installing this package:
|
||||
|
||||
1) Link your executable with -ltcmalloc
|
||||
2) Run your executable with the HEAPCHECK environment var set:
|
||||
$ HEAPCHECK=1 <path/to/binary> [binary args]
|
||||
|
||||
Other values for HEAPCHECK: normal (equivalent to "1"), strict, draconian
|
||||
|
||||
You can also use LD_PRELOAD to heap-check an executable that you
|
||||
didn't compile.
|
||||
|
||||
The heap checker is only available on Linux at this time; see INSTALL
|
||||
for more details.
|
||||
|
||||
|
||||
CPU PROFILER
|
||||
------------
|
||||
See docs/cpuprofile.html for information about how to use the CPU
|
||||
profiler and analyze its output.
|
||||
|
||||
As a quick-start, do the following after installing this package:
|
||||
|
||||
1) Link your executable with -lprofiler
|
||||
2) Run your executable with the CPUPROFILE environment var set:
|
||||
$ CPUPROFILE=/tmp/prof.out <path/to/binary> [binary args]
|
||||
3) Run pprof to analyze the CPU usage
|
||||
$ pprof <path/to/binary> /tmp/prof.out # -pg-like text output
|
||||
$ pprof --gv <path/to/binary> /tmp/prof.out # really cool graphical output
|
||||
|
||||
There are other environment variables, besides CPUPROFILE, you can set
|
||||
to adjust the cpu-profiler behavior; cf "ENVIRONMENT VARIABLES" below.
|
||||
|
||||
The CPU profiler is available on all unix-based systems we've tested;
|
||||
see INSTALL for more details. It is not currently available on Windows.
|
||||
|
||||
NOTE: CPU profiling doesn't work after fork (unless you immediately
|
||||
do an exec()-like call afterwards). Furthermore, if you do
|
||||
fork, and the child calls exit(), it may corrupt the profile
|
||||
data. You can use _exit() to work around this. We hope to have
|
||||
a fix for both problems in the next release of perftools
|
||||
(hopefully perftools 1.2).
|
||||
|
||||
|
||||
EVERYTHING IN ONE
|
||||
-----------------
|
||||
If you want the CPU profiler, heap profiler, and heap leak-checker to
|
||||
all be available for your application, you can do:
|
||||
gcc -o myapp ... -lprofiler -ltcmalloc
|
||||
|
||||
However, if you have a reason to use the static versions of the
|
||||
library, this two-library linking won't work:
|
||||
gcc -o myapp ... /usr/lib/libprofiler.a /usr/lib/libtcmalloc.a # errors!
|
||||
|
||||
Instead, use the special libtcmalloc_and_profiler library, which we
|
||||
make for just this purpose:
|
||||
gcc -o myapp ... /usr/lib/libtcmalloc_and_profiler.a
|
||||
|
||||
|
||||
CONFIGURATION OPTIONS
|
||||
---------------------
|
||||
For advanced users, there are several flags you can pass to
|
||||
'./configure' that tweak tcmalloc performance. (These are in addition
|
||||
to the environment variables you can set at runtime to affect
|
||||
tcmalloc, described below.) See the INSTALL file for details.
|
||||
|
||||
|
||||
ENVIRONMENT VARIABLES
|
||||
---------------------
|
||||
The cpu profiler, heap checker, and heap profiler will lie dormant,
|
||||
using no memory or CPU, until you turn them on. (Thus, there's no
|
||||
harm in linking -lprofiler into every application, and also -ltcmalloc
|
||||
assuming you're ok using the non-libc malloc library.)
|
||||
|
||||
The easiest way to turn them on is by setting the appropriate
|
||||
environment variables. We have several variables that let you
|
||||
enable/disable features as well as tweak parameters.
|
||||
|
||||
Here are some of the most important variables:
|
||||
|
||||
HEAPPROFILE=<pre> -- turns on heap profiling and dumps data using this prefix
|
||||
HEAPCHECK=<type> -- turns on heap checking with strictness 'type'
|
||||
CPUPROFILE=<file> -- turns on cpu profiling and dumps data to this file.
|
||||
PROFILESELECTED=1 -- if set, cpu-profiler will only profile regions of code
|
||||
surrounded with ProfilerEnable()/ProfilerDisable().
|
||||
CPUPROFILE_FREQUENCY=x-- how many interrupts/second the cpu-profiler samples.
|
||||
|
||||
PERFTOOLS_VERBOSE=<level> -- the higher level, the more messages malloc emits
|
||||
MALLOCSTATS=<level> -- prints memory-use stats at program-exit
|
||||
|
||||
For a full list of variables, see the documentation pages:
|
||||
docs/cpuprofile.html
|
||||
docs/heapprofile.html
|
||||
docs/heap_checker.html
|
||||
|
||||
See also TCMALLOC_STACKTRACE_METHOD_VERBOSE and
|
||||
TCMALLOC_STACKTRACE_METHOD environment variables briefly documented in
|
||||
our INSTALL file and on our wiki page at:
|
||||
https://github.com/gperftools/gperftools/wiki/gperftools'-stacktrace-capturing-methods-and-their-issues
|
||||
|
||||
|
||||
COMPILING ON NON-LINUX SYSTEMS
|
||||
------------------------------
|
||||
|
||||
Perftools was developed and tested on x86, aarch64 and riscv Linux
|
||||
systems, and it works in its full generality only on those systems.
|
||||
|
||||
However, we've successfully ported much of the tcmalloc library to
|
||||
FreeBSD, Solaris x86 (not tested recently though), and Mac OS X
|
||||
(aarch64; x86 and ppc have not been tested recently); and we've ported
|
||||
the basic functionality in tcmalloc_minimal to Windows. See INSTALL
|
||||
for details. See README_windows.txt for details on the Windows port.
|
||||
|
||||
|
||||
---
|
||||
Originally written: 17 May 2011
|
||||
Last refreshed: 10 Aug 2023
|
||||
Reference in New Issue
Block a user