<?xml version="1.0" encoding="ISO-8859-1"?>
<fpdoc-descriptions>
<!--

   $Id: heaptrc.xml,v 1.2 2004/09/13 19:27:49 michael Exp $
   This file is part of the FPC documentation.
   Copyright (C) 1997, by Michael Van Canneyt

   The FPC documentation is free text; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public License as
   published by the Free Software Foundation; either version 2 of the
   License, or (at your option) any later version.

   The FPC Documentation is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public
   License along with the FPC documentation; see the file COPYING.LIB.  If not,
   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
   Boston, MA 02111-1307, USA.
 -->
<package name="rtl">
<module name="heaptrc">
<short>Heap debugging functionality.</short>
<!-- \FPCexampledir{heapex} -->
<descr>
<p>
This document describes the HEAPTRC unit for Free Pascal. It was written by
Pierre Muller. It is system independent, and works on all supported systems.
</p>
<p>
The HEAPTRC unit can be used to debug your memory allocation/deallocation.
It keeps track of the calls to getmem/freemem, and, implicitly, of
New/Dispose statements.
</p>
<p>
When the program exits, or when you request it explicitly.
It displays the total memory used, and then dumps a list of blocks that
were allocated but not freed. It also displays where the memory was
allocated.
</p>
<p>
If there are any inconsistencies, such as memory blocks being allocated
or freed twice, or a memory block that is released but with wrong size,
this will be displayed also.
</p>
<p>
The information that is stored/displayed can be customized using
some constants.
</p>
</descr>

<topic name="usage">
<short>HeapTrc Usage</short>
<descr>
<p>
All that you need to do is to include <file>heaptrc</file> in the uses clause
of your program. Make sure that it is the first unit in the clause,
otherwise memory allocated in initialization code of units that precede the
heaptrc unit will not be accounted for, causing an incorrect memory usage
report.
</p>
<p>
If you use the <var>-gh</var> switch, the compiler will insert the unit by itself,
so you don't have to include it in your uses clause.
</p>
<p>
The below example shows how to use the heaptrc unit.
</p>
<p>
This is the memory dump shown when running this program in a standard way:
</p>
<code>
Marked memory at 0040FA50 invalid
Wrong size : 128 allocated 64 freed
  0x00408708
  0x0040CB49
  0x0040C481
Call trace for block 0x0040FA50 size 128
  0x0040CB3D
  0x0040C481
</code>
<p>
If you use the <file>lineinfo</file> unit (or use the <var>-gl</var> switch) as well,
then <file>heaptrc</file> will also give you the filenames and line-numbers of
the procedures in the backtrace:
</p>
<code>
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
</code>
<p>
If lines without filename/line-number occur, this means there is a unit which
has no debug info included.
</p>
</descr>
<example file="heapex/heapex"/>
</topic>

<topic name="environment">
<short>Controlling HeapTrc with environment variables</short>
<descr>
<p>The <file>HeapTrc</file> unit can be controlled with the <var>HEAPTRC</var>
environment variable. The contents of this variable controls the initial setting
of some constants in the unit. <var>HEAPTRC</var> consists of one or more of the
following strings, separated by spaces:
</p>
<dl>
<dt>keepreleased</dt>
<dd>If this string occurs, then the <link id="KeepReleased"/> variable is set
to <var>True</var></dd>
<dt>disabled</dt>
<dd>If this string occurs, then the <link id="UseHeapTrace"/> variable is set
to <var>False</var> and the heap trace is disabled. It does not make sense to
combine this value with other values.</dd>
<dt>nohalt</dt>
<dd>If this string occurs, then the <link id="HaltOnError"/> variable is set
to <var>False</var>, so the program continues executing even in case of a
heap error.</dd>
<dt>log=filename</dt>
<dd>If this string occurs, then the output of heaptrc is sent
to the specified <var>Filename</var>. (see also <link id="SetHeapTraceOutput"/>)
</dd>
</dl>
<p>
The following are valid values for the HEAPTRC variable:
</p>
<code>
HEAPTRC=disabled
HEAPTRC="keepreleased log=heap.log"
HEAPTRC="log=myheap.log nohalt"
</code>
<p>
Note that these strings are case sensitive, and the name of the variable too.
</p>
</descr>
</topic>

