\About
\dShow Heap Profile

\cA utility to inspect Heap Profiles generated
\cby Clean programs.

\EndAbout

\Help
\DShow Heap Profile

\cA utility to inspect Heap Profiles
\cgenerated by Clean programs.

\DHeap Profiling overview

\bIntroduction
The ShowHeapProfile application is a tool to analyse heap files that are
generated by Clean programs. By inspecting heap files you can get an idea
of which function and constructor nodes are taking up the most heap space.

\bGenerate heap files
To generate heap profile files you must run a Clean program with special memory
profiling code. With Heap profiling the application writes a number of heap files
(Heap0 .. Heap9). A heap file is generated after a garbage collection when
the heap use is above a certain limit (the Minimum Profile Heap). The heap files
should be removed after inspection, because they will not be overwritten.

See the section about the Application... dialogue in the help information
of the Clean Integrated Developing Environment for information on how to add
profiling code to a Clean application.

\bInspect profiles
Use this ShowHeapProfile application to inspect the heap files.
* Important *: ShowHeapProfile needs to find the original application in the same
folder as the heap files. It will fail if the application can not be found, or if
the application is changed after the heap files are generated.

\bSpecial names
There are a few special names that can appear in the profile window

Cons: list constructor ([:])
_Tuple<n>: <n>-tuple
Selector: record selections
select;...: array selections
ARRAY: arrays
Int, Bool, Real, File: values of basic types

\bMissing names
It is possible to turn of heap profiling for individual modules (see the help
on the Clean Compiler options in the Clean Integrated Developing Environment).
Nodes with functions and constructors from modules with no heap profiling
information are grouped as Function<n>, where <n> is the arity of the node.

\DMenus and commands
\L
\bThe File menu:
- Use the Open command to select the profile file. Only one profile can be
  open at a time.
- Use the Close command to close the profile file.
- Help gives you the information you are reading now.
- With the command Quit you can leave the program.

\L
\bThe Sort Menu:
The sort menu contains a sort command for every type of value in the profile
window. You can also sort by clicking on a colum title. By default the rows
are sorted by heap use.

\DThe Profile Window

The Profile Window displays a row for every type of node in the heap. Totals are
given on the last row.

You can sort a column by clicking on its title. The columns contain the following
information:

\bFunction
The name of the function or constructor.

\bHeap use(bytes)
Number of bytes used in the heap by nodes with the function or constructor.

\bHeap use(%)
Heap space used by nodes with function or constructor as a percentage of the total
number of bytes used in the heap.

\EndHelp
