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