\About
\dShow Heap Profile

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

\EndAbout

\Help
\DShow 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.
\iImportant:
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 such a module are displayed as
Function<n>, where <n> is a unique number.

\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 column title. By default the lines
are sorted by heap use.

\DThe Profile Window

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

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

\bFunction
The name of the function or constructor.

\bModule
The name of the definition module 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