\About
\dShow Time Profile

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

\EndAbout

\Help
\DShow Time Profile

\cA utility to inspect Profiles generated by Clean programs.

\DProfiling overview

\bIntroduction
When time profiling is enabled, the Clean compiler adds some extra code for
every function call. This code sums up the time and heap resources used by
the function. This information is written to file when the Clean application
exists.

\bGenerate a profile
To generate a profile file you must run a Clean program with special profiling
code. The profile is named "Profile" on the PowerMac and "Profile.pcl"
on Windows. The file will be overwritten when the application is run again.

The information in the Profile is based on real time measurements. To obtain
reliable and accurate results, you should generate the profile on an unloaded
system.

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 a profile
Use this ShowTimeProfile application to inspect the profile file. Under
Windows 95/NT you must inspect the profile on a similar machine (same
processor and clock speed) or the timing results may not be accurate.
The PowerMac version of ShowTimeProfile compensates for differences in
processor speed.

\bSpecial entries
Two special entries from Clean's run-time system are displayed in the profile
window. They appear under the following names:

1) start: the entry point, note that this is different from the Start function
  from the Clean program.
2) garbage_collector: the garbage collector. Because the garbage collector
  frees heap space the Alloc columns will contain negative values.

\bMissing functions
Functions that are not profiled will not be displayed. They are a two possible
reasons for this:
1) The function was inlined. This is the case for basic operations from the
   standard environment.
2) No profiling code was generated for the module in which the function was
   defined. This happens if you use "Never Time Profile" in the "Clean Compiler
   Options..." dialogue box. For more information see the help information in
   the Clean Integrated Developing Environment.

In both cases the resources used by the function (time and heap) are attributed
to the function from which it was called.

\DMenus and commands

\bThe File menu:
- Use the Open command to select 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 time.

\DThe Profile Window

The Profile Window displays a row for every function that was called by the
profiled application. 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.

\bTime(s)
The time spent in the function in seconds.

\bTime(%)
The time spent in the function  as a percentage of the total execution time of
the program.

\bAlloc(bytes)
Number of bytes allocated in the heap by the function.

\bAlloc(%)
Heap space allocated by the function as a percentage of the total number of bytes
allocated by the program.

\bStrict(n)
Number of calls to the function in a strict context. Direct tail recursive calls
of a function to itself are not counted.

\bLazy(n)
Number of calls to the function in a lazy context.

\bCurried(n)
Number of curried calls to the function.

\EndHelp
