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