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).