Merge pull request #107 from bernarda78/master

Add documentation (solve #85)

src/doc/file-format.md

@@ -96,7 +96,7 @@ About `stacks` section
 The `stack` entry contain all the statistics attached to each call stacks.
 It is build linking a call stack (with functions pointers) to the stat object.
 
-For dyanmic libraries (`.so` files) this is the absolute address at runtime
+For dynamic libraries (`.so` files) this is the absolute address at runtime
 which if you want to address in the library itself removing the shift
 should be recomputed but this is not required as the `sites` section already
 has all the conversion to code locations. Consider the address more like a

src/lib/core/SegmentTracker.cpp

@@ -156,7 +156,7 @@ LeakInfo::LeakInfo(void)
 
 /*******************  FUNCTION  *********************/
 /**
- * Conver a leak info object to json.
+ * Convert a leak info object to json.
  * @param json The json state object to make the conversion.
  * @param it Reference to the object to convert.
 **/

src/lib/wrapper/AllocWrapper.cpp

@@ -20,7 +20,7 @@
 #include <malloc.h>
 //signal
 #include <signal.h>
-//intenrals
+//internals
 #include <common/Debug.hpp>
 #include <portability/OS.hpp>
 #include <portability/Mutex.hpp>

src/webview/client-files/app/js/directives.js

@@ -144,7 +144,7 @@
 						return $scope.formatValue(Math.round(value/divider),unit);
 				}
 
