ghc/docs/users_guide/profiling.lit

   1 \begin{onlystandalone}
   2 \documentstyle[11pt,literate]{article}
   3 \begin{document}
   4 \title{The Glorious Haskell Compilation System\\ Profiling Guide}
   5 \author{The AQUA Team (Patrick M. Sansom)\\
   6 Department of Computing Science\\
   7 University of Glasgow\\
   8 Glasgow, Scotland\\
   9 G12 8QQ\\
  10 \\
  11 Email: glasgow-haskell-\{bugs,request\}\@dcs.glasgow.ac.uk}
  12 \maketitle
  13 \begin{rawlatex}
  14 \tableofcontents
  15 \end{rawlatex}
  16 \end{onlystandalone}
  17
  18 \section[profiling]{Profiling Haskell programs}
  19 \index{profiling, with cost-centres}
  20 \index{cost-centre profiling}
  21
  22 Glasgow Haskell comes with a time and space profiling system. Its
  23 purpose is to help you improve your understanding of your program's
  24 execution behaviour, so you can improve it.
  25
  26 %This profiling system is still under development.
  27 %Please e-mail reports of any bugs you discover to
  28 %\tr{glasgow-haskell-bugs@dcs.glasgow.ac.uk}.
  29
  30 Any comments, suggestions and/or improvements you have to are welcome.
  31 Recommended ``profiling tricks'' would be especially cool!
  32
  33 \subsection[profiling-intro]{How to profile a Haskell program}
  34
  35 The GHC approach to profiling is very simple: annotate the expressions
  36 you consider ``interesting'' with {\em cost centre} labels (strings);
  37 so, for example, you might have:
  38
  39 \begin{verbatim}
  40 f x y
  41   = let
  42         output1 = _scc_ "Pass1" ( pass1 x )
  43         output2 = _scc_ "Pass2" ( pass2 output1 y )
  44         output3 = _scc_ "Pass3" ( pass3 (output2 `zip` [1 .. ]) )
  45     in concat output3
  46 \end{verbatim}
  47
  48 The costs of the evaluating the expressions bound to \tr{output1},
  49 \tr{output2} and \tr{output3} will be attributed to the ``cost
  50 centres'' \tr{Pass1}, \tr{Pass2} and \tr{Pass3}, respectively.
  51
  52 The costs of evaluating other expressions, e.g., \tr{concat output4},
  53 will be inherited by the scope which referenced the function \tr{f}.
  54
  55 You can put in cost-centres via \tr{_scc_} constructs by hand, as in
  56 the example above.  Perfectly cool.  That's probably what you {\em
  57 would} do if your program divided into obvious ``passes'' or
  58 ``phases'', or whatever.
  59
  60 If your program is large or you have no clue what might be gobbling
  61 all the time, you can get GHC to mark all functions with \tr{_scc_}
  62 constructs, automagically.  Add an \tr{-auto} compilation flag to the
  63 usual \tr{-prof} option.
  64
  65 Once you start homing in on the Guilty Suspects, you may well switch
  66 from automagically-inserted cost-centres to a few well-chosen ones of
  67 your own.
  68
  69 To use profiling, you must {\em compile} and {\em run} with special
  70 options.  (We usually forget the ``run'' magic!---Do as we say, not as
  71 we do...) Details follow.
  72
  73 If you're serious about this profiling game, you should probably read
  74 one or more of the Sansom/Peyton Jones papers about the GHC profiling
  75 system.  Just visit the Glasgow FP Web page...
  76
  77 %************************************************************************
  78 %*                                                                      *
  79 \subsection[prof-compiler-options]{Compiling programs for profiling}
  80 \index{profiling options}
  81 \index{options, for profiling}
  82 %*                                                                      *
  83 %************************************************************************
  84
  85 \input{prof-compiler-options.lit}
  86
  87 %************************************************************************
  88 %*                                                                      *
  89 \subsection[prof-rts-options]{How to control your profiled program at runtime}
  90 \index{profiling RTS options}
  91 \index{RTS options, for profiling}
  92 %*                                                                      *
  93 %************************************************************************
  94
  95 \input{prof-rts-options.lit}
  96
  97 %************************************************************************
  98 %*                                                                      *
  99 \subsection[prof-graphs]{Producing graphical heap profiles}
 100 \index{heap profiles, producing}
 101 %*                                                                      *
 102 %************************************************************************
 103
 104 \input{prof-post-processors.lit}
 105
 106 % \subsection[cost-centres]{Profiling by Cost Centres}
 107 %
 108 % Problems with lazy evaluation
 109 %
 110 % The central idea is to identify particular source code expressions of
 111 % interest. These expressions are annotated with a {\em cost
 112 % centre}\index{cost centre} label. Execution and allocation costs are
 113 % attributed to the cost centre label which encloses the expression
 114 % incurring the costs.
 115 %
 116 % Simple example
 117 %
 118 % (Note: the paper in \tr{ghc/docs/papers/profiling.ps} may have some
 119 % decent examples...)
 120 %
 121 % Costs are attribution to one cost centre.
 122 % Inheritance of un-profiled costs.
 123 %
 124 % Degree of evaluation
 125 % Unevaluated arguments
 126 % Optimisation and transformation
 127 % Evaluation of instances
 128 %   escaping functions: evaluation vs lexical
 129 %
 130 % \subsection[prof-annotations]{Annotating your Haskell source}
 131 %
 132 %   Explicit annotations
 133 %   Automatic annotation
 134 %
 135 % \subsection[prof-information]{Profiling information}
 136 %
 137 %   Cost Centre Label,Module,Group
 138 %   Example time/alloc profile
 139 %
 140 %   Description of heap profile
 141 %   Closure Description, Type and Kind
 142 % \subsection[limitations]{Limitations of the current profiling system}
 143 %
 144 % There are a number of limitations and shortcomings of the current
 145 % profiling system. Any comments on the impact of these and any
 146 % suggested improvements would be greatly appreciated.
 147 %
 148 % \begin{onlylatex}
 149 % \subsubsection*{Explicit \tr{_scc_} annotations}
 150 % \end{onlylatex}
 151 % \begin{onlyinfo}
 152 % Explicit \tr{_scc_} annotations:
 153 % \end{onlyinfo}
 154 %
 155 % The explicit \tr{_scc_} source annotations cannot annotate entire
 156 % function declarations as the clauses, pattern matching are not part of
 157 % the expression syntax --- they are syntactic sugar. It is possible to
 158 % remove the syntactic sugar by hand, translating to a simple
 159 % declaration with case expressions on the rhs, but this is very
 160 % tiresome.
 161 %
 162 % We propose to introduce an additional annotation to enable a \tr{_scc_}
 163 % annotation to be placed around an entire declaration.
 164 %
 165 % To further ease the explicit annotation process we also propose to
 166 % provide annotations which instruct the compiler to annotate all the
 167 % declarations in a particular \tr{let} or \tr{where} clause with the
 168 % name of the declaration.
 169 %
 170 % Other annotation schemes are feasible. Any suggestions / requests?
 171 %
 172 %
 173 % \begin{onlylatex}
 174 % \subsubsection*{Closure descriptions}
 175 % \end{onlylatex}
 176 % \begin{onlyinfo}
 177 % Closure descriptions:
 178 % \end{onlyinfo}
 179 %
 180 % The closure descriptions are by no means perfect ...
 181 %
 182 % The descriptions for expressions are somewhat tedious as they reflect
 183 % some of the structure of the transformed STG code. This is largely to
 184 % provide additional information so use of the STG code can be made if
 185 % required (use the compiler option \tr{-ddump-stg}). This may be
 186 % removed if the name of the \pl{corner} is considered sufficient.
 187 %
 188 % Local bindings introduced by the compiler have a name \tr{?<tag>}.
 189 % Most of these are not related to the source in any meaningful way. For
 190 % example, the \tr{?stg} names are introduced during the CoreToStg pass.
 191 % Some other arbitrary compiler introduced names are: \tr{?ds},
 192 % \tr{?tpl}, \tr{?si}, \tr{?cs}, \tr{?ll}, and \tr{?sat}. Please let us
 193 % know if any of these turn out to be a problem. We could introduce a
 194 % more meaningful naming scheme into the compiler which assigns names
 195 % that reflect the nearest enclosing source binding. Another possibility
 196 % is to add the unique identifier so they aren't all clumped together as
 197 % one indistinguishable description.
 198 %
 199 % There is only one closure description and type for all black holes,
 200 % ``BH''. It might be useful to record the closure that is currently
 201 % being evaluated as part of the black hole description.
 202 %
 203 % Similarly there is only one partial application description, ``PAP''.
 204 % It might be useful to record the function being applied in the partial
 205 % application as part of the partial application description.
 206 %
 207 %
 208 % \begin{onlylatex}
 209 % \subsubsection*{Garbage collection and paging}
 210 % \end{onlylatex}
 211 % \begin{onlyinfo}
 212 % Garbage collection and paging:
 213 % \end{onlyinfo}
 214 %
 215 % Currently the profiling implementation requires the two-space
 216 % (\tr{-gc-2s}) garbage collector to be used. When using the \tr{-prof}
 217 % options a particular garbage collector should not be specified. This
 218 % imposes particular paging characteristics which may be different from
 219 % the garbage collector your program normally uses. These paging
 220 % characteristics may distort the user time profiling results, though we
 221 % do not believe this is a significant problem.
 222 %
 223 %
 224 % \subsection[references]{Papers describing this work}
 225 %
 226 % A discussion of our initial ideas are described in the paper
 227 % ``Profiling Lazy Functional Languages'' by Patrick Sansom and Simon
 228 % Peyton Jones.
 229 %
 230 % It is in the GHC distribution in \tr{ghc/docs/papers/profiling.ps},
 231 % or it can be retrieved using ftp from
 232 % \tr{ftp.dcs.glasgow.ac.uk} (\tr{[130.209.240.50]})
 233 % in the file
 234 % \tr{pub/glasgow-fp/papers/lazy-profiling.ps}.
 235
 236 \begin{onlystandalone}
 237 \printindex
 238 \end{document}
 239 \end{onlystandalone}