1. gperftools
  2. ----------
  3. (originally Google Performance Tools)
  4. The fastest malloc we’ve seen; works particularly well with threads
  5. and STL. Also: thread-friendly heap-checker, heap-profiler, and
  6. cpu-profiler.
  8. ---------
  9. gperftools is a collection of a high-performance multi-threaded
  10. malloc() implementation, plus some pretty nifty performance analysis
  11. tools.
  12. gperftools is distributed under the terms of the BSD License. Join our
  13. mailing list at for updates.
  14. gperftools was original home for pprof program. But do note that
  15. original pprof (which is still included with gerftools) is now
  16. deprecated in favor of golang version at
  18. --------
  19. Just link in -ltcmalloc or -ltcmalloc_minimal to get the advantages of
  20. tcmalloc -- a replacement for malloc and new. See below for some
  21. environment variables you can use with tcmalloc, as well.
  22. tcmalloc functionality is available on all systems we've tested; see
  23. INSTALL for more details. See README_windows.txt for instructions on
  24. using tcmalloc on Windows.
  25. NOTE: When compiling with programs with gcc, that you plan to link
  26. with libtcmalloc, it's safest to pass in the flags
  27. -fno-builtin-malloc -fno-builtin-calloc -fno-builtin-realloc -fno-builtin-free
  28. when compiling. gcc makes some optimizations assuming it is using its
  29. own, built-in malloc; that assumption obviously isn't true with
  30. tcmalloc. In practice, we haven't seen any problems with this, but
  31. the expected risk is highest for users who register their own malloc
  32. hooks with tcmalloc (using gperftools/malloc_hook.h). The risk is
  33. lowest for folks who use tcmalloc_minimal (or, of course, who pass in
  34. the above flags :-) ).
  36. -------------
  37. See doc/heap-profiler.html for information about how to use tcmalloc's
  38. heap profiler and analyze its output.
  39. As a quick-start, do the following after installing this package:
  40. 1) Link your executable with -ltcmalloc
  41. 2) Run your executable with the HEAPPROFILE environment var set:
  42. $ HEAPPROFILE=/tmp/heapprof <path/to/binary> [binary args]
  43. 3) Run pprof to analyze the heap usage
  44. $ pprof <path/to/binary> /tmp/heapprof.0045.heap # run 'ls' to see options
  45. $ pprof --gv <path/to/binary> /tmp/heapprof.0045.heap
  46. You can also use LD_PRELOAD to heap-profile an executable that you
  47. didn't compile.
  48. There are other environment variables, besides HEAPPROFILE, you can
  49. set to adjust the heap-profiler behavior; c.f. "ENVIRONMENT VARIABLES"
  50. below.
  51. The heap profiler is available on all unix-based systems we've tested;
  52. see INSTALL for more details. It is not currently available on Windows.
  54. ------------
  55. See doc/heap-checker.html for information about how to use tcmalloc's
  56. heap checker.
  57. In order to catch all heap leaks, tcmalloc must be linked *last* into
  58. your executable. The heap checker may mischaracterize some memory
  59. accesses in libraries listed after it on the link line. For instance,
  60. it may report these libraries as leaking memory when they're not.
  61. (See the source code for more details.)
  62. Here's a quick-start for how to use:
  63. As a quick-start, do the following after installing this package:
  64. 1) Link your executable with -ltcmalloc
  65. 2) Run your executable with the HEAPCHECK environment var set:
  66. $ HEAPCHECK=1 <path/to/binary> [binary args]
  67. Other values for HEAPCHECK: normal (equivalent to "1"), strict, draconian
  68. You can also use LD_PRELOAD to heap-check an executable that you
  69. didn't compile.
  70. The heap checker is only available on Linux at this time; see INSTALL
  71. for more details.
  73. ------------
  74. See doc/cpu-profiler.html for information about how to use the CPU
  75. profiler and analyze its output.
  76. As a quick-start, do the following after installing this package:
  77. 1) Link your executable with -lprofiler
  78. 2) Run your executable with the CPUPROFILE environment var set:
  79. $ CPUPROFILE=/tmp/prof.out <path/to/binary> [binary args]
  80. 3) Run pprof to analyze the CPU usage
  81. $ pprof <path/to/binary> /tmp/prof.out # -pg-like text output
  82. $ pprof --gv <path/to/binary> /tmp/prof.out # really cool graphical output
  83. There are other environment variables, besides CPUPROFILE, you can set
  84. to adjust the cpu-profiler behavior; cf "ENVIRONMENT VARIABLES" below.
  85. The CPU profiler is available on all unix-based systems we've tested;
  86. see INSTALL for more details. It is not currently available on Windows.
  87. NOTE: CPU profiling doesn't work after fork (unless you immediately
  88. do an exec()-like call afterwards). Furthermore, if you do
  89. fork, and the child calls exit(), it may corrupt the profile
  90. data. You can use _exit() to work around this. We hope to have
  91. a fix for both problems in the next release of perftools
  92. (hopefully perftools 1.2).
  94. -----------------
  95. If you want the CPU profiler, heap profiler, and heap leak-checker to
  96. all be available for your application, you can do:
  97. gcc -o myapp ... -lprofiler -ltcmalloc
  98. However, if you have a reason to use the static versions of the
  99. library, this two-library linking won't work:
  100. gcc -o myapp ... /usr/lib/libprofiler.a /usr/lib/libtcmalloc.a # errors!
  101. Instead, use the special libtcmalloc_and_profiler library, which we
  102. make for just this purpose:
  103. gcc -o myapp ... /usr/lib/libtcmalloc_and_profiler.a
  105. ---------------------
  106. For advanced users, there are several flags you can pass to
  107. './configure' that tweak tcmalloc performace. (These are in addition
  108. to the environment variables you can set at runtime to affect
  109. tcmalloc, described below.) See the INSTALL file for details.
  111. ---------------------
  112. The cpu profiler, heap checker, and heap profiler will lie dormant,
  113. using no memory or CPU, until you turn them on. (Thus, there's no
  114. harm in linking -lprofiler into every application, and also -ltcmalloc
  115. assuming you're ok using the non-libc malloc library.)
  116. The easiest way to turn them on is by setting the appropriate
  117. environment variables. We have several variables that let you
  118. enable/disable features as well as tweak parameters.
  119. Here are some of the most important variables:
  120. HEAPPROFILE=<pre> -- turns on heap profiling and dumps data using this prefix
  121. HEAPCHECK=<type> -- turns on heap checking with strictness 'type'
  122. CPUPROFILE=<file> -- turns on cpu profiling and dumps data to this file.
  123. PROFILESELECTED=1 -- if set, cpu-profiler will only profile regions of code
  124. surrounded with ProfilerEnable()/ProfilerDisable().
  125. CPUPROFILE_FREQUENCY=x-- how many interrupts/second the cpu-profiler samples.
  126. TCMALLOC_DEBUG=<level> -- the higher level, the more messages malloc emits
  127. MALLOCSTATS=<level> -- prints memory-use stats at program-exit
  128. For a full list of variables, see the documentation pages:
  129. doc/cpuprofile.html
  130. doc/heapprofile.html
  131. doc/heap_checker.html
  133. ------------------------------
  134. Perftools was developed and tested on x86 Linux systems, and it works
  135. in its full generality only on those systems. However, we've
  136. successfully ported much of the tcmalloc library to FreeBSD, Solaris
  137. x86, and Darwin (Mac OS X) x86 and ppc; and we've ported the basic
  138. functionality in tcmalloc_minimal to Windows. See INSTALL for details.
  139. See README_windows.txt for details on the Windows port.
  141. -----------
  142. If you're interested in some third-party comparisons of tcmalloc to
  143. other malloc libraries, here are a few web pages that have been
  144. brought to our attention. The first discusses the effect of using
  145. various malloc libraries on OpenLDAP. The second compares tcmalloc to
  146. win32's malloc.
  149. It's possible to build tcmalloc in a way that trades off faster
  150. performance (particularly for deletes) at the cost of more memory
  151. fragmentation (that is, more unusable memory on your system). See the
  152. INSTALL file for details.
  154. -----------------
  155. When compiling perftools on some old systems, like RedHat 8, you may
  156. get an error like this:
  157. ___tls_get_addr: symbol not found
  158. This means that you have a system where some parts are updated enough
  159. to support Thread Local Storage, but others are not. The perftools
  160. configure script can't always detect this kind of case, leading to
  161. that error. To fix it, just comment out (or delete) the line
  162. #define HAVE_TLS 1
  163. in your config.h file before building.
  164. 64-BIT ISSUES
  165. -------------
  166. There are two issues that can cause program hangs or crashes on x86_64
  167. 64-bit systems, which use the libunwind library to get stack-traces.
  168. Neither issue should affect the core tcmalloc library; they both
  169. affect the perftools tools such as cpu-profiler, heap-checker, and
  170. heap-profiler.
  171. 1) Some libc's -- at least glibc 2.4 on x86_64 -- have a bug where the
  172. libc function dl_iterate_phdr() acquires its locks in the wrong
  173. order. This bug should not affect tcmalloc, but may cause occasional
  174. deadlock with the cpu-profiler, heap-profiler, and heap-checker.
  175. Its likeliness increases the more dlopen() commands an executable has.
  176. Most executables don't have any, though several library routines like
  177. getgrgid() call dlopen() behind the scenes.
  178. 2) On x86-64 64-bit systems, while tcmalloc itself works fine, the
  179. cpu-profiler tool is unreliable: it will sometimes work, but sometimes
  180. cause a segfault. I'll explain the problem first, and then some
  181. workarounds.
  182. Note that this only affects the cpu-profiler, which is a
  183. gperftools feature you must turn on manually by setting the
  184. CPUPROFILE environment variable. If you do not turn on cpu-profiling,
  185. you shouldn't see any crashes due to perftools.
  186. The gory details: The underlying problem is in the backtrace()
  187. function, which is a built-in function in libc.
  188. Backtracing is fairly straightforward in the normal case, but can run
  189. into problems when having to backtrace across a signal frame.
  190. Unfortunately, the cpu-profiler uses signals in order to register a
  191. profiling event, so every backtrace that the profiler does crosses a
  192. signal frame.
  193. In our experience, the only time there is trouble is when the signal
  194. fires in the middle of pthread_mutex_lock. pthread_mutex_lock is
  195. called quite a bit from system libraries, particularly at program
  196. startup and when creating a new thread.
  197. The solution: The dwarf debugging format has support for 'cfi
  198. annotations', which make it easy to recognize a signal frame. Some OS
  199. distributions, such as Fedora and gentoo 2007.0, already have added
  200. cfi annotations to their libc. A future version of libunwind should
  201. recognize these annotations; these systems should not see any
  202. crashses.
  203. Workarounds: If you see problems with crashes when running the
  204. cpu-profiler, consider inserting ProfilerStart()/ProfilerStop() into
  205. your code, rather than setting CPUPROFILE. This will profile only
  206. those sections of the codebase. Though we haven't done much testing,
  207. in theory this should reduce the chance of crashes by limiting the
  208. signal generation to only a small part of the codebase. Ideally, you
  209. would not use ProfilerStart()/ProfilerStop() around code that spawns
  210. new threads, or is otherwise likely to cause a call to
  211. pthread_mutex_lock!
  212. ---
  213. 17 May 2011