From: Nicholas Nethercote Date: Tue, 27 Nov 2007 21:29:33 +0000 (+0000) Subject: Massif doc fixes, mostly from Julian. X-Git-Tag: svn/VALGRIND_3_3_0~50 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3387ddba10ddd1148d0c83b5d990986bd1bdc6f9;p=thirdparty%2Fvalgrind.git Massif doc fixes, mostly from Julian. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@7242 --- diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml index 8cd7bd7298..934fbca96e 100644 --- a/massif/docs/ms-manual.xml +++ b/massif/docs/ms-manual.xml @@ -20,7 +20,7 @@ command line. Heap profiling Massif is a heap profiler. It measures how much heap memory your -program uses. This includes both the useful space, as well as extra bytes +program uses. This includes both the useful space, and the extra bytes allocated for book-keeping purposes and alignment purposes. It can also measure the size of your program's stack(s), although it does not do so by default. @@ -85,8 +85,8 @@ the ms_print script. If the output file's name is the program's execution, and (b) detailed information about the responsible allocation sites at various points in the program, including the point of peak memory allocation. The use of a separate script for presenting the -results is deliberate; it separates the data gathering from its -presentation, and means that new ones of presenting the data can be added in +results is deliberate: it separates the data gathering from its +presentation, and means that new methods of presenting the data can be added in the future. @@ -189,8 +189,8 @@ Number of snapshots: 25 Why is most of the graph empty, with only a couple of bars at the very end? By default, Massif uses "instructions executed" as the unit of time. -For very short-run programs such as the example, most of the execution -instructions involved the loading and dynamic linking of the program. The +For very short-run programs such as the example, most of the executed +instructions involve the loading and dynamic linking of the program. The execution of main (and thus the heap allocations) only occur at the very end. For a short-running program like this, we can use the --time-unit=B option @@ -251,7 +251,7 @@ shortly. Detailed snapshots are represented in the graph by bars consisting of '@' and ',' characters. The text at the bottom show that 3 detailed snapshots were taken for this program (snapshots 9, 14 and 24). By default, every 10th snapshot is detailed, although this can be changed via the ---detailed-freqoption. +--detailed-freq option. Finally, there is at most one peak snapshot. The peak snapshot is detailed, and records the point where memory consumption @@ -262,7 +262,7 @@ true peak. See the description of the details.) The peak snapshot is represented in the graph by a bar consisting of '#' and ',' characters. The text at the bottom show that snapshot 14 was the peak. Note that for tiny programs that never deallocate heap memory, -Massif will record a peak snapshot. +Massif will not record a peak snapshot. The following graph is from an execution of Konqueror, the KDE web browser. It shows what graphs for larger programs look like. @@ -353,7 +353,7 @@ a small amount of information is recorded for each one: larger number. By default, if N bytes are asked for, Massif rounds N up to the nearest multiple of 8 that is equal to or greater than N. This is typical behaviour for allocators, and is required to ensure that elements - within the block are suitable aligned. The rounding size can be changed + within the block are suitably aligned. The rounding size can be changed with the --alignment option, although it cannot be less than 8, and must be a power of two. @@ -455,12 +455,14 @@ how and why all heap memory was allocated. The 00.00% entry represents the code locations for which memory was allocated and then freed (line 20 in this case, the memory for which was freed on line 28). However, no code location details are given for this -entry; by default, Massif/ms_print only show the details for code locations -responsible for more than 1% of useful memory bytes. The entries that do -not meet this threshold are aggregated. This avoids filling up the output -with large numbers of unimportant entries. This threshold can be changed -with the --threshold option of both Massif -and ms_print. +entry; by default, Massif only records the details for code locations +responsible for more than 1% of useful memory bytes, and ms_print likewise +only prints the details for code locations responsible for more than 1%. +The entries that do not meet this threshold are aggregated. This avoids +filling up the output with large numbers of unimportant entries. The +thresholds threshold can be changed with the +--threshold option that both Massif and +ms_print support. @@ -489,7 +491,7 @@ and ms_print. - If heap profiling is on, gives the number of administrative + If heap profiling is enabled, gives the number of administrative bytes per block to use. This should be an estimate of the average, since it may vary. For example, the allocator used by glibc requires somewhere between 4 to @@ -602,11 +604,11 @@ operator new[](unsigned long, std::nothrow_t const&) The time unit used for the profiling. There are three possibilities: instructions executed (i), which is good for most - cases; real time (ms, i.e. milliseconds), which is useful sometimes; - and bytes allocated/deallocated on the heap and/or stack (B), which is - useful for very short-run programs, and for testing purposes, because - it is the most reproducible across different machines. - + cases; real (wallclock) time (ms, i.e. milliseconds), which is + sometimes useful; and bytes allocated/deallocated on the heap and/or + stack (B), which is useful for very short-run programs, and for + testing purposes, because it is the most reproducible across different + machines. @@ -642,15 +644,15 @@ operator new[](unsigned long, std::nothrow_t const&) and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core option - . See here for details. + . See for details. - + The minimum alignment (and thus size) of heap blocks.