022d4e31725fce61cc9cf7a72d159e9d47870534
[ghc.git] / ghc / docs / users_guide / prof-rts-options.lit
1 %
2 % Included by  prof-options.lit  and  runtime_control.lit
3 %
4
5 It isn't enough to compile your program for profiling with \tr{-prof}!
6
7 When you {\em run} your profiled program, you must tell the runtime system (RTS)
8 what you want to profile (e.g., time and/or space), and how you wish
9 the collected data to be reported.  You also may wish to set the
10 sampling interval used in time profiling.
11
12 Executive summary: \tr{./a.out +RTS -p} produces a time profile in
13 \tr{a.out.prof}; \tr{./a.out +RTS -hC} produces space-profiling
14 info which can be mangled by \tr{hp2ps} and viewed with \tr{ghostview}
15 (or equivalent).
16
17 Profiling runtime flags are passed to your program between the usual
18 \tr{+RTS} and \tr{-RTS} options.
19
20 \begin{description}
21 \item[\tr{-p<sort>} or \tr{-P<sort>}:]
22 \index{-p<sort> RTS option (profiling)}
23 \index{-P<sort> RTS option (profiling)}
24 \index{time profile}
25 \index{serial time profile}
26 The \tr{-p} option produces a standard {\em time profile} report.
27 It is written into the file \pl{<program>}\tr{.prof}.
28
29 The \tr{-P} option produces a more detailed report containing the
30 actual time and allocation data as well.  (Not used much.)
31
32 The \tr{-P} option also produces {\em serial time-profiling}
33 information, in the file \pl{<program>}\tr{.time}. This can be
34 converted into a (somewhat unsatisfactory) PostScript graph using
35 \tr{hp2ps} (see \Sectionref{hp2ps}).
36
37 ???? -F2s needed for serial time profile??? ToDo
38
39 The \pl{<sort>} indicates how the cost centres are to be sorted in the
40 report. Valid \pl{<sort>} options are:
41 \begin{description}
42 \item[\tr{T}:] by time, largest first (the default);
43 \item[\tr{A}:] by bytes allocated, largest first;
44 \item[\tr{C}:] alphabetically by group, module and cost centre.
45 \end{description}
46
47 \item[\tr{-i<secs>}:]
48 \index{-i<secs> RTS option (profiling)}
49 Set the profiling (sampling) interval to \tr{<secs>} seconds (the
50 default is 1~second).
51
52 \item[\tr{-h<break-down>}:]
53 \index{-h<break-down> RTS option (profiling)}
54 \index{heap profile}
55 Produce a detailed {\em space profile} of the heap occupied by live
56 closures. The profile is written to the file \pl{<program>}\tr{.hp}
57 from which a PostScript graph can be produced using \tr{hp2ps} (see
58 \Sectionref{hp2ps}).
59
60 The heap space profile may be broken down by different criteria:
61 \begin{description}
62 \item[\tr{-hC}:] cost centre which produced the closure (the default).
63 \item[\tr{-hM}:] cost centre module which produced the closure.
64 \item[\tr{-hG}:] cost centre group which produced the closure.
65 \item[\tr{-hD}:] closure description --- a string describing the closure.
66 \item[\tr{-hY}:] closure type --- a string describing the closure's type.
67 \item[\tr{-hT<ints>,<start>}:] the time interval the closure was
68 created. \tr{<ints>} specifies the no. of interval bands plotted
69 (default 18) and \tr{<start>} the number of seconds after which the
70 reported intervals start (default 0.0).
71 \end{description}
72 By default all live closures in the heap are profiled, but particular
73 closures of interest can be selected (see below). 
74 \end{description}
75
76
77 Heap (space) profiling uses hash tables. If these tables
78 should fill the run will abort. The
79 \tr{-z<tbl><size>}\index{-z<tbl><size> RTS option (profiling)} option is used to
80 increase the size of the relevant hash table (\tr{C}, \tr{M},
81 \tr{G}, \tr{D} or \tr{Y}, defined as for \pl{<break-down>} above). The
82 actual size used is the next largest power of 2.
83
84 The heap profile can be restricted to particular closures of interest.
85 The closures of interest can selected by the attached cost centre
86 (module:label, module and group), closure category (description, type,
87 and kind) and closure age using the following options:
88 \begin{description}
89 \item[\tr{-c{<mod>:<lab>,<mod>:<lab>...}}:]
90 \index{-c{<lab>} RTS option (profiling)}
91 Selects individual cost centre(s).
92 \item[\tr{-m{<mod>,<mod>...}}:]
93 \index{-m{<mod>} RTS option (profiling)}
94 Selects all cost centres from the module(s) specified.
95 \item[\tr{-g{<grp>,<grp>...}}:]
96 \index{-g{<grp>} RTS option (profiling)}
97 Selects all cost centres from the groups(s) specified.
98 \item[\tr{-d{<des>,<des>...}}:]
99 \index{-d{<des>} RTS option (profiling)}
100 Selects closures which have one of the specified descriptions.
101 \item[\tr{-y{<typ>,<typ>...}}:]
102 \index{-y{<typ>} RTS option (profiling)}
103 Selects closures which have one of the specified type descriptions.
104 \item[\tr{-k{<knd>,<knd>...}}:]
105 \index{-k{<knd>} RTS option (profiling)}
106 Selects closures which are of one of the specified closure kinds.
107 Valid closure kinds are \tr{CON} (constructor), \tr{FN} (manifest
108 function), \tr{PAP} (partial application), \tr{BH} (black hole) and
109 \tr{THK} (thunk).
110 \item[\tr{-a<age>}:]
111 \index{-a<age> RTS option (profiling)}
112 Selects closures which have survived \pl{<age>} complete intervals.
113 \end{description}
114 The space occupied by a closure will be reported in the heap profile
115 if the closure satisfies the following logical expression:
116 \begin{display}
117 ([-c] or [-m] or [-g]) and ([-d] or [-y] or [-k]) and [-a]
118 \end{display}
119 where a particular option is true if the closure (or its attached cost
120 centre) is selected by the option (or the option is not specified).