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