<element name="TFillExtraInfoProc">
<short>The <var>FillExtraInfoProc</var> is a procedural type used in the <link id="SetHeapExtraInfo"/> call.</short>
<descr>
The <var>TFillExtraInfoProc</var> is a procedural type used in the
 <link id="SetHeapExtraInfo"/> call to fill a memory location with
 extra data for displaying.
</descr>
<seealso>
<link id="SetHeapExtraInfo"/>
<link id="TDisplayExtraInfoProc"/>
</seealso>
</element>

<element name="TDisplayExtraInfoProc">
<short>The <var>TDisplayExtraInfoProc</var> is a procedural type used in the <link id="SetHeapExtraInfo"/> call.</short>
<descr>
The <var>TDisplayExtraInfoType</var> is a procedural type used in the
<link id="SetHeapExtraInfo"/> call to display a memory location which was
previously filled with <link id="TFillExtraInfoProc"/>
</descr>
<seealso>
<link id="SetHeapExtraInfo"/>
<link id="TFillExtraInfoProc"/>
</seealso>
</element>


<element name="TraceSize">
<short>Specify size of callback trace</short>
<descr>
<var>Tracesize</var> specifies how many levels of calls are displayed of the
call stack during the memory dump. If you specify <var>keepreleased:=True</var>
then half the <var>TraceSize</var> is reserved for the <var>GetMem</var> call stack,
and the other half is reserved for the <var>FreeMem</var> call stack.
For example, the default value of 8 will cause eight levels of call frames
to be dumped for the getmem call if <var>keepreleased</var> is <var>False</var>. If
<var>KeepReleased</var> is true, then 4 levels of call frames will be dumped for
the <var>GetMem</var> call and 4 frames wil be dumped for the <var>FreeMem</var> call.
If you want to change this value, you must recode the <file>heaptrc</file> unit.
</descr>
</element>

<element name="QuickTrace">
<short>Do quick trace or extensive trace</short>
<descr>
<var>Quicktrace</var> determines whether the memory manager checks whether a
block that is about to be released is allocated correctly. This is a rather
time consuming search, and slows program execution significantly, so by
default it is set to <var>True</var>.
</descr>
</element>

<element name="useHeapTrace">
<short>If set to <var>false</var>, the heap trace will be disabled. </short>
<descr>
This variable must be set at program startup, through the help of an environment variable.
</descr>
<seealso>
<link id="environment"/>
</seealso>
</element>

<element name="HaltOnError">
<short>Halt program on memory fault</short>
<descr>
If <var>HaltOnError</var> is set to <var>True</var> then an illegal call to
<var>FreeMem</var> will cause the memory manager to execute a <var>halt(1)</var>
instruction, causing a memory dump. By Default it is set to <var>True</var>.
</descr>
</element>

<element name="KeepReleased">
<short>Keep released blocks in memory</short>
<descr>
If <var>keepreleased</var> is set to true, then a list of freed memory
blocks is kept. This is useful if you suspect that the same memory block is
released twice. However, this option is very memory intensive, so use it
sparingly, and only when it's really necessary.
</descr>
</element>

<element name="Add_Tail">
<short>Check for memory overwrites</short>
<descr>
If <var>add\_tail</var> is <var>True</var> (the default) then a check is also
performed on the memory location just behind the allocated memory.
</descr>
</element>

<element name="usecrc">
<short>Use CRC check on allocated memory</short>
<descr>
If <var>usecrc</var> is <var>True</var> (the default) then a crc check is performed
on locations before and after the allocated memory. This is useful to
detect memory overwrites.
</descr>
</element>

