From 168e6e8b6858afb67c809903e24ee65b230326aa Mon Sep 17 00:00:00 2001 From: michael Date: Mon, 7 Feb 2000 11:21:06 +0000 Subject: [PATCH] + Documented heaptrc and lineinfo --- docs/heaptrc.tex | 66 +++++++++++++++---------------- docs/user.tex | 101 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 132 insertions(+), 35 deletions(-) diff --git a/docs/heaptrc.tex b/docs/heaptrc.tex index 95c4ec61be..02e43d44dc 100644 --- a/docs/heaptrc.tex +++ b/docs/heaptrc.tex @@ -40,6 +40,7 @@ this will be displayed also. The information that is stored/displayed can be customized using some constants. + \section{Usage} All that you need to do is to include \file{heaptrc} in the uses clause @@ -48,49 +49,41 @@ otherwise memory allocated in initialization code of units that precede the heaptrc unit will not be accounted for, causing an incorrect memory usage report. -The following example shows how to use the heaptrc unit. +If you use the \var{-gh} switch, the compiler will insert the unit by itself, +so you don't have to include it in your uses clause. +The following example shows how to use the heaptrc unit. \latex{\lstinputlisting{heapex/heapex.pp}} \html{\input{heapex/heapex.tex}} This is the memory dump shown when running this program: \begin{verbatim} -Marked memory at 08052C48 invalid +Marked memory at 0040FA50 invalid Wrong size : 128 allocated 64 freed - 0x0804C29C - 0x080509E2 - 0x080480A4 - 0x00000000 -Heap dump by heaptrc unit -13 memory blocks allocated : 1416/1424 -6 memory blocks freed : 708/712 -7 unfreed memory blocks : 708 -True heap size : 2097152 -True free heap : 2096040 -Should be : 2096104 -Call trace for block 0x08052C48 size 128 - 0x080509D6 - 0x080480A4 -Call trace for block 0x08052B98 size 128 - 0x08050992 - 0x080480A4 -Call trace for block 0x08052AE8 size 128 - 0x08050992 - 0x080480A4 -Call trace for block 0x08052A38 size 128 - 0x08050992 - 0x080480A4 -Call trace for block 0x08052988 size 128 - 0x08050992 - 0x080480A4 -Call trace for block 0x080528D8 size 128 - 0x08050992 - 0x080480A4 -Call trace for block 0x080528A0 size 4 - 0x08050961 - 0x080480A4 + 0x00408708 + 0x0040CB49 + 0x0040C481 +Call trace for block 0x0040FA50 size 128 + 0x0040CB3D + 0x0040C481 \end{verbatim} +If you use the \file{lineinfo} unit (or use the \var{-gl} switch) as well, +then \file{heaptrc} will also give you the filenames and line-numbers of +the procedures in the backtrace: +\begin{verbatim} +Marked memory at 00410DA0 invalid +Wrong size : 128 allocated 64 freed + 0x004094B8 + 0x0040D8F9 main, line 25 of heapex.pp + 0x0040D231 +Call trace for block 0x00410DA0 size 128 + 0x0040D8ED main, line 23 of heapex.pp + 0x0040D231 +\end{verbatim} +If lines without filename/line-number occur, this means there is a unit which +has no debug info included. + \section{Constants, Types and variables} The \var{FillExtraInfoType} is a procedural type used in the @@ -189,7 +182,10 @@ output, and a \seep{DumpHeap} is executed. % % $Log$ -% Revision 1.3 1999-06-25 22:12:16 michael +% Revision 1.4 2000-02-07 11:21:06 michael +% + Documented heaptrc and lineinfo +% +% Revision 1.3 1999/06/25 22:12:16 michael % + Update to version 0.19 of listings package % % Revision 1.2 1998/12/15 23:50:52 michael diff --git a/docs/user.tex b/docs/user.tex index 471fd2ffaf..2f4b4b6456 100644 --- a/docs/user.tex +++ b/docs/user.tex @@ -2340,6 +2340,107 @@ then only output the information about the timings For more information on the \gnu profiler \var{gprof}, see its manual. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Checking the heap +\section{Detecting heap memory leaks} +\label{se:heaptrc} +\fpc has a built in mechanism to detect memory leaks. There is a plug-in +unit for the memory manager that analyses the memory allocation/deallocation +and which prints a memory usage report after the program exits. + +The unit that does this is called \file{heaptrc}. If you want to use it, +you should include it as the first unit in you uses clause. Alternatively, +you can supply the \var{-gh} switch to the compiler, and it will include +the unit automatically for you. + +After the program exits, you will get a report looking like this: +\begin{verbatim} +Marked memory at 0040FA50 invalid +Wrong size : 128 allocated 64 freed + 0x00408708 + 0x0040CB49 + 0x0040C481 +Call trace for block 0x0040FA50 size 128 + 0x0040CB3D + 0x0040C481 +\end{verbatim} +The output of the heaptrc unit is customizable by setting some variables. + +You can find more information about the usage of the \file{heaptrc} unit +in the \unitsref. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Verbos Run-time errors. +\section{Line numbers in run-time error backtraces} +\label{se:lineinfo} + +Normally, when a run-time error occurs, you are presented with a list +of addresses that represent the call stack backtrace, i.e. the addresses +of all procedures that were invoked when the run-time error occurred. + +This list is not very informative, so there exists a unit that generates +the file names and line numbers of the called procedures using the +addresses of the stack backtrace. This unit is called lineinfo. + +You can use this unit by giving the \var{-gl} option to the compiler. The +unit will be automatically included. It is also possible to use the unit +explicitly in your \var{uses} clause, but you must make sure that you +compile your program with debug info. + +Here is an example program: +\begin{verbatim} +program testline; + +procedure generateerror255; + +begin + runerror(255); +end; + +procedure generateanerror; + +begin + generateerror255; +end; + +begin + generateanerror; +end. +\end{verbatim} +When compiled with \var{-gl}, the following output is generated: +\begin{verbatim} +Runtime error 255 at 0x0040BDE5 + 0x0040BDE5 GENERATEERROR255, line 6 of testline.pp + 0x0040BDF0 GENERATEANERROR, line 13 of testline.pp + 0x0040BE0C main, line 17 of testline.pp + 0x0040B7B1 +\end{verbatim} +Which is more understandable than the normal message. Make sure that all +units you use are compiled with debug info, because if they are not, no +line number and filename can be found. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Combining heaptrc and lineinfo +\section{Combining \file{heaptrc} and \file{lineinfo}} + +If you combine the lineinfo and the heaptrc information, then the output +of the \file{heaptrc} unit will contain the names of the files and line +numbers of the procedures that occur in the stack backtrace. + +In such a case, the output will look something like this: +\begin{verbatim} +Marked memory at 00410DA0 invalid +Wrong size : 128 allocated 64 freed + 0x004094B8 + 0x0040D8F9 main, line 25 of heapex.pp + 0x0040D231 +Call trace for block 0x00410DA0 size 128 + 0x0040D8ED main, line 23 of heapex.pp + 0x0040D231 +\end{verbatim} +If lines without filename/line-number occur, this means there is a unit which +has no debug info included. (in the above case, the getmem call itself) + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % CGI. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%