From fce3a0ab499a11edbd8cd024ca0e706d164c3bda Mon Sep 17 00:00:00 2001 From: Antoine Bernard Date: Mon, 9 Sep 2024 14:26:24 +0200 Subject: [PATCH] Added documentation (see #85) and fixed some typos. --- src/doc/file-format.md | 2 +- src/lib/core/SegmentTracker.cpp | 2 +- src/lib/wrapper/AllocWrapper.cpp | 2 +- src/webview/client-files/app/js/directives.js | 2 +- src/webview/client-files/app/js/page-home.js | 4 +-- .../client-files/app/partials/help.html | 32 +++++++++++++------ .../app/partials/memory-table.html | 2 +- 7 files changed, 29 insertions(+), 17 deletions(-) diff --git a/src/doc/file-format.md b/src/doc/file-format.md index cd2e7b85e..3447532d9 100644 --- a/src/doc/file-format.md +++ b/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 diff --git a/src/lib/core/SegmentTracker.cpp b/src/lib/core/SegmentTracker.cpp index 16c80cafe..5d37edd8a 100644 --- a/src/lib/core/SegmentTracker.cpp +++ b/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. **/ diff --git a/src/lib/wrapper/AllocWrapper.cpp b/src/lib/wrapper/AllocWrapper.cpp index bad12248a..3499752c6 100644 --- a/src/lib/wrapper/AllocWrapper.cpp +++ b/src/lib/wrapper/AllocWrapper.cpp @@ -20,7 +20,7 @@ #include //signal #include -//intenrals +//internals #include #include #include diff --git a/src/webview/client-files/app/js/directives.js b/src/webview/client-files/app/js/directives.js index 61be36906..66598db9a 100644 --- a/src/webview/client-files/app/js/directives.js +++ b/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 diff --git a/src/webview/client-files/app/js/page-home.js b/src/webview/client-files/app/js/page-home.js index 326b77621..c54c25c36 100644 --- a/src/webview/client-files/app/js/page-home.js +++ b/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', diff --git a/src/webview/client-files/app/partials/help.html b/src/webview/client-files/app/partials/help.html index e0a91107a..c2701d8d4 100644 --- a/src/webview/client-files/app/partials/help.html +++ b/src/webview/client-files/app/partials/help.html @@ -17,7 +17,7 @@

Use of the GUI

malt-webview -i malt-my_program-12589.json [-p PORT]

It opens a webserver on port 8080 by default so you can open it with your browser by going to http://localhost:8080. -If you run it remotly, you might need to forward the port through SSH by using command :

+If you run it remotely, you might need to forward the port through SSH by using command : 

ssh user@foo -L8080:localhost:8080
@@ -51,7 +51,7 @@

Requested memory

Virtual memory

This is the memory the memory allocator (malloc) 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 mmap 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 mmap system call. We can illustrate with the given code :

@@ -65,15 +65,15 @@ 
Virtual memory

 free(a);                  //Total virtual = 0
-

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). +

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.

-

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.

+

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.

Physical memory

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.

@@ -85,7 +85,7 @@

Physical memory

free(a); //Total virtual = 0, physical = 0 -

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.

+

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.

Internal memory

@@ -96,19 +96,31 @@

About memory peaks

MALT provide two kinds of memory peaks :

    -
  • Local peak : it track the maximum memor used by a given function for the wall execution.
    • -
  • 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.
    • +
  • Local peak : it tracks the maximum memory used by a given function for the whole execution.
    • +
  • 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.

About chunk lifetime

-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. +

Chunk lifetime corresponds to the time between malloc and free. Ideally, it needs to be as long as possible, as short lifetime linked to lot of allocation can lead to performance issues.

Allocation rates

-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. +

Allocation rate are related to number of allocation in a short period. It can pinpoint performance overhead due to operating system memory management functions.

+ +

About counters

+ +

For each counter, MALT tracks two sub-metric:

+ +
    +
  • Inclusive: It is the number of times malloc (realloc, free, ...) has been seen under this function (by looking in all call stacks and accounting if called in child functions). This is also called total in code.
    • +
  • Exclusive: It is the number of times exactly that malloc (realloc, free, ...) has been called in this function. This is also called own in code.
    • +
+ +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.

Thanks

diff --git a/src/webview/client-files/app/partials/memory-table.html b/src/webview/client-files/app/partials/memory-table.html index 977dcacb6..093ba047d 100644 --- a/src/webview/client-files/app/partials/memory-table.html +++ b/src/webview/client-files/app/partials/memory-table.html @@ -32,7 +32,7 @@ [ {{formatValue(selectedDetails.total.lifetime.min,'')}} , {{formatRoundedRatio(selectedDetails.total.lifetime.sum , selectedDetails.total.lifetime.count,'')}} , {{formatValue(selectedDetails.total.lifetime.max ,'')}} ] (cycles) - +
Exclusive