<element name="DumpHeap">
<short>Dump memory usage report to stderr.</short>
<descr>
<var>DumpHeap</var> dumps to standard output a summary of memory usage.
It is called automatically by the heaptrc unit when your program exits
(by installing an exit procedure), but it can be called at any time.
</descr>
<errors>
None.
</errors>
<seealso>
</seealso>
</element>

<element name="SetHeapExtraInfo">
<short>Store extra information in blocks.</short>
<descr>
<p>
You can use <var>SetHeapExtraInfo</var> to store extra info in the blocks that
the heaptrc unit reserves when tracing getmem calls. <var>Size</var> indicates the
size (in bytes) that the trace mechanism should reserve for your extra
information. For each call to <var>getmem</var>, <var>FillProc</var> will be called,
and passed a pointer to the memory reserved.
</p>
<p>
When dumping the memory summary, the extra info is shown by calling
<var>displayproc</var> and passing it the memory location which was
filled by <var>fillproc</var>. It should write the information in
readable form to the text file provided in the call to <var>displayproc</var>
</p>
</descr>
<errors>
You can only call <var>SetHeapExtraInfo</var> if no memroy has been allocated
yet. If memory was already allocated prior to the call to
<var>SetHeapExtraInfo</var>, then an error will be displayed on standard error
output, and a <link id="DumpHeap"/> is executed.
</errors>
<seealso>
<link id="DumpHeap"/>
<link id="SetHeapTraceOutput"/>
</seealso>
<example file="heapex/setinfo"/>
</element>

<element name="SetHeapTraceOutput">
<short>Specify filename for heap trace output.</short>
<descr>
<var>SetHeapTraceOutput</var> sets the filename into which heap trace info
will be written. By default information is written to standard output,
this function allows you to redirect the information to a file with
full filename <var>name</var>.
</descr>
<errors>
If the file cannot be written to, errors will occur when writing the
trace.
</errors>
<seealso>
<link id="SetHeapExtraInfo"/>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="HaltOnNotReleased">
<short>Halt on exit if any memory was not freed </short>
<descr>
<var>HaltOnNotReleased</var> can be set to <var>True</var> to make the <link
id="DumpHeap"/> procedure halt (exit code 203) the program if any memory
was not released when the dump is made. If it is <var>False</var> (the
default) then <var>DumpHeap</var> just returns. 
</descr>
<seealso>
<link id="DumpHeap"/>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="printleakedblock">
<short>Print memory dump of leaked blocks ?</short>
<descr>
<var>printleakedblock</var> can be set to <var>True</var> to print a memory
dump of unreleased blocks when the <var>heaptrc</var> unit produces a
summary of memory leaks. The block is printed as a series of hexadecimal
numbers, representing the bytes in the memory block. At most <link id="maxprintedblocklength"/> bytes of
the memory block will be printed. 
</descr>
<seealso>
<link id="maxprintedblocklength"/> 
<link id="printfaultyblock"/>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="printfaultyblock">
<short>Print memory dump of faulty blocks ?</short>
<descr>
<var>printleakedblock</var> can be set to <var>True</var> to print a memory
dump of daulty memory blocks (in case a memory override occurs)
The block is printed as a series of hexadecimal
numbers, representing the bytes in the memory block. At most <link
id="maxprintedblocklength"/> bytes of
the memory block will be printed. 
</descr>
<seealso>
</seealso>
</element>

<!-- constant Visibility: default -->
<element name="maxprintedblocklength">
<short>Maximum length of memory block dumps.</short>
<descr>
<var>maxprintedblocklength</var> determines the maximum number of bytes
written by a memory block dump, as produced when <link
id="printleakedblock"/> or <link id="printfaultyblock"/> are true.
If the size of the memory block is larger than this size, then only the
first <var>maxprintedblocklength</var> will be included in the dump.
</descr>
<seealso>
<link id="printleakedblock"/>
<link id="printfaultyblock"/> 
</seealso>
</element>


</module>
</package>
</fpdoc-descriptions>