diff options
Diffstat (limited to 'third_party/tcmalloc/vendor/README')
| -rw-r--r-- | third_party/tcmalloc/vendor/README | 112 |
1 files changed, 80 insertions, 32 deletions
diff --git a/third_party/tcmalloc/vendor/README b/third_party/tcmalloc/vendor/README index c7ef8c5..21b18d5 100644 --- a/third_party/tcmalloc/vendor/README +++ b/third_party/tcmalloc/vendor/README @@ -4,34 +4,6 @@ There are known issues with some perftools functionality on x86_64 systems. See 64-BIT ISSUES, below. -CPU PROFILER ------------- -See doc/cpu-profiler.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). - - TCMALLOC -------- Just link in -ltcmalloc or -ltcmalloc_minimal to get the advantages of @@ -39,9 +11,22 @@ 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 for instructions on +INSTALL for more details. See README_windows.txt for instructions on using tcmalloc on Windows. +NOTE: When compiling with programs with gcc, that you plan to link +with libtcmalloc, it's safest to pass in the flags + + -fno-builtin-malloc -fno-builtin-calloc -fno-builtin-realloc -fno-builtin-free + +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 google/malloc_hook.h). The risk is lowest +for folks who use tcmalloc_minimal (or, of course, who pass in the +above flags :-) ). + HEAP PROFILER ------------- @@ -52,7 +37,7 @@ 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: - $ HEAPROFILE=/tmp/heapprof <path/to/binary> [binary args] + $ 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 @@ -96,6 +81,34 @@ The heap checker is only available on Linux at this time; see INSTALL for more details. +CPU PROFILER +------------ +See doc/cpu-profiler.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 @@ -111,6 +124,14 @@ 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 performace. (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, @@ -148,7 +169,7 @@ in its full generality only on those systems. However, we've successfully ported much of the tcmalloc library to FreeBSD, Solaris x86, and Darwin (Mac OS X) x86 and ppc; and we've ported the basic functionality in tcmalloc_minimal to Windows. See INSTALL for details. -See README.windows for details on the Windows port. +See README_windows.txt for details on the Windows port. PERFORMANCE @@ -162,6 +183,11 @@ win32's malloc. http://www.highlandsun.com/hyc/malloc/ http://gaiacrtn.free.fr/articles/win32perftools.html +It's possible to build tcmalloc in a way that trades off faster +performance (particularly for deletes) at the cost of more memory +fragmentation (that is, more unusable memory on your system). See the +INSTALL file for details. + OLD SYSTEM ISSUES ----------------- @@ -178,6 +204,28 @@ that error. To fix it, just comment out (or delete) the line in your config.h file before building. +OS X ISSUES +----------- + +You may need to set the environment variable DYLD_FORCE_FLAT_NAMESPACE +to use perftools with OS X. Because of how OS X does symbol binding, +libc routines will use libc malloc even when the binary is linked with +-ltcmalloc. This is not usually a problem, but becomes one if the +application is responsible for freeing that memory: the application +will use tcmalloc's free() to try to free memory allocated with libc's +malloc(), which will cause no end of confusion. + +One (or both) of these workaround may fix the problem: + DYLD_FORCE_FLAT_NAMESPACE=1 myapp + DYLD_INSERT_LIBRARIES=path/to/libtcmalloc.dylib myapp + +The best solution may depend on the version of OS X being used. +Neither solution is likely to work if you dlopen() libraries from +within your application. If you have any experience with this, we'd +appreciate you sharing it at + http://groups.google.com/group/google-perftools + + 64-BIT ISSUES ------------- @@ -236,4 +284,4 @@ new threads, or is otherwise likely to cause a call to pthread_mutex_lock! --- -22 May 2009 +17 May 2011 |