How to control your profiled program at runtime

It isn't enough to compile your program for profiling with `-prof'!

When you run your profiled program, you must tell the runtime system (RTS) what you want to profile (e.g., time and/or space), and how you wish the collected data to be reported. You also may wish to set the sampling interval used in time profiling.

Executive summary: `./a.out +RTS -p' produces a time profile in `a.out.prof'; `./a.out +RTS -hC' produces space-profiling info which can be mangled by `hp2ps' and viewed with `ghostview' (or equivalent).

Profiling runtime flags are passed to your program between the usual `+RTS' and `-RTS' options.

`-p<sort>' or `-P<sort>':

The `-p' option produces a standard time profile report. It is written into the file <program>`.prof'. The `-P' option produces a more detailed report containing the actual time and allocation data as well. (Not used much.) The `-P' option also produces serial time-profiling information, in the file <program>`.time'. This can be converted into a (somewhat unsatisfactory) PostScript graph using `hp2ps' (see Section See section `hp2ps'--heap profile to PostScript). ???? -F2s needed for serial time profile??? ToDo The <sort> indicates how the cost centres are to be sorted in the report. Valid <sort> options are:

`T':

by time, largest first (the default);

`A':

by bytes allocated, largest first;

`C':

alphabetically by group, module and cost centre.

`-i<secs>':

Set the profiling (sampling) interval to `<secs>' seconds (the default is 1 second).

`-h<break-down>':

Produce a detailed space profile of the heap occupied by live closures. The profile is written to the file <program>`.hp' from which a PostScript graph can be produced using `hp2ps' (see Section See section `hp2ps'--heap profile to PostScript). The heap space profile may be broken down by different criteria:

`-hC':

cost centre which produced the closure (the default).

`-hM':

cost centre module which produced the closure.

`-hG':

cost centre group which produced the closure.

`-hD':

closure description -- a string describing the closure.

`-hY':

closure type -- a string describing the closure's type.

By default all live closures in the heap are profiled, but particular closures of interest can be selected (see below).

Heap (space) profiling uses hash tables. If these tables should fill the run will abort. The `-z<tbl><size>' option is used to increase the size of the relevant hash table (`C', `M', `G', `D' or `Y', defined as for <break-down> above). The actual size used is the next largest power of 2.

The heap profile can be restricted to particular closures of interest. The closures of interest can selected by the attached cost centre (module:label, module and group), closure category (description, type, and kind) and closure age using the following options:

`-c{<mod>:<lab>,<mod>:<lab>...}':

Selects individual cost centre(s).

`-m{<mod>,<mod>...}':

Selects all cost centres from the module(s) specified.

`-g{<grp>,<grp>...}':

Selects all cost centres from the groups(s) specified.

`-d{<des>,<des>...}':

Selects closures which have one of the specified descriptions.

`-y{<typ>,<typ>...}':

Selects closures which have one of the specified type descriptions.

`-k{<knd>,<knd>...}':

Selects closures which are of one of the specified closure kinds. Valid closure kinds are `CON' (constructor), `FN' (manifest function), `PAP' (partial application), `BH' (black hole) and `THK' (thunk).

([-c] or [-m] or [-g]) and ([-d] or [-y] or [-k]) 

where a particular option is true if the closure (or its attached cost centre) is selected by the option (or the option is not specified).