Fix more documentation wibbles
[ghc.git] / docs / users_guide / profiling.rst
1 .. _profiling:
2
3 Profiling
4 =========
5
6 .. index::
7    single: profiling
8    single: cost-centre profiling
9    single: -p; RTS option
10
11 GHC comes with a time and space profiling system, so that you can answer
12 questions like "why is my program so slow?", or "why is my program using
13 so much memory?".
14
15 Profiling a program is a three-step process:
16
17 1. Re-compile your program for profiling with the :ghc-flag:`-prof` option, and
18    probably one of the options for adding automatic annotations:
19    :ghc-flag:`-fprof-auto` is the most common [1]_.
20
21    If you are using external packages with :command:`cabal`, you may need to
22    reinstall these packages with profiling support; typically this is
23    done with ``cabal install -p package --reinstall``.
24
25 2. Having compiled the program for profiling, you now need to run it to
26    generate the profile. For example, a simple time profile can be
27    generated by running the program with ``+RTS -p`` (see :rts-flag:`-p`), which
28    generates a file named :file:`{prog}.prof` where ⟨prog⟩ is the name of your
29    program (without the ``.exe`` extension, if you are on Windows).
30
31    There are many different kinds of profile that can be generated,
32    selected by different RTS options. We will be describing the various
33    kinds of profile throughout the rest of this chapter. Some profiles
34    require further processing using additional tools after running the
35    program.
36
37 3. Examine the generated profiling information, use the information to
38    optimise your program, and repeat as necessary.
39
40 .. _cost-centres:
41
42 Cost centres and cost-centre stacks
43 -----------------------------------
44
45 GHC's profiling system assigns costs to cost centres. A cost is simply
46 the time or space (memory) required to evaluate an expression. Cost
47 centres are program annotations around expressions; all costs incurred
48 by the annotated expression are assigned to the enclosing cost centre.
49 Furthermore, GHC will remember the stack of enclosing cost centres for
50 any given expression at run-time and generate a call-tree of cost
51 attributions.
52
53 Let's take a look at an example: ::
54
55     main = print (fib 30)
56     fib n = if n < 2 then 1 else fib (n-1) + fib (n-2)
57
58 Compile and run this program as follows:
59
60 .. code-block:: none
61
62     $ ghc -prof -fprof-auto -rtsopts Main.hs
63     $ ./Main +RTS -p
64     121393
65     $
66
67 When a GHC-compiled program is run with the :rts-flag:`-p` RTS option, it
68 generates a file called :file:`prog.prof`. In this case, the file will contain
69 something like this:
70
71 .. code-block:: none
72
73             Wed Oct 12 16:14 2011 Time and Allocation Profiling Report  (Final)
74
75                Main +RTS -p -RTS
76
77             total time  =        0.68 secs   (34 ticks @ 20 ms)
78             total alloc = 204,677,844 bytes  (excludes profiling overheads)
79
80     COST CENTRE MODULE  %time %alloc
81
82     fib         Main    100.0  100.0
83
84
85                                                           individual     inherited
86     COST CENTRE MODULE                  no.     entries  %time %alloc   %time %alloc
87
88     MAIN        MAIN                    102           0    0.0    0.0   100.0  100.0
89      CAF        GHC.IO.Handle.FD        128           0    0.0    0.0     0.0    0.0
90      CAF        GHC.IO.Encoding.Iconv   120           0    0.0    0.0     0.0    0.0
91      CAF        GHC.Conc.Signal         110           0    0.0    0.0     0.0    0.0
92      CAF        Main                    108           0    0.0    0.0   100.0  100.0
93       main      Main                    204           1    0.0    0.0   100.0  100.0
94        fib      Main                    205     2692537  100.0  100.0   100.0  100.0
95
96 The first part of the file gives the program name and options, and the
97 total time and total memory allocation measured during the run of the
98 program (note that the total memory allocation figure isn't the same as
99 the amount of *live* memory needed by the program at any one time; the
100 latter can be determined using heap profiling, which we will describe
101 later in :ref:`prof-heap`).
102
103 The second part of the file is a break-down by cost centre of the most
104 costly functions in the program. In this case, there was only one
105 significant function in the program, namely ``fib``, and it was
106 responsible for 100% of both the time and allocation costs of the
107 program.
108
109 The third and final section of the file gives a profile break-down by
110 cost-centre stack. This is roughly a call-tree profile of the program.
111 In the example above, it is clear that the costly call to ``fib`` came
112 from ``main``.
113
114 The time and allocation incurred by a given part of the program is
115 displayed in two ways: “individual”, which are the costs incurred by the
116 code covered by this cost centre stack alone, and “inherited”, which
117 includes the costs incurred by all the children of this node.
118
119 The usefulness of cost-centre stacks is better demonstrated by modifying
120 the example slightly: ::
121
122     main = print (f 30 + g 30)
123       where
124         f n  = fib n
125         g n  = fib (n `div` 2)
126
127     fib n = if n < 2 then 1 else fib (n-1) + fib (n-2)
128
129 Compile and run this program as before, and take a look at the new
130 profiling results:
131
132 .. code-block:: none
133
134     COST CENTRE MODULE                  no.     entries  %time %alloc   %time %alloc
135
136     MAIN        MAIN                    102           0    0.0    0.0   100.0  100.0
137      CAF        GHC.IO.Handle.FD        128           0    0.0    0.0     0.0    0.0
138      CAF        GHC.IO.Encoding.Iconv   120           0    0.0    0.0     0.0    0.0
139      CAF        GHC.Conc.Signal         110           0    0.0    0.0     0.0    0.0
140      CAF        Main                    108           0    0.0    0.0   100.0  100.0
141       main      Main                    204           1    0.0    0.0   100.0  100.0
142        main.g   Main                    207           1    0.0    0.0     0.0    0.1
143         fib     Main                    208        1973    0.0    0.1     0.0    0.1
144        main.f   Main                    205           1    0.0    0.0   100.0   99.9
145         fib     Main                    206     2692537  100.0   99.9   100.0   99.9
146
147 Now although we had two calls to ``fib`` in the program, it is
148 immediately clear that it was the call from ``f`` which took all the
149 time. The functions ``f`` and ``g`` which are defined in the ``where``
150 clause in ``main`` are given their own cost centres, ``main.f`` and
151 ``main.g`` respectively.
152
153 The actual meaning of the various columns in the output is:
154
155     The number of times this particular point in the call tree was
156     entered.
157
158     The percentage of the total run time of the program spent at this
159     point in the call tree.
160
161     The percentage of the total memory allocations (excluding profiling
162     overheads) of the program made by this call.
163
164     The percentage of the total run time of the program spent below this
165     point in the call tree.
166
167     The percentage of the total memory allocations (excluding profiling
168     overheads) of the program made by this call and all of its
169     sub-calls.
170
171 In addition you can use the :rts-flag:`-P` RTS option to get the
172 following additional information:
173
174 ``ticks``
175     The raw number of time “ticks” which were attributed to this
176     cost-centre; from this, we get the ``%time`` figure mentioned above.
177
178 ``bytes``
179     Number of bytes allocated in the heap while in this cost-centre;
180     again, this is the raw number from which we get the ``%alloc``
181     figure mentioned above.
182
183 What about recursive functions, and mutually recursive groups of
184 functions? Where are the costs attributed? Well, although GHC does keep
185 information about which groups of functions called each other
186 recursively, this information isn't displayed in the basic time and
187 allocation profile, instead the call-graph is flattened into a tree as
188 follows: a call to a function that occurs elsewhere on the current stack
189 does not push another entry on the stack, instead the costs for this
190 call are aggregated into the caller [2]_.
191
192 .. _scc-pragma:
193
194 Inserting cost centres by hand
195 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
196
197 Cost centres are just program annotations. When you say ``-fprof-auto``
198 to the compiler, it automatically inserts a cost centre annotation
199 around every binding not marked INLINE in your program, but you are
200 entirely free to add cost centre annotations yourself.
201
202 The syntax of a cost centre annotation for expressions is ::
203
204     {-# SCC "name" #-} <expression>
205
206 where ``"name"`` is an arbitrary string, that will become the name of
207 your cost centre as it appears in the profiling output, and
208 ``<expression>`` is any Haskell expression. An ``SCC`` annotation
209 extends as far to the right as possible when parsing. (SCC stands for
210 "Set Cost Centre"). The double quotes can be omitted if ``name`` is a
211 Haskell identifier, for example: ::
212
213     {-# SCC id #-} <expression>
214
215 Cost centre annotations can also appear in the top-level or in a
216 declaration context. In that case you need to pass a function name
217 defined in the same module or scope with the annotation. Example: ::
218
219     f x y = ...
220       where
221         g z = ...
222         {-# SCC g #-}
223
224     {-# SCC f #-}
225
226 If you want to give a cost centre different name than the function name,
227 you can pass a string to the annotation ::
228
229     f x y = ...
230     {-# SCC f "cost_centre_name" #-}
231
232 Here is an example of a program with a couple of SCCs: ::
233
234     main :: IO ()
235     main = do let xs = [1..1000000]
236               let ys = [1..2000000]
237               print $ {-# SCC last_xs #-} last xs
238               print $ {-# SCC last_init_xs #-} last $ init xs
239               print $ {-# SCC last_ys #-} last ys
240               print $ {-# SCC last_init_ys #-} last $ init ys
241
242 which gives this profile when run:
243
244 .. code-block:: none
245
246     COST CENTRE     MODULE                  no.     entries  %time %alloc   %time %alloc
247
248     MAIN            MAIN                    102           0    0.0    0.0   100.0  100.0
249      CAF            GHC.IO.Handle.FD        130           0    0.0    0.0     0.0    0.0
250      CAF            GHC.IO.Encoding.Iconv   122           0    0.0    0.0     0.0    0.0
251      CAF            GHC.Conc.Signal         111           0    0.0    0.0     0.0    0.0
252      CAF            Main                    108           0    0.0    0.0   100.0  100.0
253       main          Main                    204           1    0.0    0.0   100.0  100.0
254        last_init_ys Main                    210           1   25.0   27.4    25.0   27.4
255        main.ys      Main                    209           1   25.0   39.2    25.0   39.2
256        last_ys      Main                    208           1   12.5    0.0    12.5    0.0
257        last_init_xs Main                    207           1   12.5   13.7    12.5   13.7
258        main.xs      Main                    206           1   18.8   19.6    18.8   19.6
259        last_xs      Main                    205           1    6.2    0.0     6.2    0.0
260
261 .. _prof-rules:
262
263 Rules for attributing costs
264 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
265
266 While running a program with profiling turned on, GHC maintains a
267 cost-centre stack behind the scenes, and attributes any costs (memory
268 allocation and time) to whatever the current cost-centre stack is at the
269 time the cost is incurred.
270
271 The mechanism is simple: whenever the program evaluates an expression
272 with an SCC annotation, ``{-# SCC c -#} E``, the cost centre ``c`` is
273 pushed on the current stack, and the entry count for this stack is
274 incremented by one. The stack also sometimes has to be saved and
275 restored; in particular when the program creates a thunk (a lazy
276 suspension), the current cost-centre stack is stored in the thunk, and
277 restored when the thunk is evaluated. In this way, the cost-centre stack
278 is independent of the actual evaluation order used by GHC at runtime.
279
280 At a function call, GHC takes the stack stored in the function being
281 called (which for a top-level function will be empty), and *appends* it
282 to the current stack, ignoring any prefix that is identical to a prefix
283 of the current stack.
284
285 We mentioned earlier that lazy computations, i.e. thunks, capture the
286 current stack when they are created, and restore this stack when they
287 are evaluated. What about top-level thunks? They are "created" when the
288 program is compiled, so what stack should we give them? The technical
289 name for a top-level thunk is a CAF ("Constant Applicative Form"). GHC
290 assigns every CAF in a module a stack consisting of the single cost
291 centre ``M.CAF``, where ``M`` is the name of the module. It is also
292 possible to give each CAF a different stack, using the option
293 :ghc-flag:`-fprof-cafs`. This is especially useful when
294 compiling with :ghc-flag:`-ffull-laziness` (as is default with :ghc-flag:`-O`
295 and higher), as constants in function bodies will be lifted to the top-level
296 and become CAFs. You will probably need to consult the Core
297 (:ghc-flag:`-ddump-simpl`) in order to determine what these CAFs correspond to.
298
299 .. index::
300    single: -fprof-cafs
301
302 .. _prof-compiler-options:
303
304 Compiler options for profiling
305 ------------------------------
306
307 .. index::
308    single: profiling; options
309    single: options; for profiling
310
311 .. ghc-flag:: -prof
312
313     To make use of the profiling system *all* modules must be compiled
314     and linked with the :ghc-flag:`-prof` option. Any ``SCC`` annotations you've
315     put in your source will spring to life.
316
317     Without a :ghc-flag:`-prof` option, your ``SCC``\ s are ignored; so you can
318     compile ``SCC``-laden code without changing it.
319
320 There are a few other profiling-related compilation options. Use them
321 *in addition to* :ghc-flag:`-prof`. These do not have to be used consistently
322 for all modules in a program.
323
324 .. ghc-flag:: -fprof-auto
325
326     *All* bindings not marked INLINE, whether exported or not, top level
327     or nested, will be given automatic ``SCC`` annotations. Functions
328     marked INLINE must be given a cost centre manually.
329
330 .. ghc-flag:: -fprof-auto-top
331
332     .. index::
333        single: cost centres; automatically inserting
334
335     GHC will automatically add ``SCC`` annotations for all top-level
336     bindings not marked INLINE. If you want a cost centre on an INLINE
337     function, you have to add it manually.
338
339 .. ghc-flag:: -fprof-auto-exported
340
341     .. index::
342        single: cost centres; automatically inserting
343
344     GHC will automatically add ``SCC`` annotations for all exported
345     functions not marked INLINE. If you want a cost centre on an INLINE
346     function, you have to add it manually.
347
348 .. ghc-flag:: -fprof-auto-calls
349
350     .. index::
351        single: -fprof-auto-calls
352
353     Adds an automatic ``SCC`` annotation to all *call sites*. This is
354     particularly useful when using profiling for the purposes of
355     generating stack traces; see the function :base-ref:`traceStack <Debug-Trace.html#traceShow>` in the
356     module ``Debug.Trace``, or the :rts-flag:`-xc` RTS flag
357     (:ref:`rts-options-debugging`) for more details.
358
359 .. ghc-flag:: -fprof-cafs
360
361     The costs of all CAFs in a module are usually attributed to one
362     "big" CAF cost-centre. With this option, all CAFs get their own
363     cost-centre. An “if all else fails” option…
364
365 .. ghc-flag:: -fno-prof-auto
366
367     Disables any previous :ghc-flag:`-fprof-auto`, :ghc-flag:`-fprof-auto-top`, or
368     :ghc-flag:`-fprof-auto-exported` options.
369
370 .. ghc-flag:: -fno-prof-cafs
371
372     Disables any previous :ghc-flag:`-fprof-cafs` option.
373
374 .. ghc-flag:: -fno-prof-count-entries
375
376     .. index::
377        single: -fno-prof-count-entries
378
379     Tells GHC not to collect information about how often functions are
380     entered at runtime (the "entries" column of the time profile), for
381     this module. This tends to make the profiled code run faster, and
382     hence closer to the speed of the unprofiled code, because GHC is
383     able to optimise more aggressively if it doesn't have to maintain
384     correct entry counts. This option can be useful if you aren't
385     interested in the entry counts (for example, if you only intend to
386     do heap profiling).
387
388 .. _prof-time-options:
389
390 Time and allocation profiling
391 -----------------------------
392
393 To generate a time and allocation profile, give one of the following RTS
394 options to the compiled program when you run it (RTS options should be
395 enclosed between ``+RTS ... -RTS`` as usual):
396
397 .. rts-flag:: -p
398               -P
399               -pa
400
401     .. index::
402        single: time profile
403
404     The :rts-flag:`-p` option produces a standard *time profile* report. It is
405     written into the file :file:`<stem>.prof`; the stem is taken to be the
406     program name by default, but can be overridden by the :rts-flag:`-po
407     ⟨stem⟩` flag.
408
409     The :rts-flag:`-P` option produces a more detailed report containing the
410     actual time and allocation data as well. (Not used much.)
411
412     The :rts-flag:`-pa` option produces the most detailed report containing all
413     cost centres in addition to the actual time and allocation data.
414
415 .. rts-flag:: -pj
416
417     The :rts-flag:`-pj` option produces a time/allocation profile report in JSON
418     format written into the file :file:`<program>.prof`.
419
420 .. rts-flag:: -po ⟨stem⟩
421
422     The :rts-flag:`-po ⟨stem⟩` option overrides the stem used to form the
423     output file paths for the cost-centre profiler (see :rts-flag:`-p` and
424     :rts-flag:`-pj` flags above) and heap profiler (see :rts-flag:`-h`).
425
426     For instance, running a program with ``+RTS -h -p -pohello-world`` would
427     produce a heap profile named :file:`hello-world.hp` and a cost-centre
428     profile named :file:`hello-world.prof`.
429
430 .. rts-flag:: -V ⟨secs⟩
431
432     :default: 0.02
433
434     Sets the interval that the RTS clock ticks at, which is also the sampling
435     interval of the time and allocation profile. The default is 0.02 seconds.
436     The runtime uses a single timer signal to count ticks; this timer signal is
437     used to control the context switch timer (:ref:`using-concurrent`) and the
438     heap profiling timer :ref:`rts-options-heap-prof`. Also, the time profiler
439     uses the RTS timer signal directly to record time profiling samples.
440
441     Normally, setting the :rts-flag:`-V ⟨secs⟩` option directly is not
442     necessary: the resolution of the RTS timer is adjusted automatically if a
443     short interval is requested with the :rts-flag:`-C ⟨s⟩` or :rts-flag:`-i
444     ⟨secs⟩` options. However, setting :rts-flag:`-V ⟨secs⟩` is required in
445     order to increase the resolution of the time profiler.
446
447     Using a value of zero disables the RTS clock completely, and has the
448     effect of disabling timers that depend on it: the context switch
449     timer and the heap profiling timer. Context switches will still
450     happen, but deterministically and at a rate much faster than normal.
451     Disabling the interval timer is useful for debugging, because it
452     eliminates a source of non-determinism at runtime.
453
454
455 .. rts-flag:: -xc
456
457     This option causes the runtime to print out the current cost-centre
458     stack whenever an exception is raised. This can be particularly
459     useful for debugging the location of exceptions, such as the
460     notorious ``Prelude.head: empty list`` error. See
461     :ref:`rts-options-debugging`.
462
463
464 JSON profile format
465 ~~~~~~~~~~~~~~~~~~~
466
467 When invoked with the :rts-flag:`-pj` flag the runtime will emit the cost-centre
468 profile in a machine-readable JSON format. The top-level object of this format
469 has the following properties,
470
471 ``program`` (string)
472     The name of the program
473 ``arguments`` (list of strings)
474     The command line arguments passed to the program
475 ``rts_arguments`` (list of strings)
476     The command line arguments passed to the runtime system
477 ``initial_capabilities`` (integral number)
478     How many capabilities the program was started with (e.g. using the
479     :rts-flag:`-N ⟨x⟩` option). Note that the number of capabilities may change
480     during execution due to the ``setNumCapabilities`` function.
481 ``total_time`` (number)
482     The total wall time of the program's execution in seconds.
483 ``total_ticks`` (integral number)
484     How many profiler "ticks" elapsed over the course of the program's execution.
485 ``end_time`` (number)
486     The approximate time when the program finished execution as a UNIX epoch timestamp.
487 ``tick_interval`` (float)
488     How much time between profiler ticks.
489 ``total_alloc`` (integer)
490     The cumulative allocations of the program in bytes.
491 ``cost_centres`` (list of objects)
492     A list of the program's cost centres
493 ``profile`` (object)
494     The profile tree itself
495
496 Each entry in ``cost_centres`` is an object describing a cost-centre of the
497 program having the following properies,
498
499 ``id`` (integral number)
500     A unique identifier used to refer to the cost-centre
501 ``is_caf`` (boolean)
502     Whether the cost-centre is a Constant Applicative Form (CAF)
503 ``label`` (string)
504     A descriptive string roughly identifying the cost-centre.
505 ``src_loc`` (string)
506     A string describing the source span enclosing the cost-centre.
507
508 The profile data itself is described by the ``profile`` field, which contains a
509 tree-like object (which we'll call a "cost-centre stack" here) with the
510 following properties,
511
512 ``id`` (integral number)
513     The ``id`` of a cost-centre listed in the ``cost_centres`` list.
514 ``entries`` (integral number)
515     How many times was this cost-centre entered?
516 ``ticks`` (integral number)
517     How many ticks was the program's execution inside of this cost-centre? This
518     does not include child cost-centres.
519 ``alloc`` (integral number)
520     How many bytes did the program allocate while inside of this cost-centre?
521     This does not include allocations while in child cost-centres.
522 ``children`` (list)
523     A list containing child cost-centre stacks.
524
525 For instance, a simple profile might look like this,
526
527 .. code-block:: json
528
529     {
530       "program": "Main",
531       "arguments": [
532         "nofib/shootout/n-body/Main",
533         "50000"
534       ],
535       "rts_arguments": [
536         "-pj",
537         "-hy"
538       ],
539       "end_time": "Thu Feb 23 17:15 2017",
540       "initial_capabilities": 0,
541       "total_time": 1.7,
542       "total_ticks": 1700,
543       "tick_interval": 1000,
544       "total_alloc": 3770785728,
545       "cost_centres": [
546         {
547           "id": 168,
548           "label": "IDLE",
549           "module": "IDLE",
550           "src_loc": "<built-in>",
551           "is_caf": false
552         },
553         {
554           "id": 156,
555           "label": "CAF",
556           "module": "GHC.Integer.Logarithms.Internals",
557           "src_loc": "<entire-module>",
558           "is_caf": true
559         },
560         {
561           "id": 155,
562           "label": "CAF",
563           "module": "GHC.Integer.Logarithms",
564           "src_loc": "<entire-module>",
565           "is_caf": true
566         },
567         {
568           "id": 154,
569           "label": "CAF",
570           "module": "GHC.Event.Array",
571           "src_loc": "<entire-module>",
572           "is_caf": true
573         }
574       ],
575       "profile": {
576         "id": 162,
577         "entries": 0,
578         "alloc": 688,
579         "ticks": 0,
580         "children": [
581           {
582             "id": 1,
583             "entries": 0,
584             "alloc": 208,
585             "ticks": 0,
586             "children": [
587               {
588                 "id": 22,
589                 "entries": 1,
590                 "alloc": 80,
591                 "ticks": 0,
592                 "children": []
593               }
594             ]
595           },
596           {
597             "id": 42,
598             "entries": 1,
599             "alloc": 1632,
600             "ticks": 0,
601             "children": []
602           }
603         ]
604       }
605     }
606
607
608
609
610
611 .. _prof-heap:
612
613 Profiling memory usage
614 ----------------------
615
616 In addition to profiling the time and allocation behaviour of your
617 program, you can also generate a graph of its memory usage over time.
618 This is useful for detecting the causes of space leaks, when your
619 program holds on to more memory at run-time that it needs to. Space
620 leaks lead to slower execution due to heavy garbage collector activity,
621 and may even cause the program to run out of memory altogether.
622
623 To generate a heap profile from your program:
624
625 1. Compile the program for profiling (:ref:`prof-compiler-options`).
626
627 2. Run it with one of the heap profiling options described below (eg.
628    :rts-flag:`-h` for a basic producer profile). This generates the file
629    :file:`{prog}.hp`.
630
631    If the :ref:`event log <rts-eventlog>` is enabled (with the :rts-flag:`-l`
632    runtime system flag) heap samples will additionally be emitted to the GHC
633    event log (see :ref:`heap-profiler-events` for details about event format).
634
635 3. Run :command:`hp2ps` to produce a Postscript file, :file:`{prog}.ps`. The
636    :command:`hp2ps` utility is described in detail in :ref:`hp2ps`.
637
638 4. Display the heap profile using a postscript viewer such as Ghostview,
639    or print it out on a Postscript-capable printer.
640
641 For example, here is a heap profile produced for the ``sphere`` program
642 from GHC's ``nofib`` benchmark suite,
643
644 .. image:: images/prof_scc.*
645
646 You might also want to take a look at
647 `hp2any <http://www.haskell.org/haskellwiki/Hp2any>`__, a more advanced
648 suite of tools (not distributed with GHC) for displaying heap profiles.
649
650 .. _rts-options-heap-prof:
651
652 RTS options for heap profiling
653 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
654
655 There are several different kinds of heap profile that can be generated.
656 All the different profile types yield a graph of live heap against time,
657 but they differ in how the live heap is broken down into bands. The
658 following RTS options select which break-down to use:
659
660 .. rts-flag:: -hc
661               -h
662
663     (can be shortened to :rts-flag:`-h`). Breaks down the graph by the
664     cost-centre stack which produced the data.
665
666 .. rts-flag:: -hm
667
668     Break down the live heap by the module containing the code which
669     produced the data.
670
671 .. rts-flag:: -hd
672
673     Breaks down the graph by closure description. For actual data, the
674     description is just the constructor name, for other closures it is a
675     compiler-generated string identifying the closure.
676
677 .. rts-flag:: -hy
678
679     Breaks down the graph by type. For closures which have function type
680     or unknown/polymorphic type, the string will represent an
681     approximation to the actual type.
682
683 .. rts-flag:: -hr
684
685     Break down the graph by retainer set. Retainer profiling is
686     described in more detail below (:ref:`retainer-prof`).
687
688 .. rts-flag:: -hb
689
690     Break down the graph by biography. Biographical profiling is
691     described in more detail below (:ref:`biography-prof`).
692
693 .. rts-flag:: -l
694
695     :noindex:
696
697     .. index::
698        single: eventlog; and heap profiling
699
700     Emit profile samples to the :ref:`GHC event log <rts-eventlog>`.
701     This format is both more expressive than the old ``.hp`` format
702     and can be correlated with other events over the program's runtime.
703     See :ref:`heap-profiler-events` for details on the produced event structure.
704
705 In addition, the profile can be restricted to heap data which satisfies
706 certain criteria - for example, you might want to display a profile by
707 type but only for data produced by a certain module, or a profile by
708 retainer for a certain type of data. Restrictions are specified as
709 follows:
710
711 .. comment
712
713     The flags below are marked with ``:noindex:`` to avoid duplicate
714     ID warnings from Sphinx.
715
716 .. rts-flag:: -hc ⟨name⟩
717     :noindex:
718
719     Restrict the profile to closures produced by cost-centre stacks with
720     one of the specified cost centres at the top.
721
722 .. rts-flag:: -hC ⟨name⟩
723     :noindex:
724
725     Restrict the profile to closures produced by cost-centre stacks with
726     one of the specified cost centres anywhere in the stack.
727
728 .. rts-flag:: -hm ⟨module⟩
729     :noindex:
730
731     Restrict the profile to closures produced by the specified modules.
732
733 .. rts-flag:: -hd ⟨desc⟩
734     :noindex:
735
736     Restrict the profile to closures with the specified description
737     strings.
738
739 .. rts-flag:: -hy ⟨type⟩
740     :noindex:
741
742     Restrict the profile to closures with the specified types.
743
744 .. rts-flag:: -hr ⟨cc⟩
745     :noindex:
746
747     Restrict the profile to closures with retainer sets containing
748     cost-centre stacks with one of the specified cost centres at the
749     top.
750
751 .. rts-flag:: -hb ⟨bio⟩
752     :noindex:
753
754     Restrict the profile to closures with one of the specified
755     biographies, where ⟨bio⟩ is one of ``lag``, ``drag``, ``void``, or
756     ``use``.
757
758 For example, the following options will generate a retainer profile
759 restricted to ``Branch`` and ``Leaf`` constructors:
760
761 .. code-block:: none
762
763     prog +RTS -hr -hdBranch,Leaf
764
765 There can only be one "break-down" option (eg. :rts-flag:`-hr` in the example
766 above), but there is no limit on the number of further restrictions that
767 may be applied. All the options may be combined, with one exception: GHC
768 doesn't currently support mixing the :rts-flag:`-hr` and :rts-flag:`-hb` options.
769
770 There are three more options which relate to heap profiling:
771
772 .. rts-flag:: -i ⟨secs⟩
773
774     Set the profiling (sampling) interval to ⟨secs⟩ seconds (the default
775     is 0.1 second). Fractions are allowed: for example ``-i0.2`` will
776     get 5 samples per second. This only affects heap profiling; time
777     profiles are always sampled with the frequency of the RTS clock. See
778     :ref:`prof-time-options` for changing that.
779
780 .. rts-flag:: -xt
781
782     Include the memory occupied by threads in a heap profile. Each
783     thread takes up a small area for its thread state in addition to the
784     space allocated for its stack (stacks normally start small and then
785     grow as necessary).
786
787     This includes the main thread, so using :rts-flag:`-xt` is a good way to see
788     how much stack space the program is using.
789
790     Memory occupied by threads and their stacks is labelled as “TSO” and
791     “STACK” respectively when displaying the profile by closure
792     description or type description.
793
794 .. rts-flag:: -L ⟨num⟩
795
796     Sets the maximum length of a cost-centre stack name in a heap
797     profile. Defaults to 25.
798
799 .. _retainer-prof:
800
801 Retainer Profiling
802 ~~~~~~~~~~~~~~~~~~
803
804 Retainer profiling is designed to help answer questions like “why is
805 this data being retained?”. We start by defining what we mean by a
806 retainer:
807
808     A retainer is either the system stack, an unevaluated closure
809     (thunk), or an explicitly mutable object.
810
811 In particular, constructors are *not* retainers.
812
813 An object ``B`` retains object ``A`` if (i) ``B`` is a retainer object and (ii)
814 object ``A`` can be reached by recursively following pointers starting from
815 object ``B``, but not meeting any other retainer objects on the way. Each
816 live object is retained by one or more retainer objects, collectively
817 called its retainer set, or its retainer set, or its retainers.
818
819 When retainer profiling is requested by giving the program the ``-hr``
820 option, a graph is generated which is broken down by retainer set. A
821 retainer set is displayed as a set of cost-centre stacks; because this
822 is usually too large to fit on the profile graph, each retainer set is
823 numbered and shown abbreviated on the graph along with its number, and
824 the full list of retainer sets is dumped into the file ``prog.prof``.
825
826 Retainer profiling requires multiple passes over the live heap in order
827 to discover the full retainer set for each object, which can be quite
828 slow. So we set a limit on the maximum size of a retainer set, where all
829 retainer sets larger than the maximum retainer set size are replaced by
830 the special set ``MANY``. The maximum set size defaults to 8 and can be
831 altered with the :rts-flag:`-R ⟨size⟩` RTS option:
832
833 .. rts-flag:: -R ⟨size⟩
834
835     Restrict the number of elements in a retainer set to ⟨size⟩ (default
836     8).
837
838 Hints for using retainer profiling
839 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
840
841 The definition of retainers is designed to reflect a common cause of
842 space leaks: a large structure is retained by an unevaluated
843 computation, and will be released once the computation is forced. A good
844 example is looking up a value in a finite map, where unless the lookup
845 is forced in a timely manner the unevaluated lookup will cause the whole
846 mapping to be retained. These kind of space leaks can often be
847 eliminated by forcing the relevant computations to be performed eagerly,
848 using ``seq`` or strictness annotations on data constructor fields.
849
850 Often a particular data structure is being retained by a chain of
851 unevaluated closures, only the nearest of which will be reported by
852 retainer profiling - for example ``A`` retains ``B``, ``B`` retains ``C``, and
853 ``C`` retains a large structure. There might be a large number of ``B``\s but
854 only a single ``A``, so ``A`` is really the one we're interested in eliminating.
855 However, retainer profiling will in this case report ``B`` as the retainer of
856 the large structure. To move further up the chain of retainers, we can ask for
857 another retainer profile but this time restrict the profile to ``B`` objects, so
858 we get a profile of the retainers of ``B``:
859
860 .. code-block:: none
861
862     prog +RTS -hr -hcB
863
864 This trick isn't foolproof, because there might be other ``B`` closures in
865 the heap which aren't the retainers we are interested in, but we've
866 found this to be a useful technique in most cases.
867
868 .. _biography-prof:
869
870 Biographical Profiling
871 ~~~~~~~~~~~~~~~~~~~~~~
872
873 A typical heap object may be in one of the following four states at each
874 point in its lifetime:
875
876 -  The lag stage, which is the time between creation and the first use
877    of the object,
878
879 -  the use stage, which lasts from the first use until the last use of
880    the object, and
881
882 -  The drag stage, which lasts from the final use until the last
883    reference to the object is dropped.
884
885 -  An object which is never used is said to be in the void state for its
886    whole lifetime.
887
888 A biographical heap profile displays the portion of the live heap in
889 each of the four states listed above. Usually the most interesting
890 states are the void and drag states: live heap in these states is more
891 likely to be wasted space than heap in the lag or use states.
892
893 It is also possible to break down the heap in one or more of these
894 states by a different criteria, by restricting a profile by biography.
895 For example, to show the portion of the heap in the drag or void state
896 by producer:
897
898 .. code-block:: none
899
900     prog +RTS -hc -hbdrag,void
901
902 Once you know the producer or the type of the heap in the drag or void
903 states, the next step is usually to find the retainer(s):
904
905 .. code-block:: none
906
907     prog +RTS -hr -hccc...
908
909 .. note::
910     This two stage process is required because GHC cannot currently
911     profile using both biographical and retainer information simultaneously.
912
913 .. _mem-residency:
914
915 Actual memory residency
916 ~~~~~~~~~~~~~~~~~~~~~~~
917
918 How does the heap residency reported by the heap profiler relate to the
919 actual memory residency of your program when you run it? You might see a
920 large discrepancy between the residency reported by the heap profiler,
921 and the residency reported by tools on your system (eg. ``ps`` or
922 ``top`` on Unix, or the Task Manager on Windows). There are several
923 reasons for this:
924
925 -  There is an overhead of profiling itself, which is subtracted from
926    the residency figures by the profiler. This overhead goes away when
927    compiling without profiling support, of course. The space overhead is
928    currently 2 extra words per heap object, which probably results in
929    about a 30% overhead.
930
931 -  Garbage collection requires more memory than the actual residency.  The
932    factor depends on the kind of garbage collection algorithm in use: a major GC
933    in the standard generation copying collector will usually require :math:`3L`
934    bytes of memory, where :math:`L` is the amount of live data. This is because
935    by default (see the RTS :rts-flag:`-F ⟨factor⟩` option) we allow the old
936    generation to grow to twice its size (:math:`2L`) before collecting it, and
937    we require additionally :math:`L` bytes to copy the live data into. When
938    using compacting collection (see the :rts-flag:`-c` option), this is reduced
939    to :math:`2L`, and can further be reduced by tweaking the :rts-flag:`-F
940    ⟨factor⟩` option. Also add the size of the allocation area (see :rts-flag:`-A
941    ⟨size⟩`).
942
943 -  The stack isn't counted in the heap profile by default. See the
944    RTS :rts-flag:`-xt` option.
945
946 -  The program text itself, the C stack, any non-heap data (e.g. data
947    allocated by foreign libraries, and data allocated by the RTS), and
948    ``mmap()``\'d memory are not counted in the heap profile.
949
950 .. _hp2ps:
951
952 ``hp2ps`` -- Rendering heap profiles to PostScript
953 --------------------------------------------------
954
955 .. index::
956    single: hp2ps
957    single: heap profiles
958    single: postscript, from heap profiles
959    single: -h⟨break-down⟩
960
961 Usage:
962
963 .. code-block:: none
964
965     hp2ps [flags] [<file>[.hp]]
966
967 The program :command:`hp2ps` program converts a ``.hp`` file produced
968 by the ``-h<break-down>`` runtime option into a PostScript graph of the
969 heap profile. By convention, the file to be processed by :command:`hp2ps` has a
970 ``.hp`` extension. The PostScript output is written to :file:`{file}@.ps`.
971 If ``<file>`` is omitted entirely, then the program behaves as a filter.
972
973 :command:`hp2ps` is distributed in :file:`ghc/utils/hp2ps` in a GHC source
974 distribution. It was originally developed by Dave Wakeling as part of
975 the HBC/LML heap profiler.
976
977 The flags are:
978
979 .. program:: hp2ps
980
981 .. option:: -d
982
983     In order to make graphs more readable, ``hp2ps`` sorts the shaded
984     bands for each identifier. The default sort ordering is for the
985     bands with the largest area to be stacked on top of the smaller
986     ones. The ``-d`` option causes rougher bands (those representing
987     series of values with the largest standard deviations) to be stacked
988     on top of smoother ones.
989
990 .. option:: -b
991
992     Normally, ``hp2ps`` puts the title of the graph in a small box at
993     the top of the page. However, if the JOB string is too long to fit
994     in a small box (more than 35 characters), then ``hp2ps`` will choose
995     to use a big box instead. The ``-b`` option forces ``hp2ps`` to use
996     a big box.
997
998 .. option:: -e⟨float⟩[in|mm|pt]
999
1000     Generate encapsulated PostScript suitable for inclusion in LaTeX
1001     documents. Usually, the PostScript graph is drawn in landscape mode
1002     in an area 9 inches wide by 6 inches high, and ``hp2ps`` arranges
1003     for this area to be approximately centred on a sheet of a4 paper.
1004     This format is convenient of studying the graph in detail, but it is
1005     unsuitable for inclusion in LaTeX documents. The ``-e`` option
1006     causes the graph to be drawn in portrait mode, with float specifying
1007     the width in inches, millimetres or points (the default). The
1008     resulting PostScript file conforms to the Encapsulated PostScript
1009     (EPS) convention, and it can be included in a LaTeX document using
1010     Rokicki's dvi-to-PostScript converter ``dvips``.
1011
1012 .. option:: -g
1013
1014     Create output suitable for the ``gs`` PostScript previewer (or
1015     similar). In this case the graph is printed in portrait mode without
1016     scaling. The output is unsuitable for a laser printer.
1017
1018 .. option:: -l
1019
1020     Normally a profile is limited to 20 bands with additional
1021     identifiers being grouped into an ``OTHER`` band. The ``-l`` flag
1022     removes this 20 band and limit, producing as many bands as
1023     necessary. No key is produced as it won't fit!. It is useful for
1024     creation time profiles with many bands.
1025
1026 .. option:: -m⟨int⟩
1027
1028     Normally a profile is limited to 20 bands with additional
1029     identifiers being grouped into an ``OTHER`` band. The ``-m`` flag
1030     specifies an alternative band limit (the maximum is 20).
1031
1032     ``-m0`` requests the band limit to be removed. As many bands as
1033     necessary are produced. However no key is produced as it won't fit!
1034     It is useful for displaying creation time profiles with many bands.
1035
1036 .. option:: -p
1037
1038     Use previous parameters. By default, the PostScript graph is
1039     automatically scaled both horizontally and vertically so that it
1040     fills the page. However, when preparing a series of graphs for use
1041     in a presentation, it is often useful to draw a new graph using the
1042     same scale, shading and ordering as a previous one. The ``-p`` flag
1043     causes the graph to be drawn using the parameters determined by a
1044     previous run of ``hp2ps`` on ``file``. These are extracted from
1045     ``file@.aux``.
1046
1047 .. option:: -s
1048
1049     Use a small box for the title.
1050
1051 .. option:: -t⟨float⟩
1052
1053     Normally trace elements which sum to a total of less than 1% of the
1054     profile are removed from the profile. The ``-t`` option allows this
1055     percentage to be modified (maximum 5%).
1056
1057     ``-t0`` requests no trace elements to be removed from the profile,
1058     ensuring that all the data will be displayed.
1059
1060 .. option:: -c
1061
1062     Generate colour output.
1063
1064 .. option:: -y
1065
1066     Ignore marks.
1067
1068 .. option:: -?
1069
1070     Print out usage information.
1071
1072 .. _manipulating-hp:
1073
1074 Manipulating the ``hp`` file
1075 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1076
1077 (Notes kindly offered by Jan-Willem Maessen.)
1078
1079 The ``FOO.hp`` file produced when you ask for the heap profile of a
1080 program ``FOO`` is a text file with a particularly simple structure.
1081 Here's a representative example, with much of the actual data omitted:
1082
1083 .. code-block:: none
1084
1085     JOB "FOO -hC"
1086     DATE "Thu Dec 26 18:17 2002"
1087     SAMPLE_UNIT "seconds"
1088     VALUE_UNIT "bytes"
1089     BEGIN_SAMPLE 0.00
1090     END_SAMPLE 0.00
1091     BEGIN_SAMPLE 15.07
1092       ... sample data ...
1093     END_SAMPLE 15.07
1094     BEGIN_SAMPLE 30.23
1095       ... sample data ...
1096     END_SAMPLE 30.23
1097     ... etc.
1098     BEGIN_SAMPLE 11695.47
1099     END_SAMPLE 11695.47
1100
1101 The first four lines (``JOB``, ``DATE``, ``SAMPLE_UNIT``,
1102 ``VALUE_UNIT``) form a header. Each block of lines starting with
1103 ``BEGIN_SAMPLE`` and ending with ``END_SAMPLE`` forms a single sample
1104 (you can think of this as a vertical slice of your heap profile). The
1105 hp2ps utility should accept any input with a properly-formatted header
1106 followed by a series of *complete* samples.
1107
1108 Zooming in on regions of your profile
1109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1110
1111 You can look at particular regions of your profile simply by loading a
1112 copy of the ``.hp`` file into a text editor and deleting the unwanted
1113 samples. The resulting ``.hp`` file can be run through ``hp2ps`` and
1114 viewed or printed.
1115
1116 Viewing the heap profile of a running program
1117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1118
1119 The ``.hp`` file is generated incrementally as your program runs. In
1120 principle, running :command:`hp2ps` on the incomplete file should produce a
1121 snapshot of your program's heap usage. However, the last sample in the
1122 file may be incomplete, causing :command:`hp2ps` to fail. If you are using a
1123 machine with UNIX utilities installed, it's not too hard to work around
1124 this problem (though the resulting command line looks rather Byzantine):
1125
1126 .. code-block:: sh
1127
1128     head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1129         | hp2ps > FOO.ps
1130
1131 The command ``fgrep -n END_SAMPLE FOO.hp`` finds the end of every
1132 complete sample in ``FOO.hp``, and labels each sample with its ending
1133 line number. We then select the line number of the last complete sample
1134 using :command:`tail` and :command:`cut`. This is used as a parameter to :command:`head`; the
1135 result is as if we deleted the final incomplete sample from :file:`FOO.hp`.
1136 This results in a properly-formatted .hp file which we feed directly to
1137 :command:`hp2ps`.
1138
1139 Viewing a heap profile in real time
1140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1141
1142 The :command:`gv` and :command:`ghostview` programs have a "watch file" option
1143 can be used to view an up-to-date heap profile of your program as it runs.
1144 Simply generate an incremental heap profile as described in the previous
1145 section. Run :command:`gv` on your profile:
1146
1147 .. code-block:: sh
1148
1149       gv -watch -orientation=seascape FOO.ps
1150
1151 If you forget the ``-watch`` flag you can still select "Watch file" from
1152 the "State" menu. Now each time you generate a new profile ``FOO.ps``
1153 the view will update automatically.
1154
1155 This can all be encapsulated in a little script:
1156
1157 .. code-block:: sh
1158
1159       #!/bin/sh
1160       head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1161         | hp2ps > FOO.ps
1162       gv -watch -orientation=seascape FOO.ps &
1163       while [ 1 ] ; do
1164         sleep 10 # We generate a new profile every 10 seconds.
1165         head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1166           | hp2ps > FOO.ps
1167       done
1168
1169 Occasionally :command:`gv` will choke as it tries to read an incomplete copy of
1170 :file:`FOO.ps` (because :command:`hp2ps` is still running as an update occurs). A
1171 slightly more complicated script works around this problem, by using the
1172 fact that sending a SIGHUP to gv will cause it to re-read its input
1173 file:
1174
1175 .. code-block:: sh
1176
1177       #!/bin/sh
1178       head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1179         | hp2ps > FOO.ps
1180       gv FOO.ps &
1181       gvpsnum=$!
1182       while [ 1 ] ; do
1183         sleep 10
1184         head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1185           | hp2ps > FOO.ps
1186         kill -HUP $gvpsnum
1187       done
1188
1189 .. _prof-threaded:
1190
1191 Profiling Parallel and Concurrent Programs
1192 ------------------------------------------
1193
1194 Combining :ghc-flag:`-threaded` and :ghc-flag:`-prof` is perfectly fine, and
1195 indeed it is possible to profile a program running on multiple processors with
1196 the RTS :rts-flag:`-N ⟨x⟩` option. [3]_
1197
1198 Some caveats apply, however. In the current implementation, a profiled
1199 program is likely to scale much less well than the unprofiled program,
1200 because the profiling implementation uses some shared data structures
1201 which require locking in the runtime system. Furthermore, the memory
1202 allocation statistics collected by the profiled program are stored in
1203 shared memory but *not* locked (for speed), which means that these
1204 figures might be inaccurate for parallel programs.
1205
1206 We strongly recommend that you use :ghc-flag:`-fno-prof-count-entries` when
1207 compiling a program to be profiled on multiple cores, because the entry
1208 counts are also stored in shared memory, and continuously updating them
1209 on multiple cores is extremely slow.
1210
1211 We also recommend using
1212 `ThreadScope <http://www.haskell.org/haskellwiki/ThreadScope>`__ for
1213 profiling parallel programs; it offers a GUI for visualising parallel
1214 execution, and is complementary to the time and space profiling features
1215 provided with GHC.
1216
1217 .. _hpc:
1218
1219 Observing Code Coverage
1220 -----------------------
1221
1222 .. index::
1223    single: code coverage
1224    single: Haskell Program Coverage
1225    single: hpc
1226
1227 Code coverage tools allow a programmer to determine what parts of their
1228 code have been actually executed, and which parts have never actually
1229 been invoked. GHC has an option for generating instrumented code that
1230 records code coverage as part of the Haskell Program Coverage (HPC)
1231 toolkit, which is included with GHC. HPC tools can be used to render the
1232 generated code coverage information into human understandable format.
1233
1234 Correctly instrumented code provides coverage information of two kinds:
1235 source coverage and boolean-control coverage. Source coverage is the
1236 extent to which every part of the program was used, measured at three
1237 different levels: declarations (both top-level and local), alternatives
1238 (among several equations or case branches) and expressions (at every
1239 level). Boolean coverage is the extent to which each of the values True
1240 and False is obtained in every syntactic boolean context (ie. guard,
1241 condition, qualifier).
1242
1243 HPC displays both kinds of information in two primary ways: textual
1244 reports with summary statistics (``hpc report``) and sources with color
1245 mark-up (``hpc markup``). For boolean coverage, there are four possible
1246 outcomes for each guard, condition or qualifier: both True and False
1247 values occur; only True; only False; never evaluated. In hpc-markup
1248 output, highlighting with a yellow background indicates a part of the
1249 program that was never evaluated; a green background indicates an
1250 always-True expression and a red background indicates an always-False
1251 one.
1252
1253 A small example: Reciprocation
1254 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1255
1256 For an example we have a program, called :file:`Recip.hs`, which computes
1257 exact decimal representations of reciprocals, with recurring parts
1258 indicated in brackets. ::
1259
1260     reciprocal :: Int -> (String, Int)
1261     reciprocal n | n > 1 = ('0' : '.' : digits, recur)
1262                  | otherwise = error
1263                   "attempting to compute reciprocal of number <= 1"
1264       where
1265       (digits, recur) = divide n 1 []
1266     divide :: Int -> Int -> [Int] -> (String, Int)
1267     divide n c cs | c `elem` cs = ([], position c cs)
1268                   | r == 0      = (show q, 0)
1269                   | r /= 0      = (show q ++ digits, recur)
1270       where
1271       (q, r) = (c*10) `quotRem` n
1272       (digits, recur) = divide n r (c:cs)
1273
1274     position :: Int -> [Int] -> Int
1275     position n (x:xs) | n==x      = 1
1276                       | otherwise = 1 + position n xs
1277
1278     showRecip :: Int -> String
1279     showRecip n =
1280       "1/" ++ show n ++ " = " ++
1281       if r==0 then d else take p d ++ "(" ++ drop p d ++ ")"
1282       where
1283       p = length d - r
1284       (d, r) = reciprocal n
1285
1286     main = do
1287       number <- readLn
1288       putStrLn (showRecip number)
1289       main
1290
1291 HPC instrumentation is enabled with the :ghc-flag:`-fhpc` flag:
1292
1293 .. code-block:: sh
1294
1295     $ ghc -fhpc Recip.hs
1296
1297 GHC creates a subdirectory ``.hpc`` in the current directory, and puts
1298 HPC index (``.mix``) files in there, one for each module compiled. You
1299 don't need to worry about these files: they contain information needed
1300 by the ``hpc`` tool to generate the coverage data for compiled modules
1301 after the program is run.
1302
1303 .. code-block:: sh
1304
1305     $ ./Recip
1306     1/3
1307     = 0.(3)
1308
1309 Running the program generates a file with the ``.tix`` suffix, in this
1310 case :file:`Recip.tix`, which contains the coverage data for this run of the
1311 program. The program may be run multiple times (e.g. with different test
1312 data), and the coverage data from the separate runs is accumulated in
1313 the ``.tix`` file. To reset the coverage data and start again, just
1314 remove the ``.tix`` file. You can control where the ``.tix`` file
1315 is generated using the environment variable :envvar:`HPCTIXFILE`.
1316
1317 .. envvar:: HPCTIXFILE
1318
1319     Set the HPC ``.tix`` file output path.
1320
1321 Having run the program, we can generate a textual summary of coverage:
1322
1323 .. code-block:: none
1324
1325     $ hpc report Recip
1326      80% expressions used (81/101)
1327      12% boolean coverage (1/8)
1328           14% guards (1/7), 3 always True,
1329                             1 always False,
1330                             2 unevaluated
1331            0% 'if' conditions (0/1), 1 always False
1332          100% qualifiers (0/0)
1333      55% alternatives used (5/9)
1334     100% local declarations used (9/9)
1335     100% top-level declarations used (5/5)
1336
1337 We can also generate a marked-up version of the source.
1338
1339 .. code-block:: none
1340
1341     $ hpc markup Recip
1342     writing Recip.hs.html
1343
1344 This generates one file per Haskell module, and 4 index files,
1345 :file:`hpc_index.html`, :file:`hpc_index_alt.html`, :file:`hpc_index_exp.html`,
1346 :file:`hpc_index_fun.html`.
1347
1348 Options for instrumenting code for coverage
1349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1350
1351 .. program:: hpc
1352
1353 .. ghc-flag:: -fhpc
1354
1355     Enable code coverage for the current module or modules being
1356     compiled.
1357
1358     Modules compiled with this option can be freely mixed with modules
1359     compiled without it; indeed, most libraries will typically be
1360     compiled without :ghc-flag:`-fhpc`. When the program is run, coverage data
1361     will only be generated for those modules that were compiled with
1362     :ghc-flag:`-fhpc`, and the :command:`hpc` tool will only show information about
1363     those modules.
1364
1365 The hpc toolkit
1366 ~~~~~~~~~~~~~~~
1367
1368 The hpc command has several sub-commands:
1369
1370 .. code-block:: none
1371
1372     $ hpc
1373     Usage: hpc COMMAND ...
1374
1375     Commands:
1376       help        Display help for hpc or a single command
1377     Reporting Coverage:
1378       report      Output textual report about program coverage
1379       markup      Markup Haskell source with program coverage
1380     Processing Coverage files:
1381       sum         Sum multiple .tix files in a single .tix file
1382       combine     Combine two .tix files in a single .tix file
1383       map         Map a function over a single .tix file
1384     Coverage Overlays:
1385       overlay     Generate a .tix file from an overlay file
1386       draft       Generate draft overlay that provides 100% coverage
1387     Others:
1388       show        Show .tix file in readable, verbose format
1389       version     Display version for hpc
1390
1391 In general, these options act on a ``.tix`` file after an instrumented
1392 binary has generated it.
1393
1394 The hpc tool assumes you are in the top-level directory of the location
1395 where you built your application, and the ``.tix`` file is in the same
1396 top-level directory. You can use the flag ``--srcdir`` to use ``hpc``
1397 for any other directory, and use ``--srcdir`` multiple times to analyse
1398 programs compiled from difference locations, as is typical for packages.
1399
1400 We now explain in more details the major modes of hpc.
1401
1402 hpc report
1403 ^^^^^^^^^^
1404
1405 ``hpc report`` gives a textual report of coverage. By default, all
1406 modules and packages are considered in generating report, unless include
1407 or exclude are used. The report is a summary unless the ``--per-module``
1408 flag is used. The ``--xml-output`` option allows for tools to use hpc to
1409 glean coverage.
1410
1411 .. code-block:: none
1412
1413     $ hpc help report
1414     Usage: hpc report [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
1415
1416     Options:
1417
1418         --per-module                  show module level detail
1419         --decl-list                   show unused decls
1420         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1421         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1422         --srcdir=DIR                  path to source directory of .hs files
1423                                       multi-use of srcdir possible
1424         --hpcdir=DIR                  append sub-directory that contains .mix files
1425                                       default .hpc [rarely used]
1426         --reset-hpcdirs               empty the list of hpcdir's
1427                                       [rarely used]
1428         --xml-output                  show output in XML
1429
1430 hpc markup
1431 ^^^^^^^^^^
1432
1433 ``hpc markup`` marks up source files into colored html.
1434
1435 .. code-block:: none
1436
1437     $ hpc help markup
1438     Usage: hpc markup [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
1439
1440     Options:
1441
1442         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1443         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1444         --srcdir=DIR                  path to source directory of .hs files
1445                                       multi-use of srcdir possible
1446         --hpcdir=DIR                  append sub-directory that contains .mix files
1447                                       default .hpc [rarely used]
1448         --reset-hpcdirs               empty the list of hpcdir's
1449                                       [rarely used]
1450         --fun-entry-count             show top-level function entry counts
1451         --highlight-covered           highlight covered code, rather that code gaps
1452         --destdir=DIR                 path to write output to
1453
1454 hpc sum
1455 ^^^^^^^
1456
1457 ``hpc sum`` adds together any number of ``.tix`` files into a single
1458 ``.tix`` file. ``hpc sum`` does not change the original ``.tix`` file;
1459 it generates a new ``.tix`` file.
1460
1461 .. code-block:: none
1462
1463     $ hpc help sum
1464     Usage: hpc sum [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]]
1465     Sum multiple .tix files in a single .tix file
1466
1467     Options:
1468
1469         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1470         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1471         --output=FILE                 output FILE
1472         --union                       use the union of the module namespace (default is intersection)
1473
1474 hpc combine
1475 ^^^^^^^^^^^
1476
1477 ``hpc combine`` is the swiss army knife of ``hpc``. It can be used to
1478 take the difference between ``.tix`` files, to subtract one ``.tix``
1479 file from another, or to add two ``.tix`` files. hpc combine does not
1480 change the original ``.tix`` file; it generates a new ``.tix`` file.
1481
1482 .. code-block:: none
1483
1484     $ hpc help combine
1485     Usage: hpc combine [OPTION] .. <TIX_FILE> <TIX_FILE>
1486     Combine two .tix files in a single .tix file
1487
1488     Options:
1489
1490         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1491         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1492         --output=FILE                 output FILE
1493         --function=FUNCTION           combine .tix files with join function, default = ADD
1494                                       FUNCTION = ADD | DIFF | SUB
1495         --union                       use the union of the module namespace (default is intersection)
1496
1497 hpc map
1498 ^^^^^^^
1499
1500 hpc map inverts or zeros a ``.tix`` file. hpc map does not change the
1501 original ``.tix`` file; it generates a new ``.tix`` file.
1502
1503 .. code-block:: none
1504
1505     $ hpc help map
1506     Usage: hpc map [OPTION] .. <TIX_FILE>
1507     Map a function over a single .tix file
1508
1509     Options:
1510
1511         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1512         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1513         --output=FILE                 output FILE
1514         --function=FUNCTION           apply function to .tix files, default = ID
1515                                       FUNCTION = ID | INV | ZERO
1516         --union                       use the union of the module namespace (default is intersection)
1517
1518 hpc overlay and hpc draft
1519 ^^^^^^^^^^^^^^^^^^^^^^^^^
1520
1521 Overlays are an experimental feature of HPC, a textual description of
1522 coverage. hpc draft is used to generate a draft overlay from a .tix
1523 file, and hpc overlay generates a .tix files from an overlay.
1524
1525 .. code-block:: none
1526
1527     % hpc help overlay
1528     Usage: hpc overlay [OPTION] .. <OVERLAY_FILE> [<OVERLAY_FILE> [...]]
1529
1530     Options:
1531
1532         --srcdir=DIR   path to source directory of .hs files
1533                        multi-use of srcdir possible
1534         --hpcdir=DIR                  append sub-directory that contains .mix files
1535                                       default .hpc [rarely used]
1536         --reset-hpcdirs               empty the list of hpcdir's
1537                                       [rarely used]
1538         --output=FILE  output FILE
1539     % hpc help draft
1540     Usage: hpc draft [OPTION] .. <TIX_FILE>
1541
1542     Options:
1543
1544         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1545         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1546         --srcdir=DIR                  path to source directory of .hs files
1547                                       multi-use of srcdir possible
1548         --hpcdir=DIR                  append sub-directory that contains .mix files
1549                                       default .hpc [rarely used]
1550         --reset-hpcdirs               empty the list of hpcdir's
1551                                       [rarely used]
1552         --output=FILE                 output FILE
1553
1554 Caveats and Shortcomings of Haskell Program Coverage
1555 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1556
1557 HPC does not attempt to lock the ``.tix`` file, so multiple concurrently
1558 running binaries in the same directory will exhibit a race condition.
1559 At compile time, there is no way to change the name of the ``.tix`` file generated;
1560 at runtime, the name of the generated ``.tix`` file can be changed
1561 using :envvar:`HPCTIXFILE`; the name of the ``.tix`` file
1562 will also change if you rename the binary.  HPC does not work with GHCi.
1563
1564 .. _ticky-ticky:
1565
1566 Using “ticky-ticky” profiling (for implementors)
1567 ------------------------------------------------
1568
1569 .. index::
1570    single: ticky-ticky profiling
1571
1572 .. ghc-flag:: -ticky
1573
1574    Enable ticky-ticky profiling.
1575
1576 Because ticky-ticky profiling requires a certain familiarity with GHC
1577 internals, we have moved the documentation to the GHC developers wiki.
1578 Take a look at its
1579 :ghc-wiki:`overview of the profiling options <Commentary/Profiling>`,
1580 which includeds a link to the ticky-ticky profiling page.
1581
1582 .. [1]
1583    :ghc-flag:`-fprof-auto` was known as ``-auto-all`` prior to
1584    GHC 7.4.1.
1585
1586 .. [2]
1587    Note that this policy has changed slightly in GHC 7.4.1 relative to
1588    earlier versions, and may yet change further, feedback is welcome.
1589
1590 .. [3]
1591    This feature was added in GHC 7.4.1.