4.3. 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 -pT 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 <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). Fractions are allowed: for example -i0.2 will get 5 samples per 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 4.5.1).

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) using the following options:

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

RTS option (profiling)} Selects individual cost centre(s).

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

RTS option (profiling)} Selects all cost centres from the module(s) specified.

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

RTS option (profiling)} Selects all cost centres from the groups(s) specified.

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

RTS option (profiling)} Selects closures which have one of the specified descriptions.

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

RTS option (profiling)} Selects closures which have one of the specified type descriptions.

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

RTS option (profiling)} 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).

The space occupied by a closure will be reported in the heap profile if the closure satisfies the following logical expression:

"([-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).