-				$scope.hasExlusiveValues = function() {
+				$scope.hasExclusiveValues = function() {
 					if ($scope.selectedDetails == undefined || $scope.selectedDetails.own == undefined)
 						return true;
 					else

src/webview/client-files/app/js/page-home.js

@@ -92,13 +92,13 @@ function MaltPageHome()
 			key:'totalAllocatedMemory',
 			name:'Cumulated memory allocations',
 			level: 1,
-			help:"Sum of all dyanmic memory allocation throuth malloc, calloc, realloc....",
+			help:"Sum of all dynamic memory allocation througth malloc, calloc, realloc....",
 			format: function(x) {return maltHelper.humanReadable(x,1,'B',false);}
 		},{
 			key:'allocCount',
 			name:'Allocation count',
 			level: 1,
-			help:"Total number of all dyanmic memory allocation with malloc, calloc, realloc....",
+			help:"Total number of all dynamic memory allocation with malloc, calloc, realloc....",
 			format: function(x) {return maltHelper.humanReadable(x,1,'',false);}
 		},{
 			key:'recyclingRatio',

src/webview/client-files/app/partials/help.html

@@ -17,7 +17,7 @@ <h1>Use of the GUI</h1>
 <pre>malt-webview -i malt-my_program-12589.json [-p PORT]</pre>
 
 <p>It opens a webserver on port 8080 by default so you can open it with your browser by going to <a href='http://localhost:8080'>http://localhost:8080</a>.
-If you run it remotly, you might need to forward the port through SSH by using command : </p>
+If you run it remotely, you might need to forward the port through SSH by using command : </p>
 
 <pre>ssh user@foo -L8080:localhost:8080 </pre>
 
@@ -51,7 +51,7 @@ <h2>Requested memory</h2>
 <h2>Virtual memory</h2>
 
 <p>This is the memory the memory allocator (<code>malloc</code>) has requested to the system. Here, we remind that memory management is done at page (4K segments) granularity
-by the OS. When you request an allocation of 16 bytes, the allocator must request a least 4Kb to the OS through the <code>mmap</code> system call. 
+by the OS. When you request an allocation of 16 bytes, the allocator must request a least 4Kb to the OS through the <code>mmap</code> system call.
 We can illustrate with the given code :</p>
 
 <pre>
@@ -65,15 +65,15 @@ <h2>Virtual memory</h2>
 free(a);                  //Total virtual = 0
 </pre>
 
-<p>There is no guaranty that the allocator return the virtual memory immediatly, it might keep it for latter use. In practive it appens only for small segments (upper magnitude is roughtly 128 Kb).
+<p>There is no guaranty that the allocator return the virtual memory immediately, it might keep it for latter use. In practice it happens only for small segments (upper magnitude is roughly 128 Kb).
 The virtual memory also contain all the libraries and executable code so can contain much more than the requested memory.</p>
 
-<p>Caution, in practive the virtual take in account the memory space consummed by the binaries (lib and executable) of your program. MALT remove its own memory usage from this metric.</p>
+<p>Caution, in practice the virtual take in account the memory space consumed by the binaries (lib and executable) of your program. MALT removes its own memory usage from this metric.</p>
 
 <h2>Physical memory</h2>
 
 <p>By default the operating system only allocate Virtual Memory by keeping track of the authorized memory addressed. He didn't associate any physical
-pages to those virtual segments. The first access on a virtual page generate a "page fault" to notify the OS. On page fault, the OS searh and
+pages to those virtual segments. The first access on a virtual page generates a "page fault" to notify the OS. On page fault, the OS search and
 map a physical page to the virtual one. The virtual memory give the memory requested by the user and the physical give the memory used by
 the user. Gaps between those two metrics point too large allocation compared to the memory usage.</p>
 
@@ -85,7 +85,7 @@ <h2>Physical memory</h2>
 free(a);                  //Total virtual = 0,   physical = 0
 </pre>
 
-<p>Caution, in practive the physical memory as for the virtual take in account the memory space consummed by the binaries (lib and executable) of your program. MALT remove its own memory usage from this metric.</p>
+<p>Caution, in practice the physical memory, like the virtual memory, takes into account the memory space consumed by the binaries (lib and executable) of your program. MALT removes its own memory usage from this metric.</p>
 
 <h2>Internal memory</h2>
 
@@ -96,19 +96,31 @@ <h2>About memory peaks</h2>
 <p>MALT provide two kinds of memory peaks : </p>
 
 <ul>
-	<li>Local peak : it track the maximum memor used by a given function for the wall execution.</li>
-	<li>Global peak : it track the memory used by a function at global peak time, it might be smaller than local peak as the function might use no memory when the global peak append.</li>
+	<li>Local peak : it tracks the maximum memory used by a given function for the whole execution.</li>
+	<li>Global peak : it tracks the memory used by a function at global peak time, it might be smaller than local peak as the function might use no memory when the global peak append.</li>
 </ul>
 
 <h2>About chunk lifetime</h2>
 
-Chunk lifetime correspond to the time between malloc and free. Ideally it need to be as long as possible as short lifetime linked to lot of allocation can lead to performance issues.
+<p>Chunk lifetime corresponds to the time between <code>malloc</code> and <code>free</code>. Ideally, it needs to be as long as possible, as short lifetime linked to lot of allocation can lead to performance issues.</p>
 
 <!--<h2>About fragmentation</h2>-->
 
 <h2>Allocation rates</h2>
 
-Allocation rate are related to number of allocation in a short period. It can pin point performance overhead due to operating system memory management functions.
+<p>Allocation rate are related to number of allocation in a short period. It can pinpoint performance overhead due to operating system memory management functions.</p>
+
+<h2>About counters</h2>
+
+<p>For each counter, MALT tracks two sub-metric:</p>
+
+<ul>
+    <li>Inclusive: It is the number of times <code>malloc</code> (<code>realloc</code>, <code>free</code>, ...) has been seen under this function (by looking in all call stacks and accounting if called in child functions). This is also called <code>total</code> in code. </li>
+    <li>Exclusive: It is the number of times exactly that <code>malloc</code> (<code>realloc</code>, <code>free</code>, ...) has been called in this function. This is also called <code>own</code> in code. </li>
+</ul>
+
+By default, values displayed are inclusives, i.e. it account for every allocation below it,as on the home page.
+Exclusives value are only displayed if it is relevant to the function.
 
 <h1>Thanks</h1>
 

src/webview/client-files/app/partials/memory-table.html

@@ -32,7 +32,7 @@
 			<td> [ {{formatValue(selectedDetails.total.lifetime.min,'')}} , {{formatRoundedRatio(selectedDetails.total.lifetime.sum , selectedDetails.total.lifetime.count,'')}} , {{formatValue(selectedDetails.total.lifetime.max ,'')}} ] (cycles)</td>
 		</tr>
 	</table>
-	<table class="table table-condensed table-striped table-bordered" ng-hide="hasExlusiveValues()" style="width:100%">
+	<table class="table table-condensed table-striped table-bordered" ng-hide="hasExclusiveValues()" style="width:100%">
 		<tr>
 			<th colspan="2">Exclusive</th>
 		</tr>