http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/heap_checker.html ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/heap_checker.html b/third_party/gperftools/doc/heap_checker.html deleted file mode 100644 index ea2ade6..0000000 --- a/third_party/gperftools/doc/heap_checker.html +++ /dev/null @@ -1,534 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<HTML> - -<HEAD> - <link rel="stylesheet" href="designstyle.css"> - <title>Gperftools Heap Leak Checker</title> -</HEAD> - -<BODY> - -<p align=right> - <i>Last modified - <script type=text/javascript> - var lm = new Date(document.lastModified); - document.write(lm.toDateString()); - </script></i> -</p> - -<p>This is the heap checker we use at Google to detect memory leaks in -C++ programs. There are three parts to using it: linking the library -into an application, running the code, and analyzing the output.</p> - - -<H1>Linking in the Library</H1> - -<p>The heap-checker is part of tcmalloc, so to install the heap -checker into your executable, add <code>-ltcmalloc</code> to the -link-time step for your executable. Also, while we don't necessarily -recommend this form of usage, it's possible to add in the profiler at -run-time using <code>LD_PRELOAD</code>:</p> -<pre>% env LD_PRELOAD="/usr/lib/libtcmalloc.so" <binary></pre> - -<p>This does <i>not</i> turn on heap checking; it just inserts the -code. For that reason, it's practical to just always link -<code>-ltcmalloc</code> into a binary while developing; that's what we -do at Google. (However, since any user can turn on the profiler by -setting an environment variable, it's not necessarily recommended to -install heapchecker-linked binaries into a production, running -system.) Note that if you wish to use the heap checker, you must -also use the tcmalloc memory-allocation library. There is no way -currently to use the heap checker separate from tcmalloc.</p> - - -<h1>Running the Code</h1> - -<p>Note: For security reasons, heap profiling will not write to a file --- and is thus not usable -- for setuid programs.</p> - -<h2><a name="whole_program">Whole-program Heap Leak Checking</a></h2> - -<p>The recommended way to use the heap checker is in "whole program" -mode. In this case, the heap-checker starts tracking memory -allocations before the start of <code>main()</code>, and checks again -at program-exit. If it finds any memory leaks -- that is, any memory -not pointed to by objects that are still "live" at program-exit -- it -aborts the program (via <code>exit(1)</code>) and prints a message -describing how to track down the memory leak (using <A -HREF="heapprofile.html#pprof">pprof</A>).</p> - -<p>The heap-checker records the stack trace for each allocation while -it is active. This causes a significant increase in memory usage, in -addition to slowing your program down.</p> - -<p>Here's how to run a program with whole-program heap checking:</p> - -<ol> - <li> <p>Define the environment variable HEAPCHECK to the <A - HREF="#types">type of heap-checking</A> to do. For instance, - to heap-check - <code>/usr/local/bin/my_binary_compiled_with_tcmalloc</code>:</p> - <pre>% env HEAPCHECK=normal /usr/local/bin/my_binary_compiled_with_tcmalloc</pre> -</ol> - -<p>No other action is required.</p> - -<p>Note that since the heap-checker uses the heap-profiling framework -internally, it is not possible to run both the heap-checker and <A -HREF="heapprofile.html">heap profiler</A> at the same time.</p> - - -<h3><a name="types">Flavors of Heap Checking</a></h3> - -<p>These are the legal values when running a whole-program heap -check:</p> -<ol> - <li> <code>minimal</code> - <li> <code>normal</code> - <li> <code>strict</code> - <li> <code>draconian</code> -</ol> - -<p>"Minimal" heap-checking starts as late as possible in a -initialization, meaning you can leak some memory in your -initialization routines (that run before <code>main()</code>, say), -and not trigger a leak message. If you frequently (and purposefully) -leak data in one-time global initializers, "minimal" mode is useful -for you. Otherwise, you should avoid it for stricter modes.</p> - -<p>"Normal" heap-checking tracks <A HREF="#live">live objects</A> and -reports a leak for any data that is not reachable via a live object -when the program exits.</p> - -<p>"Strict" heap-checking is much like "normal" but has a few extra -checks that memory isn't lost in global destructors. In particular, -if you have a global variable that allocates memory during program -execution, and then "forgets" about the memory in the global -destructor (say, by setting the pointer to it to NULL) without freeing -it, that will prompt a leak message in "strict" mode, though not in -"normal" mode.</p> - -<p>"Draconian" heap-checking is appropriate for those who like to be -very precise about their memory management, and want the heap-checker -to help them enforce it. In "draconian" mode, the heap-checker does -not do "live object" checking at all, so it reports a leak unless -<i>all</i> allocated memory is freed before program exit. (However, -you can use <A HREF="#disable">IgnoreObject()</A> to re-enable -liveness-checking on an object-by-object basis.)</p> - -<p>"Normal" mode, as the name implies, is the one used most often at -Google. It's appropriate for everyday heap-checking use.</p> - -<p>In addition, there are two other possible modes:</p> -<ul> - <li> <code>as-is</code> - <li> <code>local</code> -</ul> -<p><code>as-is</code> is the most flexible mode; it allows you to -specify the various <A HREF="#options">knobs</A> of the heap checker -explicitly. <code>local</code> activates the <A -HREF="#explicit">explicit heap-check instrumentation</A>, but does not -turn on any whole-program leak checking.</p> - - -<h3><A NAME="tweaking">Tweaking whole-program checking</A></h3> - -<p>In some cases you want to check the whole program for memory leaks, -but waiting for after <code>main()</code> exits to do the first -whole-program leak check is waiting too long: e.g. in a long-running -server one might wish to simply periodically check for leaks while the -server is running. In this case, you can call the static method -<code>NoGlobalLeaks()</code>, to verify no global leaks have happened -as of that point in the program.</p> - -<p>Alternately, doing the check after <code>main()</code> exits might -be too late. Perhaps you have some objects that are known not to -clean up properly at exit. You'd like to do the "at exit" check -before those objects are destroyed (since while they're live, any -memory they point to will not be considered a leak). In that case, -you can call <code>NoGlobalLeaks()</code> manually, near the end of -<code>main()</code>, and then call <code>CancelGlobalCheck()</code> to -turn off the automatic post-<code>main()</code> check.</p> - -<p>Finally, there's a helper macro for "strict" and "draconian" modes, -which require all global memory to be freed before program exit. This -freeing can be time-consuming and is often unnecessary, since libc -cleans up all memory at program-exit for you. If you want the -benefits of "strict"/"draconian" modes without the cost of all that -freeing, look at <code>REGISTER_HEAPCHECK_CLEANUP</code> (in -<code>heap-checker.h</code>). This macro allows you to mark specific -cleanup code as active only when the heap-checker is turned on.</p> - - -<h2><a name="explicit">Explicit (Partial-program) Heap Leak Checking</h2> - -<p>Instead of whole-program checking, you can check certain parts of your -code to verify they do not have memory leaks. This check verifies that -between two parts of a program, no memory is allocated without being freed.</p> -<p>To use this kind of checking code, bracket the code you want -checked by creating a <code>HeapLeakChecker</code> object at the -beginning of the code segment, and call -<code>NoLeaks()</code> at the end. These functions, and all others -referred to in this file, are declared in -<code><gperftools/heap-checker.h></code>. -</p> - -<p>Here's an example:</p> -<pre> - HeapLeakChecker heap_checker("test_foo"); - { - code that exercises some foo functionality; - this code should not leak memory; - } - if (!heap_checker.NoLeaks()) assert(NULL == "heap memory leak"); -</pre> - -<p>Note that adding in the <code>HeapLeakChecker</code> object merely -instruments the code for leak-checking. To actually turn on this -leak-checking on a particular run of the executable, you must still -run with the heap-checker turned on:</p> -<pre>% env HEAPCHECK=local /usr/local/bin/my_binary_compiled_with_tcmalloc</pre> -<p>If you want to do whole-program leak checking in addition to this -manual leak checking, you can run in <code>normal</code> or some other -mode instead: they'll run the "local" checks in addition to the -whole-program check.</p> - - -<h2><a name="disable">Disabling Heap-checking of Known Leaks</a></h2> - -<p>Sometimes your code has leaks that you know about and are willing -to accept. You would like the heap checker to ignore them when -checking your program. You can do this by bracketing the code in -question with an appropriate heap-checking construct:</p> -<pre> - ... - { - HeapLeakChecker::Disabler disabler; - <leaky code> - } - ... -</pre> -Any objects allocated by <code>leaky code</code> (including inside any -routines called by <code>leaky code</code>) and any objects reachable -from such objects are not reported as leaks. - -<p>Alternately, you can use <code>IgnoreObject()</code>, which takes a -pointer to an object to ignore. That memory, and everything reachable -from it (by following pointers), is ignored for the purposes of leak -checking. You can call <code>UnIgnoreObject()</code> to undo the -effects of <code>IgnoreObject()</code>.</p> - - -<h2><a name="options">Tuning the Heap Checker</h2> - -<p>The heap leak checker has many options, some that trade off running -time and accuracy, and others that increase the sensitivity at the -risk of returning false positives. For most uses, the range covered -by the <A HREF="#types">heap-check flavors</A> is enough, but in -specialized cases more control can be helpful.</p> - -<p> -These options are specified via environment varaiables. -</p> - -<p>This first set of options controls sensitivity and accuracy. These -options are ignored unless you run the heap checker in <A -HREF="#types">as-is</A> mode. - -<table frame=box rules=sides cellpadding=5 width=100%> - -<tr valign=top> - <td><code>HEAP_CHECK_AFTER_DESTRUCTORS</code></td> - <td>Default: false</td> - <td> - When true, do the final leak check after all other global - destructors have run. When false, do it after all - <code>REGISTER_HEAPCHECK_CLEANUP</code>, typically much earlier in - the global-destructor process. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_CHECK_IGNORE_THREAD_LIVE</code></td> - <td>Default: true</td> - <td> - If true, ignore objects reachable from thread stacks and registers - (that is, do not report them as leaks). - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_CHECK_IGNORE_GLOBAL_LIVE</code></td> - <td>Default: true</td> - <td> - If true, ignore objects reachable from global variables and data - (that is, do not report them as leaks). - </td> -</tr> - -</table> - -<p>These options modify the behavior of whole-program leak -checking.</p> - -<table frame=box rules=sides cellpadding=5 width=100%> - -<tr valign=top> - <td><code>HEAP_CHECK_MAX_LEAKS</code></td> - <td>Default: 20</td> - <td> - The maximum number of leaks to be printed to stderr (all leaks are still - emitted to file output for pprof to visualize). If negative or zero, - print all the leaks found. - </td> -</tr> - - -</table> - -<p>These options apply to all types of leak checking.</p> - -<table frame=box rules=sides cellpadding=5 width=100%> - -<tr valign=top> - <td><code>HEAP_CHECK_IDENTIFY_LEAKS</code></td> - <td>Default: false</td> - <td> - If true, generate the addresses of the leaked objects in the - generated memory leak profile files. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_CHECK_TEST_POINTER_ALIGNMENT</code></td> - <td>Default: false</td> - <td> - If true, check all leaks to see if they might be due to the use - of unaligned pointers. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_CHECK_POINTER_SOURCE_ALIGNMENT</code></td> - <td>Default: sizeof(void*)</td> - <td> - Alignment at which all pointers in memory are supposed to be located. - Use 1 if any alignment is ok. - </td> -</tr> - -<tr valign=top> - <td><code>PPROF_PATH</code></td> - <td>Default: pprof</td> -<td> - The location of the <code>pprof</code> executable. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_CHECK_DUMP_DIRECTORY</code></td> - <td>Default: /tmp</td> - <td> - Where the heap-profile files are kept while the program is running. - </td> -</tr> - -</table> - - -<h2>Tips for Handling Detected Leaks</h2> - -<p>What do you do when the heap leak checker detects a memory leak? -First, you should run the reported <code>pprof</code> command; -hopefully, that is enough to track down the location where the leak -occurs.</p> - -<p>If the leak is a real leak, you should fix it!</p> - -<p>If you are sure that the reported leaks are not dangerous and there -is no good way to fix them, then you can use -<code>HeapLeakChecker::Disabler</code> and/or -<code>HeapLeakChecker::IgnoreObject()</code> to disable heap-checking -for certain parts of the codebase.</p> - -<p>In "strict" or "draconian" mode, leaks may be due to incomplete -cleanup in the destructors of global variables. If you don't wish to -augment the cleanup routines, but still want to run in "strict" or -"draconian" mode, consider using <A -HREF="#tweaking"><code>REGISTER_HEAPCHECK_CLEANUP</code></A>.</p> - -<h2>Hints for Debugging Detected Leaks</h2> - -<p>Sometimes it can be useful to not only know the exact code that -allocates the leaked objects, but also the addresses of the leaked objects. -Combining this e.g. with additional logging in the program -one can then track which subset of the allocations -made at a certain spot in the code are leaked. -<br/> -To get the addresses of all leaked objects - define the environment variable <code>HEAP_CHECK_IDENTIFY_LEAKS</code> - to be <code>1</code>. -The object addresses will be reported in the form of addresses -of fake immediate callers of the memory allocation routines. -Note that the performance of doing leak-checking in this mode -can be noticeably worse than the default mode. -</p> - -<p>One relatively common class of leaks that don't look real -is the case of multiple initialization. -In such cases the reported leaks are typically things that are -linked from some global objects, -which are initialized and say never modified again. -The non-obvious cause of the leak is frequently the fact that -the initialization code for these objects executes more than once. -<br/> -E.g. if the code of some <code>.cc</code> file is made to be included twice -into the binary, then the constructors for global objects defined in that file -will execute twice thus leaking the things allocated on the first run. -<br/> -Similar problems can occur if object initialization is done more explicitly -e.g. on demand by a slightly buggy code -that does not always ensure only-once initialization. -</p> - -<p> -A more rare but even more puzzling problem can be use of not properly -aligned pointers (maybe inside of not properly aligned objects). -Normally such pointers are not followed by the leak checker, -hence the objects reachable only via such pointers are reported as leaks. -If you suspect this case - define the environment variable <code>HEAP_CHECK_TEST_POINTER_ALIGNMENT</code> - to be <code>1</code> -and then look closely at the generated leak report messages. -</p> - -<h1>How It Works</h1> - -<p>When a <code>HeapLeakChecker</code> object is constructed, it dumps -a memory-usage profile named -<code><prefix>.<name>-beg.heap</code> to a temporary -directory. When <code>NoLeaks()</code> -is called (for whole-program checking, this happens automatically at -program-exit), it dumps another profile, named -<code><prefix>.<name>-end.heap</code>. -(<code><prefix></code> is typically determined automatically, -and <code><name></code> is typically <code>argv[0]</code>.) It -then compares the two profiles. If the second profile shows -more memory use than the first, the -<code>NoLeaks()</code> function will -return false. For "whole program" profiling, this will cause the -executable to abort (via <code>exit(1)</code>). In all cases, it will -print a message on how to process the dumped profiles to locate -leaks.</p> - -<h3><A name=live>Detecting Live Objects</A></h3> - -<p>At any point during a program's execution, all memory that is -accessible at that time is considered "live." This includes global -variables, and also any memory that is reachable by following pointers -from a global variable. It also includes all memory reachable from -the current stack frame and from current CPU registers (this captures -local variables). Finally, it includes the thread equivalents of -these: thread-local storage and thread heaps, memory reachable from -thread-local storage and thread heaps, and memory reachable from -thread CPU registers.</p> - -<p>In all modes except "draconian," live memory is not -considered to be a leak. We detect this by doing a liveness flood, -traversing pointers to heap objects starting from some initial memory -regions we know to potentially contain live pointer data. Note that -this flood might potentially not find some (global) live data region -to start the flood from. If you find such, please file a bug.</p> - -<p>The liveness flood attempts to treat any properly aligned byte -sequences as pointers to heap objects and thinks that it found a good -pointer whenever the current heap memory map contains an object with -the address whose byte representation we found. Some pointers into -not-at-start of object will also work here.</p> - -<p>As a result of this simple approach, it's possible (though -unlikely) for the flood to be inexact and occasionally result in -leaked objects being erroneously determined to be live. For instance, -random bit patterns can happen to look like pointers to leaked heap -objects. More likely, stale pointer data not corresponding to any -live program variables can be still present in memory regions, -especially in thread stacks. For instance, depending on how the local -<code>malloc</code> is implemented, it may reuse a heap object -address:</p> -<pre> - char* p = new char[1]; // new might return 0x80000000, say. - delete p; - new char[1]; // new might return 0x80000000 again - // This last new is a leak, but doesn't seem it: p looks like it points to it -</pre> - -<p>In other words, imprecisions in the liveness flood mean that for -any heap leak check we might miss some memory leaks. This means that -for local leak checks, we might report a memory leak in the local -area, even though the leak actually happened before the -<code>HeapLeakChecker</code> object was constructed. Note that for -whole-program checks, a leak report <i>does</i> always correspond to a -real leak (since there's no "before" to have created a false-live -object).</p> - -<p>While this liveness flood approach is not very portable and not -100% accurate, it works in most cases and saves us from writing a lot -of explicit clean up code and other hassles when dealing with thread -data.</p> - - -<h3>Visualizing Leak with <code>pprof</code></h3> - -<p> -The heap checker automatically prints basic leak info with stack traces of -leaked objects' allocation sites, as well as a pprof command line that can be -used to visualize the call-graph involved in these allocations. -The latter can be much more useful for a human -to see where/why the leaks happened, especially if the leaks are numerous. -</p> - -<h3>Leak-checking and Threads</h3> - -<p>At the time of HeapLeakChecker's construction and during -<code>NoLeaks()</code> calls, we grab a lock -and then pause all other threads so other threads do not interfere -with recording or analyzing the state of the heap.</p> - -<p>In general, leak checking works correctly in the presence of -threads. However, thread stack data liveness determination (via -<code>base/thread_lister.h</code>) does not work when the program is -running under GDB, because the ptrace functionality needed for finding -threads is already hooked to by GDB. Conversely, leak checker's -ptrace attempts might also interfere with GDB. As a result, GDB can -result in potentially false leak reports. For this reason, the -heap-checker turns itself off when running under GDB.</p> - -<p>Also, <code>thread_lister</code> only works for Linux pthreads; -leak checking is unlikely to handle other thread implementations -correctly.</p> - -<p>As mentioned in the discussion of liveness flooding, thread-stack -liveness determination might mis-classify as reachable objects that -very recently became unreachable (leaked). This can happen when the -pointers to now-logically-unreachable objects are present in the -active thread stack frame. In other words, trivial code like the -following might not produce the expected leak checking outcome -depending on how the compiled code works with the stack:</p> -<pre> - int* foo = new int [20]; - HeapLeakChecker check("a_check"); - foo = NULL; - // May fail to trigger. - if (!heap_checker.NoLeaks()) assert(NULL == "heap memory leak"); -</pre> - - -<hr> -<address>Maxim Lifantsev<br> -<!-- Created: Tue Dec 19 10:43:14 PST 2000 --> -<!-- hhmts start --> -Last modified: Fri Jul 13 13:14:33 PDT 2007 -<!-- hhmts end --> -</address> -</body> -</html>
http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/heapprofile.html ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/heapprofile.html b/third_party/gperftools/doc/heapprofile.html deleted file mode 100644 index d2ff52c..0000000 --- a/third_party/gperftools/doc/heapprofile.html +++ /dev/null @@ -1,382 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<HTML> - -<HEAD> - <link rel="stylesheet" href="designstyle.css"> - <title>Gperftools Heap Profiler</title> -</HEAD> - -<BODY> - -<p align=right> - <i>Last modified - <script type=text/javascript> - var lm = new Date(document.lastModified); - document.write(lm.toDateString()); - </script></i> -</p> - -<p>This is the heap profiler we use at Google, to explore how C++ -programs manage memory. This facility can be useful for</p> -<ul> - <li> Figuring out what is in the program heap at any given time - <li> Locating memory leaks - <li> Finding places that do a lot of allocation -</ul> - -<p>The profiling system instruments all allocations and frees. It -keeps track of various pieces of information per allocation site. An -allocation site is defined as the active stack trace at the call to -<code>malloc</code>, <code>calloc</code>, <code>realloc</code>, or, -<code>new</code>.</p> - -<p>There are three parts to using it: linking the library into an -application, running the code, and analyzing the output.</p> - - -<h1>Linking in the Library</h1> - -<p>To install the heap profiler into your executable, add -<code>-ltcmalloc</code> to the link-time step for your executable. -Also, while we don't necessarily recommend this form of usage, it's -possible to add in the profiler at run-time using -<code>LD_PRELOAD</code>: -<pre>% env LD_PRELOAD="/usr/lib/libtcmalloc.so" <binary></pre> - -<p>This does <i>not</i> turn on heap profiling; it just inserts the -code. For that reason, it's practical to just always link -<code>-ltcmalloc</code> into a binary while developing; that's what we -do at Google. (However, since any user can turn on the profiler by -setting an environment variable, it's not necessarily recommended to -install profiler-linked binaries into a production, running -system.) Note that if you wish to use the heap profiler, you must -also use the tcmalloc memory-allocation library. There is no way -currently to use the heap profiler separate from tcmalloc.</p> - - -<h1>Running the Code</h1> - -<p>There are several alternatives to actually turn on heap profiling -for a given run of an executable:</p> - -<ol> - <li> <p>Define the environment variable HEAPPROFILE to the filename - to dump the profile to. For instance, to profile - <code>/usr/local/bin/my_binary_compiled_with_tcmalloc</code>:</p> - <pre>% env HEAPPROFILE=/tmp/mybin.hprof /usr/local/bin/my_binary_compiled_with_tcmalloc</pre> - <li> <p>In your code, bracket the code you want profiled in calls to - <code>HeapProfilerStart()</code> and <code>HeapProfilerStop()</code>. - (These functions are declared in <code><gperftools/heap-profiler.h></code>.) - <code>HeapProfilerStart()</code> will take the - profile-filename-prefix as an argument. Then, as often as - you'd like before calling <code>HeapProfilerStop()</code>, you - can use <code>HeapProfilerDump()</code> or - <code>GetHeapProfile()</code> to examine the profile. In case - it's useful, <code>IsHeapProfilerRunning()</code> will tell you - whether you've already called HeapProfilerStart() or not.</p> -</ol> - - -<p>For security reasons, heap profiling will not write to a file -- -and is thus not usable -- for setuid programs.</p> - -<H2>Modifying Runtime Behavior</H2> - -<p>You can more finely control the behavior of the heap profiler via -environment variables.</p> - -<table frame=box rules=sides cellpadding=5 width=100%> - -<tr valign=top> - <td><code>HEAP_PROFILE_ALLOCATION_INTERVAL</code></td> - <td>default: 1073741824 (1 Gb)</td> - <td> - Dump heap profiling information each time the specified number of - bytes has been allocated by the program. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_PROFILE_INUSE_INTERVAL</code></td> - <td>default: 104857600 (100 Mb)</td> - <td> - Dump heap profiling information whenever the high-water memory - usage mark increases by the specified number of bytes. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_PROFILE_TIME_INTERVAL</code></td> - <td>default: 104857600 (100 Mb)</td> - <td> - Dump heap profiling information each time the specified - number of seconds has elapsed. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_PROFILE_MMAP</code></td> - <td>default: false</td> - <td> - Profile <code>mmap</code>, <code>mremap</code> and <code>sbrk</code> - calls in addition - to <code>malloc</code>, <code>calloc</code>, <code>realloc</code>, - and <code>new</code>. <b>NOTE:</b> this causes the profiler to - profile calls internal to tcmalloc, since tcmalloc and friends use - mmap and sbrk internally for allocations. One partial solution is - to filter these allocations out when running <code>pprof</code>, - with something like - <code>pprof --ignore='DoAllocWithArena|SbrkSysAllocator::Alloc|MmapSysAllocator::Alloc</code>. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_PROFILE_ONLY_MMAP</code></td> - <td>default: false</td> - <td> - Only profile <code>mmap</code>, <code>mremap</code>, and <code>sbrk</code> - calls; do not profile - <code>malloc</code>, <code>calloc</code>, <code>realloc</code>, - or <code>new</code>. - </td> -</tr> - -<tr valign=top> - <td><code>HEAP_PROFILE_MMAP_LOG</code></td> - <td>default: false</td> - <td> - Log <code>mmap</code>/<code>munmap</code> calls. - </td> -</tr> - -</table> - -<H2>Checking for Leaks</H2> - -<p>You can use the heap profiler to manually check for leaks, for -instance by reading the profiler output and looking for large -allocations. However, for that task, it's easier to use the <A -HREF="heap_checker.html">automatic heap-checking facility</A> built -into tcmalloc.</p> - - -<h1><a name="pprof">Analyzing the Output</a></h1> - -<p>If heap-profiling is turned on in a program, the program will -periodically write profiles to the filesystem. The sequence of -profiles will be named:</p> -<pre> - <prefix>.0000.heap - <prefix>.0001.heap - <prefix>.0002.heap - ... -</pre> -<p>where <code><prefix></code> is the filename-prefix supplied -when running the code (e.g. via the <code>HEAPPROFILE</code> -environment variable). Note that if the supplied prefix -does not start with a <code>/</code>, the profile files will be -written to the program's working directory.</p> - -<p>The profile output can be viewed by passing it to the -<code>pprof</code> tool -- the same tool that's used to analyze <A -HREF="cpuprofile.html">CPU profiles</A>. - -<p>Here are some examples. These examples assume the binary is named -<code>gfs_master</code>, and a sequence of heap profile files can be -found in files named:</p> -<pre> - /tmp/profile.0001.heap - /tmp/profile.0002.heap - ... - /tmp/profile.0100.heap -</pre> - -<h3>Why is a process so big</h3> - -<pre> - % pprof --gv gfs_master /tmp/profile.0100.heap -</pre> - -<p>This command will pop-up a <code>gv</code> window that displays -the profile information as a directed graph. Here is a portion -of the resulting output:</p> - -<p><center> -<img src="heap-example1.png"> -</center></p> - -A few explanations: -<ul> -<li> <code>GFS_MasterChunk::AddServer</code> accounts for 255.6 MB - of the live memory, which is 25% of the total live memory. -<li> <code>GFS_MasterChunkTable::UpdateState</code> is directly - accountable for 176.2 MB of the live memory (i.e., it directly - allocated 176.2 MB that has not been freed yet). Furthermore, - it and its callees are responsible for 729.9 MB. The - labels on the outgoing edges give a good indication of the - amount allocated by each callee. -</ul> - -<h3>Comparing Profiles</h3> - -<p>You often want to skip allocations during the initialization phase -of a program so you can find gradual memory leaks. One simple way to -do this is to compare two profiles -- both collected after the program -has been running for a while. Specify the name of the first profile -using the <code>--base</code> option. For example:</p> -<pre> - % pprof --base=/tmp/profile.0004.heap gfs_master /tmp/profile.0100.heap -</pre> - -<p>The memory-usage in <code>/tmp/profile.0004.heap</code> will be -subtracted from the memory-usage in -<code>/tmp/profile.0100.heap</code> and the result will be -displayed.</p> - -<h3>Text display</h3> - -<pre> -% pprof --text gfs_master /tmp/profile.0100.heap - 255.6 24.7% 24.7% 255.6 24.7% GFS_MasterChunk::AddServer - 184.6 17.8% 42.5% 298.8 28.8% GFS_MasterChunkTable::Create - 176.2 17.0% 59.5% 729.9 70.5% GFS_MasterChunkTable::UpdateState - 169.8 16.4% 75.9% 169.8 16.4% PendingClone::PendingClone - 76.3 7.4% 83.3% 76.3 7.4% __default_alloc_template::_S_chunk_alloc - 49.5 4.8% 88.0% 49.5 4.8% hashtable::resize - ... -</pre> - -<p> -<ul> - <li> The first column contains the direct memory use in MB. - <li> The fourth column contains memory use by the procedure - and all of its callees. - <li> The second and fifth columns are just percentage - representations of the numbers in the first and fourth columns. - <li> The third column is a cumulative sum of the second column - (i.e., the <code>k</code>th entry in the third column is the - sum of the first <code>k</code> entries in the second column.) -</ul> - -<h3>Ignoring or focusing on specific regions</h3> - -<p>The following command will give a graphical display of a subset of -the call-graph. Only paths in the call-graph that match the regular -expression <code>DataBuffer</code> are included:</p> -<pre> -% pprof --gv --focus=DataBuffer gfs_master /tmp/profile.0100.heap -</pre> - -<p>Similarly, the following command will omit all paths subset of the -call-graph. All paths in the call-graph that match the regular -expression <code>DataBuffer</code> are discarded:</p> -<pre> -% pprof --gv --ignore=DataBuffer gfs_master /tmp/profile.0100.heap -</pre> - -<h3>Total allocations + object-level information</h3> - -<p>All of the previous examples have displayed the amount of in-use -space. I.e., the number of bytes that have been allocated but not -freed. You can also get other types of information by supplying a -flag to <code>pprof</code>:</p> - -<center> -<table frame=box rules=sides cellpadding=5 width=100%> - -<tr valign=top> - <td><code>--inuse_space</code></td> - <td> - Display the number of in-use megabytes (i.e. space that has - been allocated but not freed). This is the default. - </td> -</tr> - -<tr valign=top> - <td><code>--inuse_objects</code></td> - <td> - Display the number of in-use objects (i.e. number of - objects that have been allocated but not freed). - </td> -</tr> - -<tr valign=top> - <td><code>--alloc_space</code></td> - <td> - Display the number of allocated megabytes. This includes - the space that has since been de-allocated. Use this - if you want to find the main allocation sites in the - program. - </td> -</tr> - -<tr valign=top> - <td><code>--alloc_objects</code></td> - <td> - Display the number of allocated objects. This includes - the objects that have since been de-allocated. Use this - if you want to find the main allocation sites in the - program. - </td> - -</table> -</center> - - -<h3>Interactive mode</a></h3> - -<p>By default -- if you don't specify any flags to the contrary -- -pprof runs in interactive mode. At the <code>(pprof)</code> prompt, -you can run many of the commands described above. You can type -<code>help</code> for a list of what commands are available in -interactive mode.</p> - - -<h1>Caveats</h1> - -<ul> - <li> Heap profiling requires the use of libtcmalloc. This - requirement may be removed in a future version of the heap - profiler, and the heap profiler separated out into its own - library. - - <li> If the program linked in a library that was not compiled - with enough symbolic information, all samples associated - with the library may be charged to the last symbol found - in the program before the library. This will artificially - inflate the count for that symbol. - - <li> If you run the program on one machine, and profile it on - another, and the shared libraries are different on the two - machines, the profiling output may be confusing: samples that - fall within the shared libaries may be assigned to arbitrary - procedures. - - <li> Several libraries, such as some STL implementations, do their - own memory management. This may cause strange profiling - results. We have code in libtcmalloc to cause STL to use - tcmalloc for memory management (which in our tests is better - than STL's internal management), though it only works for some - STL implementations. - - <li> If your program forks, the children will also be profiled - (since they inherit the same HEAPPROFILE setting). Each - process is profiled separately; to distinguish the child - profiles from the parent profile and from each other, all - children will have their process-id attached to the HEAPPROFILE - name. - - <li> Due to a hack we make to work around a possible gcc bug, your - profiles may end up named strangely if the first character of - your HEAPPROFILE variable has ascii value greater than 127. - This should be exceedingly rare, but if you need to use such a - name, just set prepend <code>./</code> to your filename: - <code>HEAPPROFILE=./Ägypten</code>. -</ul> - -<hr> -<address>Sanjay Ghemawat -<!-- Created: Tue Dec 19 10:43:14 PST 2000 --> -</address> -</body> -</html> http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/index.html ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/index.html b/third_party/gperftools/doc/index.html deleted file mode 100644 index 7b93ed3..0000000 --- a/third_party/gperftools/doc/index.html +++ /dev/null @@ -1,20 +0,0 @@ -<HTML> - -<HEAD> -<title>Gperftools</title> -</HEAD> - -<BODY> -<ul> - <li> <A HREF="tcmalloc.html">thread-caching malloc</A> - <li> <A HREF="heap_checker.html">heap-checking using tcmalloc</A> - <li> <A HREF="heapprofile.html">heap-profiling using tcmalloc</A> - <li> <A HREF="cpuprofile.html">CPU profiler</A> -</ul> - -<hr> -Last modified: Thu Feb 2 14:40:47 PST 2012 - -</BODY> - -</HTML> http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/overview.dot ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/overview.dot b/third_party/gperftools/doc/overview.dot deleted file mode 100644 index 9966f56..0000000 --- a/third_party/gperftools/doc/overview.dot +++ /dev/null @@ -1,15 +0,0 @@ -digraph Overview { -node [shape = box] - -{rank=same -T1 [label="Thread Cache"] -Tsep [label="...", shape=plaintext] -Tn [label="Thread Cache"] -T1 -> Tsep -> Tn [style=invis] -} - -C [label="Central\nHeap"] -T1 -> C [dir=both] -Tn -> C [dir=both] - -} http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/overview.gif ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/overview.gif b/third_party/gperftools/doc/overview.gif deleted file mode 100644 index 43828da..0000000 Binary files a/third_party/gperftools/doc/overview.gif and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pageheap.dot ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pageheap.dot b/third_party/gperftools/doc/pageheap.dot deleted file mode 100644 index 82e5fd5..0000000 --- a/third_party/gperftools/doc/pageheap.dot +++ /dev/null @@ -1,29 +0,0 @@ -digraph PageHeap { -rankdir=LR -node [shape=box, width=0.3, height=0.3] -nodesep=.05 - -heap [shape=record, height=3, label="<f0>1 page|<f1>2 pages|<f2>3 pages|...|<f255>255 pages|<frest>rest"] -O0 [shape=record, label=""] -O1 [shape=record, label=""] -O2 [shape=record, label="{|}"] -O3 [shape=record, label="{|}"] -O4 [shape=record, label="{||}"] -O5 [shape=record, label="{||}"] -O6 [shape=record, label="{|...|}"] -O7 [shape=record, label="{|...|}"] -O8 [shape=record, label="{|.....|}"] -O9 [shape=record, label="{|.....|}"] -sep1 [shape=plaintext, label="..."] -sep2 [shape=plaintext, label="..."] -sep3 [shape=plaintext, label="..."] -sep4 [shape=plaintext, label="..."] -sep5 [shape=plaintext, label="..."] - -heap:f0 -> O0 -> O1 -> sep1 -heap:f1 -> O2 -> O3 -> sep2 -heap:f2 -> O4 -> O5 -> sep3 -heap:f255 -> O6 -> O7 -> sep4 -heap:frest -> O8 -> O9 -> sep5 - -} http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pageheap.gif ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pageheap.gif b/third_party/gperftools/doc/pageheap.gif deleted file mode 100644 index 6632981..0000000 Binary files a/third_party/gperftools/doc/pageheap.gif and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pprof-test-big.gif ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pprof-test-big.gif b/third_party/gperftools/doc/pprof-test-big.gif deleted file mode 100644 index 67a1240..0000000 Binary files a/third_party/gperftools/doc/pprof-test-big.gif and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pprof-test.gif ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pprof-test.gif b/third_party/gperftools/doc/pprof-test.gif deleted file mode 100644 index 9eeab8a..0000000 Binary files a/third_party/gperftools/doc/pprof-test.gif and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pprof-vsnprintf-big.gif ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pprof-vsnprintf-big.gif b/third_party/gperftools/doc/pprof-vsnprintf-big.gif deleted file mode 100644 index 2ab292a..0000000 Binary files a/third_party/gperftools/doc/pprof-vsnprintf-big.gif and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pprof-vsnprintf.gif ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pprof-vsnprintf.gif b/third_party/gperftools/doc/pprof-vsnprintf.gif deleted file mode 100644 index 42a8547..0000000 Binary files a/third_party/gperftools/doc/pprof-vsnprintf.gif and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pprof.1 ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pprof.1 b/third_party/gperftools/doc/pprof.1 deleted file mode 100644 index 4662281..0000000 --- a/third_party/gperftools/doc/pprof.1 +++ /dev/null @@ -1,131 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.23. -.TH PPROF "1" "February 2005" "pprof (part of gperftools)" Google -.SH NAME -pprof \- manual page for pprof (part of gperftools) -.SH SYNOPSIS -.B pprof -[\fIoptions\fR] \fI<program> <profile>\fR -.SH DESCRIPTION -.IP -Prints specified cpu- or heap-profile -.SH OPTIONS -.TP -\fB\-\-cum\fR -Sort by cumulative data -.TP -\fB\-\-base=\fR<base> -Subtract <base> from <profile> before display -.SS "Reporting Granularity:" -.TP -\fB\-\-addresses\fR -Report at address level -.TP -\fB\-\-lines\fR -Report at source line level -.TP -\fB\-\-functions\fR -Report at function level [default] -.TP -\fB\-\-files\fR -Report at source file level -.SS "Output type:" -.TP -\fB\-\-text\fR -Generate text report [default] -.TP -\fB\-\-gv\fR -Generate Postscript and display -.TP -\fB\-\-list=\fR<regexp> -Generate source listing of matching routines -.TP -\fB\-\-disasm=\fR<regexp> -Generate disassembly of matching routines -.TP -\fB\-\-dot\fR -Generate DOT file to stdout -.TP -\fB\-\-ps\fR -Generate Postcript to stdout -.TP -\fB\-\-pdf\fR -Generate PDF to stdout -.TP -\fB\-\-gif\fR -Generate GIF to stdout -.SS "Heap-Profile Options:" -.TP -\fB\-\-inuse_space\fR -Display in-use (mega)bytes [default] -.TP -\fB\-\-inuse_objects\fR -Display in-use objects -.TP -\fB\-\-alloc_space\fR -Display allocated (mega)bytes -.TP -\fB\-\-alloc_objects\fR -Display allocated objects -.TP -\fB\-\-show_bytes\fR -Display space in bytes -.TP -\fB\-\-drop_negative\fR -Ignore negaive differences -.SS "Call-graph Options:" -.TP -\fB\-\-nodecount=\fR<n> -Show at most so many nodes [default=80] -.TP -\fB\-\-nodefraction=\fR<f> -Hide nodes below <f>*total [default=.005] -.TP -\fB\-\-edgefraction=\fR<f> -Hide edges below <f>*total [default=.001] -.TP -\fB\-\-focus=\fR<regexp> -Focus on nodes matching <regexp> -.TP -\fB\-\-ignore=\fR<regexp> -Ignore nodes matching <regexp> -.TP -\fB\-\-scale=\fR<n> -Set GV scaling [default=0] -.SH EXAMPLES - -pprof /bin/ls ls.prof -.IP -Outputs one line per procedure -.PP -pprof \fB\-\-gv\fR /bin/ls ls.prof -.IP -Displays annotated call-graph via 'gv' -.PP -pprof \fB\-\-gv\fR \fB\-\-focus\fR=\fIMutex\fR /bin/ls ls.prof -.IP -Restricts to code paths including a .*Mutex.* entry -.PP -pprof \fB\-\-gv\fR \fB\-\-focus\fR=\fIMutex\fR \fB\-\-ignore\fR=\fIstring\fR /bin/ls ls.prof -.IP -Code paths including Mutex but not string -.PP -pprof \fB\-\-list\fR=\fIgetdir\fR /bin/ls ls.prof -.IP -Dissassembly (with per-line annotations) for getdir() -.PP -pprof \fB\-\-disasm\fR=\fIgetdir\fR /bin/ls ls.prof -.IP -Dissassembly (with per-PC annotations) for getdir() -.SH COPYRIGHT -Copyright \(co 2005 Google Inc. -.SH "SEE ALSO" -Further documentation for -.B pprof -is maintained as a web page called -.B cpu_profiler.html -and is likely installed at one of the following locations: -.IP -.B /usr/share/gperftools/cpu_profiler.html -.br -.B /usr/local/share/gperftools/cpu_profiler.html -.PP http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pprof.see_also ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pprof.see_also b/third_party/gperftools/doc/pprof.see_also deleted file mode 100644 index f2caf52..0000000 --- a/third_party/gperftools/doc/pprof.see_also +++ /dev/null @@ -1,11 +0,0 @@ -[see also] -Further documentation for -.B pprof -is maintained as a web page called -.B cpu_profiler.html -and is likely installed at one of the following locations: -.IP -.B /usr/share/gperftools/cpu_profiler.html -.br -.B /usr/local/share/gperftools/cpu_profiler.html -.PP http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/pprof_remote_servers.html ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/pprof_remote_servers.html b/third_party/gperftools/doc/pprof_remote_servers.html deleted file mode 100644 index e30e612..0000000 --- a/third_party/gperftools/doc/pprof_remote_servers.html +++ /dev/null @@ -1,260 +0,0 @@ -<HTML> - -<HEAD> -<title>pprof and Remote Servers</title> -</HEAD> - -<BODY> - -<h1><code>pprof</code> and Remote Servers</h1> - -<p>In mid-2006, we added an experimental facility to <A -HREF="cpu_profiler.html">pprof</A>, the tool that analyzes CPU and -heap profiles. This facility allows you to collect profile -information from running applications. It makes it easy to collect -profile information without having to stop the program first, and -without having to log into the machine where the application is -running. This is meant to be used on webservers, but will work on any -application that can be modified to accept TCP connections on a port -of its choosing, and to respond to HTTP requests on that port.</p> - -<p>We do not currently have infrastructure, such as apache modules, -that you can pop into a webserver or other application to get the -necessary functionality "for free." However, it's easy to generate -the necessary data, which should allow the interested developer to add -the necessary support into his or her applications.</p> - -<p>To use <code>pprof</code> in this experimental "server" mode, you -give the script a host and port it should query, replacing the normal -commandline arguments of application + profile file:</p> -<pre> - % pprof internalweb.mycompany.com:80 -</pre> - -<p>The host must be listening on that port, and be able to accept HTTP/1.0 -requests -- sent via <code>wget</code> and <code>curl</code> -- for -several urls. The following sections list the urls that -<code>pprof</code> can send, and the responses it expects in -return.</p> - -<p>Here are examples that pprof will recognize, when you give them -on the commandline, are urls. In general, you -specify the host and a port (the port-number is required), and put -the service-name at the end of the url.:</p> -<blockquote><pre> -http://myhost:80/pprof/heap # retrieves a heap profile -http://myhost:8008/pprof/profile # retrieves a CPU profile -http://myhost:80 # retrieves a CPU profile (the default) -http://myhost:8080/ # retrieves a CPU profile (the default) -myhost:8088/pprof/growth # "http://"; is optional, but port is not -http://myhost:80/myservice/pprof/heap # /pprof/heap just has to come at the end -http://myhost:80/pprof/pmuprofile # CPU profile using performance counters -</pre></blockquote> - -<h2> <code><b>/pprof/heap</b></code> </h2> - -<p><code>pprof</code> asks for the url <code>/pprof/heap</code> to -get heap information. The actual url is controlled via the variable -<code>HEAP_PAGE</code> in the <code>pprof</code> script, so you -can change it if you'd like.</p> - -<p>There are two ways to get this data. The first is to call</p> -<pre> - MallocExtension::instance()->GetHeapSample(&output); -</pre> -<p>and have the server send <code>output</code> back as an HTTP -response to <code>pprof</code>. <code>MallocExtension</code> is -defined in the header file <code>gperftools/malloc_extension.h</code>.</p> - -<p>Note this will only only work if the binary is being run with -sampling turned on (which is not the default). To do this, set the -environment variable <code>TCMALLOC_SAMPLE_PARAMETER</code> to a -positive value, such as 524288, before running.</p> - -<p>The other way is to call <code>HeapProfileStart(filename)</code> -(from <code>heap-profiler.h</code>), continue to do work, and then, -some number of seconds later, call <code>GetHeapProfile()</code> -(followed by <code>HeapProfilerStop()</code>). The server can send -the output of <code>GetHeapProfile</code> back as the HTTP response to -pprof. (Note you must <code>free()</code> this data after using it.) -This is similar to how <A HREF="#profile">profile requests</A> are -handled, below. This technique does not require the application to -run with sampling turned on.</p> - -<p>Here's an example of what the output should look like:</p> -<pre> -heap profile: 1923: 127923432 [ 1923: 127923432] @ heap_v2/524288 - 1: 312 [ 1: 312] @ 0x2aaaabaf5ccc 0x2aaaaba4cd2c 0x2aaaac08c09a - 928: 122586016 [ 928: 122586016] @ 0x2aaaabaf682c 0x400680 0x400bdd 0x2aaaab1c368a 0x2aaaab1c8f77 0x2aaaab1c0396 0x2aaaab1c86ed 0x4007ff 0x2aaaaca62afa - 1: 16 [ 1: 16] @ 0x2aaaabaf5ccc 0x2aaaabb04bac 0x2aaaabc1b262 0x2aaaabc21496 0x2aaaabc214bb -[...] -</pre> - - -<p> Older code may produce "version 1" heap profiles which look like this:<p/> -<pre> -heap profile: 14933: 791700132 [ 14933: 791700132] @ heap - 1: 848688 [ 1: 848688] @ 0xa4b142 0x7f5bfc 0x87065e 0x4056e9 0x4125f8 0x42b4f1 0x45b1ba 0x463248 0x460871 0x45cb7c 0x5f1744 0x607cee 0x5f4a5e 0x40080f 0x2aaaabad7afa - 1: 1048576 [ 1: 1048576] @ 0xa4a9b2 0x7fd025 0x4ca6d8 0x4ca814 0x4caa88 0x2aaaab104cf0 0x404e20 0x4125f8 0x42b4f1 0x45b1ba 0x463248 0x460871 0x45cb7c 0x5f1744 0x607cee 0x5f4a5e 0x40080f 0x2aaaabad7afa - 2942: 388629374 [ 2942: 388629374] @ 0xa4b142 0x4006a0 0x400bed 0x5f0cfa 0x5f1744 0x607cee 0x5f4a5e 0x40080f 0x2aaaabad7afa -[...] -</pre> -<p>pprof accepts both old and new heap profiles and automatically -detects which one you are using.</p> - -<h2> <code><b>/pprof/growth</b></code> </h2> - -<p><code>pprof</code> asks for the url <code>/pprof/growth</code> to -get heap-profiling delta (growth) information. The actual url is -controlled via the variable <code>GROWTH_PAGE</code> in the -<code>pprof</code> script, so you can change it if you'd like.</p> - -<p>The server should respond by calling</p> -<pre> - MallocExtension::instance()->GetHeapGrowthStacks(&output); -</pre> -<p>and sending <code>output</code> back as an HTTP response to -<code>pprof</code>. <code>MallocExtension</code> is defined in the -header file <code>gperftools/malloc_extension.h</code>.</p> - -<p>Here's an example, from an actual Google webserver, of what the -output should look like:</p> -<pre> -heap profile: 741: 812122112 [ 741: 812122112] @ growth - 1: 1572864 [ 1: 1572864] @ 0x87da564 0x87db8a3 0x84787a4 0x846e851 0x836d12f 0x834cd1c 0x8349ba5 0x10a3177 0x8349961 - 1: 1048576 [ 1: 1048576] @ 0x87d92e8 0x87d9213 0x87d9178 0x87d94d3 0x87da9da 0x8a364ff 0x8a437e7 0x8ab7d23 0x8ab7da9 0x8ac7454 0x8348465 0x10a3161 0x8349961 -[...] -</pre> - - -<h2> <A NAME="profile"><code><b>/pprof/profile</b></code></A> </h2> - -<p><code>pprof</code> asks for the url -<code>/pprof/profile?seconds=XX</code> to get cpu-profiling -information. The actual url is controlled via the variable -<code>PROFILE_PAGE</code> in the <code>pprof</code> script, so you can -change it if you'd like.</p> - -<p>The server should respond by calling -<code>ProfilerStart(filename)</code>, continuing to do its work, and -then, XX seconds later, calling <code>ProfilerStop()</code>. (These -functions are declared in <code>gperftools/profiler.h</code>.) The -application is responsible for picking a unique filename for -<code>ProfilerStart()</code>. After calling -<code>ProfilerStop()</code>, the server should read the contents of -<code>filename</code> and send them back as an HTTP response to -<code>pprof</code>.</p> - -<p>Obviously, to get useful profile information the application must -continue to run in the XX seconds that the profiler is running. Thus, -the profile start-stop calls should be done in a separate thread, or -be otherwise non-blocking.</p> - -<p>The profiler output file is binary, but near the end of it, it -should have lines of text somewhat like this:</p> -<pre> -01016000-01017000 rw-p 00015000 03:01 59314 /lib/ld-2.2.2.so -</pre> - -<h2> <code><b>/pprof/pmuprofile</b></code> </h2> - -<code>pprof</code> asks for a url of the form -<code>/pprof/pmuprofile?event=hw_event:unit_mask&period=nnn&seconds=xxx</code> -to get cpu-profiling information. The actual url is controlled via the variable -<code>PMUPROFILE_PAGE</code> in the <code>pprof</code> script, so you can -change it if you'd like.</p> - -<p> -This is similar to pprof, but is meant to be used with your CPU's hardware -performance counters. The server could be implemented on top of a library -such as <a href="http://perfmon2.sourceforge.net/";> -<code>libpfm</code></a>. It should collect a sample every nnn occurrences -of the event and stop the sampling after xxx seconds. Much of the code -for <code>/pprof/profile</code> can be reused for this purpose. -</p> - -<p>The server side routines (the equivalent of -ProfilerStart/ProfilerStart) are not available as part of perftools, -so this URL is unlikely to be that useful.</p> - -<h2> <code><b>/pprof/contention</b></code> </h2> - -<p>This is intended to be able to profile (thread) lock contention in -addition to CPU and memory use. It's not yet usable.</p> - - -<h2> <code><b>/pprof/cmdline</b></code> </h2> - -<p><code>pprof</code> asks for the url <code>/pprof/cmdline</code> to -figure out what application it's profiling. The actual url is -controlled via the variable <code>PROGRAM_NAME_PAGE</code> in the -<code>pprof</code> script, so you can change it if you'd like.</p> - -<p>The server should respond by reading the contents of -<code>/proc/self/cmdline</code>, converting all internal NUL (\0) -characters to newlines, and sending the result back as an HTTP -response to <code>pprof</code>.</p> - -<p>Here's an example return value:<p> -<pre> -/root/server/custom_webserver -80 ---configfile=/root/server/ws.config -</pre> - - -<h2> <code><b>/pprof/symbol</b></code> </h2> - -<p><code>pprof</code> asks for the url <code>/pprof/symbol</code> to -map from hex addresses to variable names. The actual url is -controlled via the variable <code>SYMBOL_PAGE</code> in the -<code>pprof</code> script, so you can change it if you'd like.</p> - -<p>When the server receives a GET request for -<code>/pprof/symbol</code>, it should return a line formatted like -so:</p> -<pre> - num_symbols: ### -</pre> -<p>where <code>###</code> is the number of symbols found in the -binary. (For now, the only important distinction is whether the value -is 0, which it is for executables that lack debug information, or -not-0).</p> - -<p>This is perhaps the hardest request to write code for, because in -addition to the GET request for this url, the server must accept POST -requests. This means that after the HTTP headers, pprof will pass in -a list of hex addresses connected by <code>+</code>, like so:</p> -<pre> - curl -d '0x0824d061+0x0824d1cf' http://remote_host:80/pprof/symbol -</pre> - -<p>The server should read the POST data, which will be in one line, -and for each hex value, should write one line of output to the output -stream, like so:</p> -<pre> -<hex address><tab><function name> -</pre> -<p>For instance:</p> -<pre> -0x08b2dabd _Update -</pre> - -<p>The other reason this is the most difficult request to implement, -is that the application will have to figure out for itself how to map -from address to function name. One possibility is to run <code>nm -C --n <program name></code> to get the mappings at -program-compile-time. Another, at least on Linux, is to call out to -addr2line for every <code>pprof/symbol</code> call, for instance -<code>addr2line -Cfse /proc/<getpid>/exe 0x12345678 0x876543210</code> -(presumably with some caching!)</p> - -<p><code>pprof</code> itself does just this for local profiles (not -ones that talk to remote servers); look at the subroutine -<code>GetProcedureBoundaries</code>.</p> - - -<hr> -Last modified: Mon Jun 12 21:30:14 PDT 2006 -</body> -</html> http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/spanmap.dot ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/spanmap.dot b/third_party/gperftools/doc/spanmap.dot deleted file mode 100644 index 3cb42ab..0000000 --- a/third_party/gperftools/doc/spanmap.dot +++ /dev/null @@ -1,22 +0,0 @@ -digraph SpanMap { -node [shape=box, width=0.3, height=0.3] -nodesep=.05 - -map [shape=record, width=6, label="<f0>|<f1>|<f2>|<f3>|<f4>|<f5>|<f6>|<f7>|<f8>|<f9>|<f10>"] -S0 [label="a"] -S1 [label="b"] -S2 [label="c"] -S3 [label="d"] -map:f0 -> S0 -map:f1 -> S0 -map:f2 -> S1 -map:f3 -> S2 -map:f4 -> S2 -map:f5 -> S2 -map:f6 -> S2 -map:f7 -> S2 -map:f8 -> S3 -map:f9 -> S3 -map:f10 -> S3 - -} http://git-wip-us.apache.org/repos/asf/incubator-quickstep/blob/9661f956/third_party/gperftools/doc/spanmap.gif ---------------------------------------------------------------------- diff --git a/third_party/gperftools/doc/spanmap.gif b/third_party/gperftools/doc/spanmap.gif deleted file mode 100644 index a0627f6..0000000 Binary files a/third_party/gperftools/doc/spanmap.gif and /dev/null differ
