ghc/docs/users_guide/profiling.sgml

   1 <Chapter id="profiling">
   2 <Title>Profiling
   3 </Title>
   4
   5 <Para>
   6 <IndexTerm><Primary>profiling, with cost-centres</Primary></IndexTerm>
   7 <IndexTerm><Primary>cost-centre profiling</Primary></IndexTerm>
   8 Glasgow Haskell comes with a time and space profiling system. Its
   9 purpose is to help you improve your understanding of your program's
  10 execution behaviour, so you can improve it.
  11 </Para>
  12
  13 <Para>
  14 Any comments, suggestions and/or improvements you have are welcome.
  15 Recommended ``profiling tricks'' would be especially cool!
  16 </Para>
  17
  18 <Sect1 id="profiling-intro">
  19 <Title>How to profile a Haskell program
  20 </Title>
  21
  22 <Para>
  23 The GHC approach to profiling is very simple: annotate the expressions
  24 you consider ``interesting'' with <Emphasis>cost centre</Emphasis> labels (strings);
  25 so, for example, you might have:
  26 </Para>
  27
  28 <Para>
  29
  30 <ProgramListing>
  31 f x y
  32   = let
  33         output1 = _scc_ "Pass1" ( pass1 x )
  34         output2 = _scc_ "Pass2" ( pass2 output1 y )
  35         output3 = _scc_ "Pass3" ( pass3 (output2 `zip` [1 .. ]) )
  36     in concat output3
  37 </ProgramListing>
  38
  39 </Para>
  40
  41 <Para>
  42 The costs of the evaluating the expressions bound to <VarName>output1</VarName>,
  43 <VarName>output2</VarName> and <VarName>output3</VarName> will be attributed to the ``cost
  44 centres'' <VarName>Pass1</VarName>, <VarName>Pass2</VarName> and <VarName>Pass3</VarName>, respectively.
  45 </Para>
  46
  47 <Para>
  48 The costs of evaluating other expressions, e.g., <Literal>concat output4</Literal>,
  49 will be inherited by the scope which referenced the function <Function>f</Function>.
  50 </Para>
  51
  52 <Para>
  53 You can put in cost-centres via <Function>&lowbar;scc&lowbar;</Function> constructs by hand, as in the
  54 example above.  Perfectly cool.  That's probably what you
  55 <Emphasis>would</Emphasis> do if your program divided into obvious ``passes'' or
  56 ``phases'', or whatever.
  57 </Para>
  58
  59 <Para>
  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 <Function>&lowbar;scc&lowbar;</Function>
  62 constructs, automagically.  Add an <Option>-auto</Option> compilation flag to the
  63 usual <Option>-prof</Option> option.
  64 </Para>
  65
  66 <Para>
  67 Once you start homing in on the Guilty Suspects, you may well switch
  68 from automagically-inserted cost-centres to a few well-chosen ones of
  69 your own.
  70 </Para>
  71
  72 <Para>
  73 To use profiling, you must <Emphasis>compile</Emphasis> and <Emphasis>run</Emphasis> with special
  74 options.  (We usually forget the ``run'' magic!&mdash;Do as we say, not as
  75 we do&hellip;) Details follow.
  76 </Para>
  77
  78 <Para>
  79 If you're serious about this profiling game, you should probably read
  80 one or more of the Sansom/Peyton Jones papers about the GHC profiling
  81 system.  Just visit the <ULink URL="http://www.dcs.gla.ac.uk/fp/">Glasgow FP group web page</ULink>&hellip;
  82 </Para>
  83
  84 </Sect1>
  85
  86 <Sect1 id="prof-compiler-options">
  87 <Title>Compiling programs for profiling
  88 </Title>
  89
  90 <Para>
  91 <IndexTerm><Primary>profiling options</Primary></IndexTerm>
  92 <IndexTerm><Primary>options, for profiling</Primary></IndexTerm>
  93 </Para>
  94
  95 <Para>
  96 To make use of the cost centre profiling system <Emphasis>all</Emphasis> modules must
  97 be compiled and linked with the <Option>-prof</Option> option.<IndexTerm><Primary>-prof option</Primary></IndexTerm>
  98 Any <Function>&lowbar;scc&lowbar;</Function> constructs you've put in your source will spring to life.
  99 </Para>
 100
 101 <Para>
 102 Without a <Option>-prof</Option> option, your <Function>&lowbar;scc&lowbar;</Function>s are ignored; so you can
 103 compiled <Function>&lowbar;scc&lowbar;</Function>-laden code without changing it.
 104 </Para>
 105
 106 <Para>
 107 There are a few other profiling-related compilation options.  Use them
 108 <Emphasis>in addition to</Emphasis> <Option>-prof</Option>.  These do not have to be used
 109 consistently for all modules in a program.
 110 </Para>
 111
 112 <Para>
 113 <VariableList>
 114
 115 <VarListEntry>
 116 <Term><Option>-auto</Option>:</Term>
 117 <ListItem>
 118 <Para>
 119 <IndexTerm><Primary>-auto option</Primary></IndexTerm>
 120 <IndexTerm><Primary>cost centres, automatically inserting</Primary></IndexTerm>
 121 GHC will automatically add <Function>&lowbar;scc&lowbar;</Function> constructs for
 122 all top-level, exported functions.
 123 </Para>
 124 </ListItem>
 125 </VarListEntry>
 126 <VarListEntry>
 127 <Term><Option>-auto-all</Option>:</Term>
 128 <ListItem>
 129 <Para>
 130 <IndexTerm><Primary>-auto-all option</Primary></IndexTerm>
 131 <Emphasis>All</Emphasis> top-level functions, exported or not, will be automatically
 132 <Function>&lowbar;scc&lowbar;</Function>'d.
 133 </Para>
 134 </ListItem>
 135 </VarListEntry>
 136 <VarListEntry>
 137 <Term><Option>-caf-all</Option>:</Term>
 138 <ListItem>
 139 <Para>
 140 <IndexTerm><Primary>-caf-all option</Primary></IndexTerm>
 141 The costs of all CAFs in a module are usually attributed to one
 142 ``big'' CAF cost-centre. With this option, all CAFs get their own cost-centre.
 143 An ``if all else fails'' option&hellip;
 144 </Para>
 145 </ListItem>
 146 </VarListEntry>
 147 <VarListEntry>
 148 <Term><Option>-ignore-scc</Option>:</Term>
 149 <ListItem>
 150 <Para>
 151 <IndexTerm><Primary>-ignore-scc option</Primary></IndexTerm>
 152 Ignore any <Function>&lowbar;scc&lowbar;</Function> constructs,
 153 so a module which already has <Function>&lowbar;scc&lowbar;</Function>s can be
 154 compiled for profiling with the annotations ignored.
 155 </Para>
 156 </ListItem>
 157 </VarListEntry>
 158 <VarListEntry>
 159 <Term><Option>-G&lt;group&gt;</Option>:</Term>
 160 <ListItem>
 161 <Para>
 162 <IndexTerm><Primary>-G&lt;group&gt; option</Primary></IndexTerm>
 163 Specifies the <Literal>&lt;group&gt;</Literal> to be attached to all the cost-centres
 164 declared in the module. If no group is specified it defaults to the
 165 module name.
 166 </Para>
 167 </ListItem>
 168 </VarListEntry>
 169 </VariableList>
 170 </Para>
 171
 172 <Para>
 173 In addition to the <Option>-prof</Option> option your system might be setup to enable
 174 you to compile and link with the <Option>-prof-details</Option> <IndexTerm><Primary>-prof-details
 175 option</Primary></IndexTerm> option instead. This enables additional detailed counts
 176 to be reported with the <Option>-P</Option> RTS option.
 177 </Para>
 178
 179 </Sect1>
 180
 181 <Sect1 id="prof-rts-options">
 182 <Title>How to control your profiled program at runtime
 183 </Title>
 184
 185 <Para>
 186 <IndexTerm><Primary>profiling RTS options</Primary></IndexTerm>
 187 <IndexTerm><Primary>RTS options, for profiling</Primary></IndexTerm>
 188 </Para>
 189
 190 <Para>
 191 It isn't enough to compile your program for profiling with <Option>-prof</Option>!
 192 </Para>
 193
 194 <Para>
 195 When you <Emphasis>run</Emphasis> your profiled program, you must tell the runtime
 196 system (RTS) what you want to profile (e.g., time and/or space), and
 197 how you wish the collected data to be reported.  You also may wish to
 198 set the sampling interval used in time profiling.
 199 </Para>
 200
 201 <Para>
 202 Executive summary: <Command>./a.out +RTS -pT</Command> produces a time profile in
 203 <Filename>a.out.prof</Filename>; <Command>./a.out +RTS -hC</Command> produces space-profiling
 204 info which can be mangled by <Command>hp2ps</Command> and viewed with <Command>ghostview</Command>
 205 (or equivalent).
 206 </Para>
 207
 208 <Para>
 209 Profiling runtime flags are passed to your program between the usual
 210 <Option>+RTS</Option> and <Option>-RTS</Option> options.
 211 </Para>
 212
 213 <Para>
 214 <VariableList>
 215
 216 <VarListEntry>
 217 <Term><Option>-p&lt;sort&gt;</Option> or <Option>-P&lt;sort&gt;</Option>:</Term>
 218 <ListItem>
 219 <Para>
 220 <IndexTerm><Primary>-p&lt;sort&gt; RTS option (profiling)</Primary></IndexTerm>
 221 <IndexTerm><Primary>-P&lt;sort&gt; RTS option (profiling)</Primary></IndexTerm>
 222 <IndexTerm><Primary>time profile</Primary></IndexTerm>
 223 <IndexTerm><Primary>serial time profile</Primary></IndexTerm>
 224 The <Option>-p?</Option> option produces a standard <Emphasis>time profile</Emphasis> report.
 225 It is written into the file <Filename>&lt;program&gt;@.prof</Filename>.
 226 </Para>
 227
 228 <Para>
 229 The <Option>-P?</Option> option produces a more detailed report containing the
 230 actual time and allocation data as well.  (Not used much.)
 231 </Para>
 232
 233 <Para>
 234 The <Literal>&lt;sort&gt;</Literal> indicates how the cost centres are to be sorted in the
 235 report. Valid <Literal>&lt;sort&gt;</Literal> options are:
 236 <VariableList>
 237
 238 <VarListEntry>
 239 <Term><Option>T</Option>:</Term>
 240 <ListItem>
 241 <Para>
 242 by time, largest first (the default);
 243 </Para>
 244 </ListItem>
 245 </VarListEntry>
 246 <VarListEntry>
 247 <Term><Option>A</Option>:</Term>
 248 <ListItem>
 249 <Para>
 250 by bytes allocated, largest first;
 251 </Para>
 252 </ListItem>
 253 </VarListEntry>
 254 <VarListEntry>
 255 <Term><Option>C</Option>:</Term>
 256 <ListItem>
 257 <Para>
 258 alphabetically by group, module and cost centre.
 259 </Para>
 260 </ListItem>
 261 </VarListEntry>
 262 </VariableList>
 263 </Para>
 264 </ListItem>
 265 </VarListEntry>
 266 <VarListEntry>
 267 <Term><Option>-i&lt;secs&gt;</Option>:</Term>
 268 <ListItem>
 269 <Para>
 270 <IndexTerm><Primary>-i&lt;secs&gt; RTS option
 271 (profiling)</Primary></IndexTerm> Set the profiling (sampling) interval to <Literal>&lt;secs&gt;</Literal>
 272 seconds (the default is 1&nbsp;second).  Fractions are allowed: for example
 273 <Option>-i0.2</Option> will get 5 samples per second.
 274 </Para>
 275 </ListItem>
 276 </VarListEntry>
 277 <VarListEntry>
 278 <Term><Option>-h&lt;break-down&gt;</Option>:</Term>
 279 <ListItem>
 280 <Para>
 281 <IndexTerm><Primary>-h&lt;break-down&gt; RTS option (profiling)</Primary></IndexTerm>
 282 <IndexTerm><Primary>heap profile</Primary></IndexTerm>
 283 </Para>
 284
 285 <Para>
 286 Produce a detailed <Emphasis>space profile</Emphasis> of the heap occupied by live
 287 closures. The profile is written to the file <Filename>&lt;program&gt;@.hp</Filename> from
 288 which a PostScript graph can be produced using <Command>hp2ps</Command> (see
 289 <XRef LinkEnd="hp2ps">).
 290 </Para>
 291
 292 <Para>
 293 The heap space profile may be broken down by different criteria:
 294 <VariableList>
 295
 296 <VarListEntry>
 297 <Term><Option>-hC</Option>:</Term>
 298 <ListItem>
 299 <Para>
 300 cost centre which produced the closure (the default).
 301 </Para>
 302 </ListItem>
 303 </VarListEntry>
 304 <VarListEntry>
 305 <Term><Option>-hM</Option>:</Term>
 306 <ListItem>
 307 <Para>
 308 cost centre module which produced the closure.
 309 </Para>
 310 </ListItem>
 311 </VarListEntry>
 312 <VarListEntry>
 313 <Term><Option>-hG</Option>:</Term>
 314 <ListItem>
 315 <Para>
 316 cost centre group which produced the closure.
 317 </Para>
 318 </ListItem>
 319 </VarListEntry>
 320 <VarListEntry>
 321 <Term><Option>-hD</Option>:</Term>
 322 <ListItem>
 323 <Para>
 324 closure description&mdash;a string describing the closure.
 325 </Para>
 326 </ListItem>
 327 </VarListEntry>
 328 <VarListEntry>
 329 <Term><Option>-hY</Option>:</Term>
 330 <ListItem>
 331 <Para>
 332 closure type&mdash;a string describing the closure's type.
 333 </Para>
 334 </ListItem>
 335 </VarListEntry>
 336 </VariableList>
 337 By default all live closures in the heap are profiled, but particular
 338 closures of interest can be selected (see below).
 339 </Para>
 340 </ListItem>
 341 </VarListEntry>
 342 </VariableList>
 343 </Para>
 344
 345 <Para>
 346 Heap (space) profiling uses hash tables. If these tables
 347 should fill the run will abort. The
 348 <Option>-z&lt;tbl&gt;&lt;size&gt;</Option><IndexTerm><Primary>-z&lt;tbl&gt;&lt;size&gt; RTS option (profiling)</Primary></IndexTerm> option is used to
 349 increase the size of the relevant hash table (<Literal>C</Literal>, <Literal>M</Literal>,
 350 <Literal>G</Literal>, <Literal>D</Literal> or <Literal>Y</Literal>, defined as for <Literal>&lt;break-down&gt;</Literal> above). The
 351 actual size used is the next largest power of 2.
 352 </Para>
 353
 354 <Para>
 355 The heap profile can be restricted to particular closures of interest.
 356 The closures of interest can selected by the attached cost centre
 357 (module:label, module and group), closure category (description, type,
 358 and kind) using the following options:
 359 </Para>
 360
 361 <Para>
 362 <VariableList>
 363
 364 <VarListEntry>
 365 <Term><Option>-c&lcub;&lt;mod&gt;:&lt;lab&gt;,&lt;mod&gt;:&lt;lab&gt;...</Option>&rcub;:</Term>
 366 <ListItem>
 367 <Para>
 368 <IndexTerm><Primary>-c&lcub;&lt;lab&gt;</Primary></IndexTerm> RTS option (profiling)&rcub;
 369 Selects individual cost centre(s).
 370 </Para>
 371 </ListItem>
 372 </VarListEntry>
 373 <VarListEntry>
 374 <Term><Option>-m&lcub;&lt;mod&gt;,&lt;mod&gt;...</Option>&rcub;:</Term>
 375 <ListItem>
 376 <Para>
 377 <IndexTerm><Primary>-m&lcub;&lt;mod&gt;</Primary></IndexTerm> RTS option (profiling)&rcub;
 378 Selects all cost centres from the module(s) specified.
 379 </Para>
 380 </ListItem>
 381 </VarListEntry>
 382 <VarListEntry>
 383 <Term><Option>-g&lcub;&lt;grp&gt;,&lt;grp&gt;...</Option>&rcub;:</Term>
 384 <ListItem>
 385 <Para>
 386 <IndexTerm><Primary>-g&lcub;&lt;grp&gt;</Primary></IndexTerm> RTS option (profiling)&rcub;
 387 Selects all cost centres from the groups(s) specified.
 388 </Para>
 389 </ListItem>
 390 </VarListEntry>
 391 <VarListEntry>
 392 <Term><Option>-d&lcub;&lt;des&gt;,&lt;des&gt;...</Option>&rcub;:</Term>
 393 <ListItem>
 394 <Para>
 395 <IndexTerm><Primary>-d&lcub;&lt;des&gt;</Primary></IndexTerm> RTS option (profiling)&rcub;
 396 Selects closures which have one of the specified descriptions.
 397 </Para>
 398 </ListItem>
 399 </VarListEntry>
 400 <VarListEntry>
 401 <Term><Option>-y&lcub;&lt;typ&gt;,&lt;typ&gt;...</Option>&rcub;:</Term>
 402 <ListItem>
 403 <Para>
 404 <IndexTerm><Primary>-y&lcub;&lt;typ&gt;</Primary></IndexTerm> RTS option (profiling)&rcub;
 405 Selects closures which have one of the specified type descriptions.
 406 </Para>
 407 </ListItem>
 408 </VarListEntry>
 409 <VarListEntry>
 410 <Term><Option>-k&lcub;&lt;knd&gt;,&lt;knd&gt;...</Option>&rcub;:</Term>
 411 <ListItem>
 412 <Para>
 413 <IndexTerm><Primary>-k&lcub;&lt;knd&gt;</Primary></IndexTerm> RTS option (profiling)&rcub;
 414 Selects closures which are of one of the specified closure kinds.
 415 Valid closure kinds are <Literal>CON</Literal> (constructor), <Literal>FN</Literal> (manifest
 416 function), <Literal>PAP</Literal> (partial application), <Literal>BH</Literal> (black hole) and
 417 <Literal>THK</Literal> (thunk).
 418 </Para>
 419 </ListItem>
 420 </VarListEntry>
 421 </VariableList>
 422 </Para>
 423
 424 <Para>
 425 The space occupied by a closure will be reported in the heap profile
 426 if the closure satisfies the following logical expression:
 427 </Para>
 428
 429 <Para>
 430 <Quote>(&lsqb;-c&rsqb; or &lsqb;-m&rsqb; or &lsqb;-g&rsqb;) and (&lsqb;-d&rsqb; or &lsqb;-y&rsqb; or &lsqb;-k&rsqb;)</Quote>
 431 </Para>
 432
 433 <Para>
 434 where a particular option is true if the closure (or its attached cost
 435 centre) is selected by the option (or the option is not specified).
 436 </Para>
 437
 438 </Sect1>
 439
 440 <Sect1 id="prof-output">
 441 <Title>What's in a profiling report?
 442 </Title>
 443
 444 <Para>
 445 <IndexTerm><Primary>profiling report, meaning thereof</Primary></IndexTerm>
 446 </Para>
 447
 448 <Para>
 449 When you run your profiled program with the <Option>-p</Option> RTS option <IndexTerm><Primary>-p
 450 RTS option</Primary></IndexTerm>, you get the following information about your ``cost
 451 centres'':
 452 </Para>
 453
 454 <Para>
 455 <VariableList>
 456
 457 <VarListEntry>
 458 <Term><Literal>COST CENTRE</Literal>:</Term>
 459 <ListItem>
 460 <Para>
 461 The cost-centre's name.
 462 </Para>
 463 </ListItem>
 464 </VarListEntry>
 465 <VarListEntry>
 466 <Term><Literal>MODULE</Literal>:</Term>
 467 <ListItem>
 468 <Para>
 469 The module associated with the cost-centre;
 470 important mostly if you have identically-named cost-centres in
 471 different modules.
 472 </Para>
 473 </ListItem>
 474 </VarListEntry>
 475 <VarListEntry>
 476 <Term><Literal>scc</Literal>:</Term>
 477 <ListItem>
 478 <Para>
 479 How many times this cost-centre was entered; think
 480 of it as ``I got to the <Function>&lowbar;scc&lowbar;</Function> construct this many times&hellip;''
 481 </Para>
 482 </ListItem>
 483 </VarListEntry>
 484 <VarListEntry>
 485 <Term><Literal>&percnt;time</Literal>:</Term>
 486 <ListItem>
 487 <Para>
 488 What part of the time was spent in this cost-centre (see also ``ticks,''
 489 below).
 490 </Para>
 491 </ListItem>
 492 </VarListEntry>
 493 <VarListEntry>
 494 <Term><Literal>&percnt;alloc</Literal>:</Term>
 495 <ListItem>
 496 <Para>
 497 What part of the memory allocation was done in this cost-centre
 498 (see also ``bytes,'' below).
 499 </Para>
 500 </ListItem>
 501 </VarListEntry>
 502 <VarListEntry>
 503 <Term><Literal>inner</Literal>:</Term>
 504 <ListItem>
 505 <Para>
 506 How many times this cost-centre ``passed control'' to an inner
 507 cost-centre; for example, <Literal>scc=4</Literal> plus <Literal>subscc=8</Literal> means
 508 ``This <Literal>&lowbar;scc&lowbar;</Literal> was entered four times, but went out to
 509 other <Literal>&lowbar;scc&lowbar;s</Literal> eight times.''
 510 </Para>
 511 </ListItem>
 512 </VarListEntry>
 513 <VarListEntry>
 514 <Term><Literal>cafs</Literal>:</Term>
 515 <ListItem>
 516 <Para>
 517 <IndexTerm><Primary>CAF, profiling</Primary></IndexTerm>
 518 How many CAFs this cost centre evaluated.
 519 </Para>
 520 </ListItem>
 521 </VarListEntry>
 522 <VarListEntry>
 523 <Term><Literal>dicts</Literal>:</Term>
 524 <ListItem>
 525 <Para>
 526 <IndexTerm><Primary>Dictionaries, profiling</Primary></IndexTerm>
 527 How many dictionaries this cost centre evaluated.
 528 </Para>
 529 </ListItem>
 530 </VarListEntry>
 531 </VariableList>
 532 </Para>
 533
 534 <Para>
 535 In addition you can use the <Option>-P</Option> RTS option <IndexTerm><Primary></Primary></IndexTerm> to get the following additional information:
 536 <VariableList>
 537
 538 <VarListEntry>
 539 <Term><Literal>ticks</Literal>:</Term>
 540 <ListItem>
 541 <Para>
 542 The raw number of time ``ticks'' which were
 543 attributed to this cost-centre; from this, we get the <Literal>&percnt;time</Literal>
 544 figure mentioned above.
 545 </Para>
 546 </ListItem>
 547 </VarListEntry>
 548 <VarListEntry>
 549 <Term><Literal>bytes</Literal>:</Term>
 550 <ListItem>
 551 <Para>
 552 Number of bytes allocated in the heap while in
 553 this cost-centre; again, this is the raw number from which we
 554 get the <Literal>&percnt;alloc</Literal> figure mentioned above.
 555 </Para>
 556 </ListItem>
 557 </VarListEntry>
 558 </VariableList>
 559 </Para>
 560
 561 <Para>
 562 Finally if you built your program with <Option>-prof-details</Option>
 563 <IndexTerm><Primary></Primary></IndexTerm> the <Option>-P</Option> RTS option will also
 564 produce the following information:
 565 <VariableList>
 566
 567 <VarListEntry>
 568 <Term><Literal>closures</Literal>:</Term>
 569 <ListItem>
 570 <Para>
 571 <IndexTerm><Primary>closures, profiling</Primary></IndexTerm>
 572 How many heap objects were allocated; these objects may be of varying
 573 size.  If you divide the number of bytes (mentioned below) by this
 574 number of ``closures'', then you will get the average object size.
 575 (Not too interesting, but still&hellip;)
 576 </Para>
 577 </ListItem>
 578 </VarListEntry>
 579 <VarListEntry>
 580 <Term><Literal>thunks</Literal>:</Term>
 581 <ListItem>
 582 <Para>
 583 <IndexTerm><Primary>thunks, profiling</Primary></IndexTerm>
 584 How many times we entered (evaluated) a thunk&mdash;an unevaluated
 585 object in the heap&mdash;while we were in this cost-centre.
 586 </Para>
 587 </ListItem>
 588 </VarListEntry>
 589 <VarListEntry>
 590 <Term><Literal>funcs</Literal>:</Term>
 591 <ListItem>
 592 <Para>
 593 <IndexTerm><Primary>functions, profiling</Primary></IndexTerm>
 594 How many times we entered (evaluated) a function while we we in this
 595 cost-centre.  (In Haskell, functions are first-class values and may be
 596 passed as arguments, returned as results, evaluated, and generally
 597 manipulated just like data values)
 598 </Para>
 599 </ListItem>
 600 </VarListEntry>
 601 <VarListEntry>
 602 <Term><Literal>PAPs</Literal>:</Term>
 603 <ListItem>
 604 <Para>
 605 <IndexTerm><Primary>partial applications, profiling</Primary></IndexTerm>
 606 How many times we entered (evaluated) a partial application (PAP), i.e.,
 607 a function applied to fewer arguments than it needs.  For example, <Literal>Int</Literal>
 608 addition applied to one argument would be a PAP.  A PAP is really
 609 just a particular form for a function.
 610 </Para>
 611 </ListItem>
 612 </VarListEntry>
 613 </VariableList>
 614 </Para>
 615
 616 </Sect1>
 617
 618 <Sect1 id="prof-graphs">
 619 <Title>Producing graphical heap profiles
 620 </Title>
 621
 622 <Para>
 623 <IndexTerm><Primary>heap profiles, producing</Primary></IndexTerm>
 624 </Para>
 625
 626 <Para>
 627 Utility programs which produce graphical profiles.
 628 </Para>
 629
 630 <Sect2 id="hp2ps">
 631 <Title><Command>hp2ps</Command>--heap profile to PostScript
 632 </Title>
 633
 634 <Para>
 635 <IndexTerm><Primary>hp2ps (utility)</Primary></IndexTerm>
 636 <IndexTerm><Primary>heap profiles</Primary></IndexTerm>
 637 <IndexTerm><Primary>PostScript, from heap profiles</Primary></IndexTerm>
 638 </Para>
 639
 640 <Para>
 641 Usage:
 642 </Para>
 643
 644 <Para>
 645
 646 <Screen>
 647 hp2ps [flags] [&#60;file&#62;[.stat]]
 648 </Screen>
 649
 650 </Para>
 651
 652 <Para>
 653 The program <Command>hp2ps</Command><IndexTerm><Primary>hp2ps program</Primary></IndexTerm> converts a heap profile
 654 as produced by the <Option>-h&lt;break-down&gt;</Option><IndexTerm><Primary>-h&lt;break-down&gt; RTS
 655 option</Primary></IndexTerm> runtime option into a PostScript graph of the heap
 656 profile. By convention, the file to be processed by <Command>hp2ps</Command> has a
 657 <Filename>.hp</Filename> extension. The PostScript output is written to <Filename>&lt;file&gt;@.ps</Filename>. If
 658 <Filename>&lt;file&gt;</Filename> is omitted entirely, then the program behaves as a filter.
 659 </Para>
 660
 661 <Para>
 662 <Command>hp2ps</Command> is distributed in <Filename>ghc/utils/hp2ps</Filename> in a GHC source
 663 distribution. It was originally developed by Dave Wakeling as part of
 664 the HBC/LML heap profiler.
 665 </Para>
 666
 667 <Para>
 668 The flags are:
 669 <VariableList>
 670
 671 <VarListEntry>
 672 <Term><Option>-d</Option></Term>
 673 <ListItem>
 674 <Para>
 675 In order to make graphs more readable, <Command>hp2ps</Command> sorts the shaded
 676 bands for each identifier. The default sort ordering is for the bands
 677 with the largest area to be stacked on top of the smaller ones.  The
 678 <Option>-d</Option> option causes rougher bands (those representing series of
 679 values with the largest standard deviations) to be stacked on top of
 680 smoother ones.
 681 </Para>
 682 </ListItem>
 683 </VarListEntry>
 684 <VarListEntry>
 685 <Term><Option>-b</Option></Term>
 686 <ListItem>
 687 <Para>
 688 Normally, <Command>hp2ps</Command> puts the title of the graph in a small box at the
 689 top of the page. However, if the JOB string is too long to fit in a
 690 small box (more than 35 characters), then
 691 <Command>hp2ps</Command> will choose to use a big box instead.  The <Option>-b</Option>
 692 option forces <Command>hp2ps</Command> to use a big box.
 693 </Para>
 694 </ListItem>
 695 </VarListEntry>
 696 <VarListEntry>
 697 <Term><Option>-e&lt;float&gt;[in&verbar;mm&verbar;pt]</Option></Term>
 698 <ListItem>
 699 <Para>
 700 Generate encapsulated PostScript suitable for inclusion in LaTeX
 701 documents.  Usually, the PostScript graph is drawn in landscape mode
 702 in an area 9 inches wide by 6 inches high, and <Command>hp2ps</Command> arranges
 703 for this area to be approximately centred on a sheet of a4 paper.
 704 This format is convenient of studying the graph in detail, but it is
 705 unsuitable for inclusion in LaTeX documents.  The <Option>-e</Option> option
 706 causes the graph to be drawn in portrait mode, with float specifying
 707 the width in inches, millimetres or points (the default).  The
 708 resulting PostScript file conforms to the Encapsulated PostScript
 709 (EPS) convention, and it can be included in a LaTeX document using
 710 Rokicki's dvi-to-PostScript converter <Command>dvips</Command>.
 711 </Para>
 712 </ListItem>
 713 </VarListEntry>
 714 <VarListEntry>
 715 <Term><Option>-g</Option></Term>
 716 <ListItem>
 717 <Para>
 718 Create output suitable for the <Command>gs</Command> PostScript previewer (or
 719 similar). In this case the graph is printed in portrait mode without
 720 scaling. The output is unsuitable for a laser printer.
 721 </Para>
 722 </ListItem>
 723 </VarListEntry>
 724 <VarListEntry>
 725 <Term><Option>-l</Option></Term>
 726 <ListItem>
 727 <Para>
 728 Normally a profile is limited to 20 bands with additional identifiers
 729 being grouped into an <Literal>OTHER</Literal> band. The <Option>-l</Option> flag removes this
 730 20 band and limit, producing as many bands as necessary. No key is
 731 produced as it won't fit!. It is useful for creation time profiles
 732 with many bands.
 733 </Para>
 734 </ListItem>
 735 </VarListEntry>
 736 <VarListEntry>
 737 <Term><Option>-m&lt;int&gt;</Option></Term>
 738 <ListItem>
 739 <Para>
 740 Normally a profile is limited to 20 bands with additional identifiers
 741 being grouped into an <Literal>OTHER</Literal> band. The <Option>-m</Option> flag specifies an
 742 alternative band limit (the maximum is 20).
 743 </Para>
 744
 745 <Para>
 746 <Option>-m0</Option> requests the band limit to be removed. As many bands as
 747 necessary are produced. However no key is produced as it won't fit! It
 748 is useful for displaying creation time profiles with many bands.
 749 </Para>
 750 </ListItem>
 751 </VarListEntry>
 752 <VarListEntry>
 753 <Term><Option>-p</Option></Term>
 754 <ListItem>
 755 <Para>
 756 Use previous parameters. By default, the PostScript graph is
 757 automatically scaled both horizontally and vertically so that it fills
 758 the page.  However, when preparing a series of graphs for use in a
 759 presentation, it is often useful to draw a new graph using the same
 760 scale, shading and ordering as a previous one. The <Option>-p</Option> flag causes
 761 the graph to be drawn using the parameters determined by a previous
 762 run of <Command>hp2ps</Command> on <Filename>file</Filename>. These are extracted from
 763 <Filename>file@.aux</Filename>.
 764 </Para>
 765 </ListItem>
 766 </VarListEntry>
 767 <VarListEntry>
 768 <Term><Option>-s</Option></Term>
 769 <ListItem>
 770 <Para>
 771 Use a small box for the title.
 772 </Para>
 773 </ListItem>
 774 </VarListEntry>
 775 <VarListEntry>
 776 <Term><Option>-t&lt;float&gt;</Option></Term>
 777 <ListItem>
 778 <Para>
 779 Normally trace elements which sum to a total of less than 1&percnt; of the
 780 profile are removed from the profile. The <Option>-t</Option> option allows this
 781 percentage to be modified (maximum 5&percnt;).
 782 </Para>
 783
 784 <Para>
 785 <Option>-t0</Option> requests no trace elements to be removed from the profile,
 786 ensuring that all the data will be displayed.
 787 </Para>
 788 </ListItem>
 789 </VarListEntry>
 790 <VarListEntry>
 791 <Term><Option>-?</Option></Term>
 792 <ListItem>
 793 <Para>
 794 Print out usage information.
 795 </Para>
 796 </ListItem>
 797 </VarListEntry>
 798 </VariableList>
 799 </Para>
 800
 801 </Sect2>
 802
 803 <Sect2 id="stat2resid">
 804 <Title><Command>stat2resid</Command>&mdash;residency info from GC stats
 805 </Title>
 806
 807 <Para>
 808 <IndexTerm><Primary>stat2resid (utility)</Primary></IndexTerm>
 809 <IndexTerm><Primary>GC stats&mdash;residency info</Primary></IndexTerm>
 810 <IndexTerm><Primary>residency, from GC stats</Primary></IndexTerm>
 811 </Para>
 812
 813 <Para>
 814 Usage:
 815 </Para>
 816
 817 <Para>
 818
 819 <Screen>
 820 stat2resid [&#60;file&#62;[.stat] [&#60;outfile&#62;]]
 821 </Screen>
 822
 823 </Para>
 824
 825 <Para>
 826 The program <Command>stat2resid</Command><IndexTerm><Primary>stat2resid</Primary></IndexTerm> converts a detailed
 827 garbage collection statistics file produced by the
 828 <Option>-S</Option><IndexTerm><Primary>-S RTS option</Primary></IndexTerm> runtime option into a PostScript heap
 829 residency graph. The garbage collection statistics file can be
 830 produced without compiling your program for profiling.
 831 </Para>
 832
 833 <Para>
 834 By convention, the file to be processed by <Command>stat2resid</Command> has a
 835 <Filename>.stat</Filename> extension. If the <Filename>&lt;outfile&gt;</Filename> is not specified the
 836 PostScript will be written to <Filename>&lt;file&gt;@.resid.ps</Filename>. If
 837 <Filename>&lt;file&gt;</Filename> is omitted entirely, then the program behaves as a filter.
 838 </Para>
 839
 840 <Para>
 841 The plot can not be produced from the statistics file for a
 842 generational collector, though a suitable stats file can be produced
 843 using the <Option>-F2s</Option><IndexTerm><Primary>-F2s RTS option</Primary></IndexTerm> runtime option when the
 844 program has been compiled for generational garbage collection (the
 845 default).
 846 </Para>
 847
 848 <Para>
 849 <Command>stat2resid</Command> is distributed in <Filename>ghc/utils/stat2resid</Filename> in a GHC source
 850 distribution.
 851 </Para>
 852
 853 </Sect2>
 854
 855 </Sect1>
 856
 857 <Sect1 id="ticky-ticky">
 858 <Title>Using ``ticky-ticky'' profiling (for implementors)
 859 </Title>
 860
 861 <Para>
 862 <IndexTerm><Primary>ticky-ticky profiling (implementors)</Primary></IndexTerm>
 863 </Para>
 864
 865 <Para>
 866 (ToDo: document properly.)
 867 </Para>
 868
 869 <Para>
 870 It is possible to compile Glasgow Haskell programs so that they will
 871 count lots and lots of interesting things, e.g., number of updates,
 872 number of data constructors entered, etc., etc.  We call this
 873 ``ticky-ticky'' profiling,<IndexTerm><Primary>ticky-ticky profiling</Primary></IndexTerm>
 874 <IndexTerm><Primary>profiling, ticky-ticky</Primary></IndexTerm> because that's the sound a Sun4 makes
 875 when it is running up all those counters (<Emphasis>slowly</Emphasis>).
 876 </Para>
 877
 878 <Para>
 879 Ticky-ticky profiling is mainly intended for implementors; it is quite
 880 separate from the main ``cost-centre'' profiling system, intended for
 881 all users everywhere.
 882 </Para>
 883
 884 <Para>
 885 To be able to use ticky-ticky profiling, you will need to have built
 886 appropriate libraries and things when you made the system.  See
 887 ``Customising what libraries to build,'' in the installation guide.
 888 </Para>
 889
 890 <Para>
 891 To get your compiled program to spit out the ticky-ticky numbers, use
 892 a <Option>-r</Option> RTS option<IndexTerm><Primary>-r RTS option</Primary></IndexTerm>.  See <XRef LinkEnd="runtime-control">.
 893 </Para>
 894
 895 <Para>
 896 Compiling your program with the <Option>-ticky</Option> switch yields an executable
 897 that performs these counts.  Here is a sample ticky-ticky statistics
 898 file, generated by the invocation <Command>foo +RTS -rfoo.ticky</Command>.
 899 </Para>
 900
 901 <Para>
 902
 903 <Screen>
 904  foo +RTS -rfoo.ticky
 905
 906
 907 ALLOCATIONS: 3964631 (11330900 words total: 3999476 admin, 6098829 goods, 1232595 slop)
 908                                 total words:        2     3     4     5    6+
 909   69647 (  1.8%) function values                 50.0  50.0   0.0   0.0   0.0
 910 2382937 ( 60.1%) thunks                           0.0  83.9  16.1   0.0   0.0
 911 1477218 ( 37.3%) data values                     66.8  33.2   0.0   0.0   0.0
 912       0 (  0.0%) big tuples
 913       2 (  0.0%) black holes                      0.0 100.0   0.0   0.0   0.0
 914       0 (  0.0%) prim things
 915   34825 (  0.9%) partial applications             0.0   0.0   0.0 100.0   0.0
 916       2 (  0.0%) thread state objects             0.0   0.0   0.0   0.0 100.0
 917
 918 Total storage-manager allocations: 3647137 (11882004 words)
 919         [551104 words lost to speculative heap-checks]
 920
 921 STACK USAGE:
 922
 923 ENTERS: 9400092  of which 2005772 (21.3%) direct to the entry code
 924                   [the rest indirected via Node's info ptr]
 925 1860318 ( 19.8%) thunks
 926 3733184 ( 39.7%) data values
 927 3149544 ( 33.5%) function values
 928                   [of which 1999880 (63.5%) bypassed arg-satisfaction chk]
 929  348140 (  3.7%) partial applications
 930  308906 (  3.3%) normal indirections
 931       0 (  0.0%) permanent indirections
 932
 933 RETURNS: 5870443
 934 2137257 ( 36.4%) from entering a new constructor
 935                   [the rest from entering an existing constructor]
 936 2349219 ( 40.0%) vectored [the rest unvectored]
 937
 938 RET_NEW:         2137257:  32.5% 46.2% 21.3%  0.0%  0.0%  0.0%  0.0%  0.0%  0.0%
 939 RET_OLD:         3733184:   2.8% 67.9% 29.3%  0.0%  0.0%  0.0%  0.0%  0.0%  0.0%
 940 RET_UNBOXED_TUP:       2:   0.0%  0.0%100.0%  0.0%  0.0%  0.0%  0.0%  0.0%  0.0%
 941
 942 RET_VEC_RETURN : 2349219:   0.0%  0.0%100.0%  0.0%  0.0%  0.0%  0.0%  0.0%  0.0%
 943
 944 UPDATE FRAMES: 2241725 (0 omitted from thunks)
 945 SEQ FRAMES:    1
 946 CATCH FRAMES:  1
 947 UPDATES: 2241725
 948       0 (  0.0%) data values
 949   34827 (  1.6%) partial applications
 950                   [2 in place, 34825 allocated new space]
 951 2206898 ( 98.4%) updates to existing heap objects (46 by squeezing)
 952 UPD_CON_IN_NEW:         0:       0      0      0      0      0      0      0      0      0
 953 UPD_PAP_IN_NEW:     34825:       0      0      0  34825      0      0      0      0      0
 954
 955 NEW GEN UPDATES: 2274700 ( 99.9%)
 956
 957 OLD GEN UPDATES: 1852 (  0.1%)
 958
 959 Total bytes copied during GC: 190096
 960
 961 **************************************************
 962 3647137 ALLOC_HEAP_ctr
 963 11882004 ALLOC_HEAP_tot
 964   69647 ALLOC_FUN_ctr
 965   69647 ALLOC_FUN_adm
 966   69644 ALLOC_FUN_gds
 967   34819 ALLOC_FUN_slp
 968   34831 ALLOC_FUN_hst_0
 969   34816 ALLOC_FUN_hst_1
 970       0 ALLOC_FUN_hst_2
 971       0 ALLOC_FUN_hst_3
 972       0 ALLOC_FUN_hst_4
 973 2382937 ALLOC_UP_THK_ctr
 974       0 ALLOC_SE_THK_ctr
 975  308906 ENT_IND_ctr
 976       0 E!NT_PERM_IND_ctr requires +RTS -Z
 977 [... lots more info omitted ...]
 978       0 GC_SEL_ABANDONED_ctr
 979       0 GC_SEL_MINOR_ctr
 980       0 GC_SEL_MAJOR_ctr
 981       0 GC_FAILED_PROMOTION_ctr
 982   47524 GC_WORDS_COPIED_ctr
 983 </Screen>
 984
 985 </Para>
 986
 987 <Para>
 988 The formatting of the information above the row of asterisks is
 989 subject to change, but hopefully provides a useful human-readable
 990 summary.  Below the asterisks <Emphasis>all counters</Emphasis> maintained by the
 991 ticky-ticky system are dumped, in a format intended to be
 992 machine-readable: zero or more spaces, an integer, a space, the
 993 counter name, and a newline.
 994 </Para>
 995
 996 <Para>
 997 In fact, not <Emphasis>all</Emphasis> counters are necessarily dumped; compile- or
 998 run-time flags can render certain counters invalid.  In this case,
 999 either the counter will simply not appear, or it will appear with a
1000 modified counter name, possibly along with an explanation for the
1001 omission (notice <Literal>ENT&lowbar;PERM&lowbar;IND&lowbar;ctr</Literal> appears with an inserted <Literal>!</Literal>
1002 above).  Software analysing this output should always check that it
1003 has the counters it expects.  Also, beware: some of the counters can
1004 have <Emphasis>large</Emphasis> values!
1005 </Para>
1006
1007 </Sect1>
1008
1009 </Chapter>