6851536cfb514d7bafd3bee24ce5c9c21c8c010e
[ghc.git] / docs / users_guide / sooner.rst
1 .. _sooner-faster-quicker:
2
3 Advice on: sooner, faster, smaller, thriftier
4 =============================================
5
6 Please advise us of other "helpful hints" that should go here!
7
8 .. _sooner:
9
10 Sooner: producing a program more quickly
11 ----------------------------------------
12
13 .. index::
14    single: compiling faster
15    single: faster compiling
16
17 Don't use :ghc-flag:`-O` or (especially) :ghc-flag:`-O2`:
18     By using them, you are telling GHC that you are willing to suffer
19     longer compilation times for better-quality code.
20
21     GHC is surprisingly zippy for normal compilations without :ghc-flag:`-O`!
22
23 Use more memory:
24     Within reason, more memory for heap space means less garbage
25     collection for GHC, which means less compilation time. If you use
26     the ``-Rghc-timing`` option, you'll get a garbage-collector report.
27     (Again, you can use the cheap-and-nasty ``+RTS -S -RTS`` option to
28     send the GC stats straight to standard error.)
29
30     .. index::
31        single: -H; RTS option
32
33     If it says you're using more than 20% of total time in garbage collecting,
34     then more memory might help: use the ``-H⟨size⟩`` (see :rts-flag:`-H
35     [⟨size⟩]`) option. Increasing the default allocation area size used by the
36     compiler's RTS might also help: use the ``+RTS -A⟨size⟩ -RTS`` option (see
37     :rts-flag:`-A ⟨size⟩`).
38
39     .. index::
40        single: -A⟨size⟩; RTS option
41
42     If GHC persists in being a bad memory citizen, please report it as a
43     bug.
44
45 Don't use too much memory!
46     As soon as GHC plus its “fellow citizens” (other processes on your
47     machine) start using more than the *real memory* on your machine,
48     and the machine starts “thrashing,” *the party is over*. Compile
49     times will be worse than terrible! Use something like the csh
50     builtin :command:`time` command to get a report on how many page faults
51     you're getting.
52
53     If you don't know what virtual memory, thrashing, and page faults
54     are, or you don't know the memory configuration of your machine,
55     *don't* try to be clever about memory use: you'll just make your
56     life a misery (and for other people, too, probably).
57
58 Try to use local disks when linking:
59     Because Haskell objects and libraries tend to be large, it can take
60     many real seconds to slurp the bits to/from a remote filesystem.
61
62     It would be quite sensible to *compile* on a fast machine using
63     remotely-mounted disks; then *link* on a slow machine that had your
64     disks directly mounted.
65
66 Don't derive/use ``Read`` unnecessarily:
67     It's ugly and slow.
68
69 GHC compiles some program constructs slowly:
70     We'd rather you reported such behaviour as a bug, so that we can try
71     to correct it.
72
73     .. index::
74        single: -v; GHC option
75
76     To figure out which part of the compiler is badly behaved, the
77     ``-v2`` option is your friend.
78
79 .. _faster:
80
81 Faster: producing a program that runs quicker
82 ---------------------------------------------
83
84 .. index::
85    single: faster programs, how to produce
86
87 The key tool to use in making your Haskell program run faster are GHC's
88 profiling facilities, described separately in :ref:`profiling`. There is
89 *no substitute* for finding where your program's time/space is *really*
90 going, as opposed to where you imagine it is going.
91
92 Another point to bear in mind: By far the best way to improve a
93 program's performance *dramatically* is to use better algorithms. Once
94 profiling has thrown the spotlight on the guilty time-consumer(s), it
95 may be better to re-think your program than to try all the tweaks listed
96 below.
97
98 Another extremely efficient way to make your program snappy is to use
99 library code that has been Seriously Tuned By Someone Else. You *might*
100 be able to write a better quicksort than the one in ``Data.List``, but
101 it will take you much longer than typing ``import Data.List``.
102
103 Please report any overly-slow GHC-compiled programs. Since GHC doesn't
104 have any credible competition in the performance department these days
105 it's hard to say what overly-slow means, so just use your judgement! Of
106 course, if a GHC compiled program runs slower than the same program
107 compiled with NHC or Hugs, then it's definitely a bug.
108
109 Optimise, using ``-O`` or ``-O2``:
110     This is the most basic way to make your program go faster.
111     Compilation time will be slower, especially with ``-O2``.
112
113     At present, ``-O2`` is nearly indistinguishable from ``-O``.
114
115 Compile via LLVM:
116     The :ref:`LLVM code generator <llvm-code-gen>` can sometimes do a far
117     better job at producing fast code than the :ref:`native code generator
118     <native-code-gen>`. This is not universal and depends on the code. Numeric
119     heavy code seems to show the best improvement when compiled via LLVM. You
120     can also experiment with passing specific flags to LLVM with the
121     :ghc-flag:`-optlo ⟨option⟩` and :ghc-flag:`-optlc ⟨option⟩` flags. Be
122     careful though as setting these flags stops GHC from setting its usual
123     flags for the LLVM optimiser and compiler.
124
125 Overloaded functions are not your friend:
126     Haskell's overloading (using type classes) is elegant, neat, etc.,
127     etc., but it is death to performance if left to linger in an inner
128     loop. How can you squash it?
129
130 Give explicit type signatures:
131     Signatures are the basic trick; putting them on exported, top-level
132     functions is good software-engineering practice, anyway. (Tip: using
133     the :ghc-flag:`-Wmissing-signatures` option can
134     help enforce good signature-practice).
135
136     The automatic specialisation of overloaded functions (with ``-O``)
137     should take care of overloaded local and/or unexported functions.
138
139 Use ``SPECIALIZE`` pragmas:
140     .. index::
141        single: SPECIALIZE pragma
142
143     .. index::
144        single: overloading, death to
145
146     Specialize the overloading on key functions in your program. See
147     :ref:`specialize-pragma` and :ref:`specialize-instance-pragma`.
148
149 "But how do I know where overloading is creeping in?"
150     A low-tech way: grep (search) your interface files for overloaded
151     type signatures. You can view interface files using the
152     :ghc-flag:`--show-iface ⟨file⟩` option (see :ref:`hi-options`).
153
154     .. code-block:: sh
155
156         $ ghc --show-iface Foo.hi | egrep '^[a-z].*::.*=>'
157
158 Strict functions are your dear friends:
159     And, among other things, lazy pattern-matching is your enemy.
160
161     (If you don't know what a "strict function" is, please consult a
162     functional-programming textbook. A sentence or two of explanation
163     here probably would not do much good.)
164
165     Consider these two code fragments:
166
167     ::
168
169         f (Wibble x y) =  ... # strict
170
171         f arg = let { (Wibble x y) = arg } in ... # lazy
172
173     The former will result in far better code.
174
175     A less contrived example shows the use of ``cases`` instead of
176     ``lets`` to get stricter code (a good thing):
177
178     ::
179
180         f (Wibble x y)  # beautiful but slow
181               = let
182                     (a1, b1, c1) = unpackFoo x
183                     (a2, b2, c2) = unpackFoo y
184                 in ...
185
186         f (Wibble x y)  # ugly, and proud of it
187               = case (unpackFoo x) of { (a1, b1, c1) ->
188                     case (unpackFoo y) of { (a2, b2, c2) ->
189                         ...
190               }}
191
192 GHC loves single-constructor data-types:
193     It's all the better if a function is strict in a single-constructor
194     type (a type with only one data-constructor; for example, tuples are
195     single-constructor types).
196
197 Newtypes are better than datatypes:
198     If your datatype has a single constructor with a single field, use a
199     ``newtype`` declaration instead of a ``data`` declaration. The
200     ``newtype`` will be optimised away in most cases.
201
202 "How do I find out a function's strictness?"
203     Don't guess—look it up.
204
205     Look for your function in the interface file, then for the third
206     field in the pragma; it should say ``Strictness: ⟨string⟩``. The
207     ⟨string⟩ gives the strictness of the function's arguments: see
208     :ghc-wiki:`the GHC Commentary <Commentary/Compiler/Demand>`
209     for a description of the strictness notation.
210
211     For an "unpackable" ``U(...)`` argument, the info inside tells the
212     strictness of its components. So, if the argument is a pair, and it
213     says ``U(AU(LSS))``, that means “the first component of the pair
214     isn't used; the second component is itself unpackable, with three
215     components (lazy in the first, strict in the second \\& third).”
216
217     If the function isn't exported, just compile with the extra flag
218     :ghc-flag:`-ddump-simpl`; next to the signature for any binder, it will
219     print the self-same pragmatic information as would be put in an
220     interface file. (Besides, Core syntax is fun to look at!)
221
222 Force key functions to be ``INLINE``\ d (esp. monads):
223     Placing ``INLINE`` pragmas on certain functions that are used a lot
224     can have a dramatic effect. See :ref:`inline-pragma`.
225
226 Explicit ``export`` list:
227     If you do not have an explicit export list in a module, GHC must
228     assume that everything in that module will be exported. This has
229     various pessimising effects. For example, if a bit of code is
230     actually *unused* (perhaps because of unfolding effects), GHC will
231     not be able to throw it away, because it is exported and some other
232     module may be relying on its existence.
233
234     GHC can be quite a bit more aggressive with pieces of code if it
235     knows they are not exported.
236
237 Look at the Core syntax!
238     (The form in which GHC manipulates your code.) Just run your
239     compilation with :ghc-flag:`-ddump-simpl` (don't forget the :ghc-flag:`-O`).
240
241     If profiling has pointed the finger at particular functions, look at
242     their Core code. ``lets`` are bad, ``cases`` are good, dictionaries
243     (``d.⟨Class⟩.⟨Unique⟩``) [or anything overloading-ish] are bad,
244     nested lambdas are bad, explicit data constructors are good,
245     primitive operations (e.g., ``eqInt#``) are good, ...
246
247 Use strictness annotations:
248     Putting a strictness annotation (``!``) on a constructor field helps
249     in two ways: it adds strictness to the program, which gives the
250     strictness analyser more to work with, and it might help to reduce
251     space leaks.
252
253     It can also help in a third way: when used with
254     :ghc-flag:`-funbox-strict-fields` (see :ref:`options-f`), a strict field can
255     be unpacked or unboxed in the constructor, and one or more levels of
256     indirection may be removed. Unpacking only happens for
257     single-constructor datatypes (``Int`` is a good candidate, for
258     example).
259
260     Using :ghc-flag:`-funbox-strict-fields` is only really a good idea in
261     conjunction with :ghc-flag:`-O`, because otherwise the extra packing and
262     unpacking won't be optimised away. In fact, it is possible that
263     :ghc-flag:`-funbox-strict-fields` may worsen performance even *with* :ghc-flag:`-O`,
264     but this is unlikely (let us know if it happens to you).
265
266 Use unboxed types (a GHC extension):
267     When you are *really* desperate for speed, and you want to get right
268     down to the “raw bits.” Please see :ref:`glasgow-unboxed` for some
269     information about using unboxed types.
270
271     Before resorting to explicit unboxed types, try using strict
272     constructor fields and :ghc-flag:`-funbox-strict-fields` first (see above).
273     That way, your code stays portable.
274
275 Use ``foreign import`` (a GHC extension) to plug into fast libraries:
276     This may take real work, but… There exist piles of massively-tuned
277     library code, and the best thing is not to compete with it, but link
278     with it.
279
280     :ref:`ffi` describes the foreign function interface.
281
282 Don't use ``Float``\s:
283     If you're using ``Complex``, definitely use ``Complex Double``
284     rather than ``Complex Float`` (the former is specialised heavily,
285     but the latter isn't).
286
287     ``Floats`` (probably 32-bits) are almost always a bad idea, anyway,
288     unless you Really Know What You Are Doing. Use ``Double``\s.
289     There's rarely a speed disadvantage—modern machines will use the
290     same floating-point unit for both. With ``Double``\s, you are much
291     less likely to hang yourself with numerical errors.
292
293     One time when ``Float`` might be a good idea is if you have a *lot*
294     of them, say a giant array of ``Float``\s. They take up half the
295     space in the heap compared to ``Doubles``. However, this isn't true
296     on a 64-bit machine.
297
298 Use unboxed arrays (``UArray``)
299     GHC supports arrays of unboxed elements, for several basic
300     arithmetic element types including ``Int`` and ``Char``: see the
301     ``Data.Array.Unboxed`` library for details. These arrays are likely
302     to be much faster than using standard Haskell 98 arrays from the
303     ``Data.Array`` library.
304
305 Use a bigger heap!
306     If your program's GC stats (:rts-flag:`-S [⟨file⟩]` RTS option) indicate
307     that it's doing lots of garbage-collection (say, more than 20% of execution
308     time), more memory might help — with the ``-H⟨size⟩`` or ``-A⟨size⟩`` RTS
309     options (see :ref:`rts-options-gc`). As a rule of thumb, try setting
310     ``-H⟨size⟩`` to the amount of memory you're willing to let your process
311     consume, or perhaps try passing :ghc-flag:`-H ⟨size⟩` without any argument
312     to let GHC calculate a value based on the amount of live data.
313
314 Compact your data:
315     The :compact-ref:`GHC.Compact <GHC-Compact.html>` module
316     provides a way to make garbage collection more efficient for
317     long-lived data structures. Compacting a data structure collects
318     the objects together in memory, where they are treated as a single
319     object by the garbage collector and not traversed individually.
320
321 .. _smaller:
322
323 Smaller: producing a program that is smaller
324 --------------------------------------------
325
326 .. index::
327    single: smaller programs, how to produce
328    single: -funfolding-use-threshold0 option
329
330 Decrease the "go-for-it" threshold for unfolding smallish expressions.
331 Give a ``-funfolding-use-threshold0`` option for the extreme case.
332 (“Only unfoldings with zero cost should proceed.”) Warning: except in
333 certain specialised cases (like Happy parsers) this is likely to
334 actually *increase* the size of your program, because unfolding
335 generally enables extra simplifying optimisations to be performed.
336
337 Avoid ``Read``.
338
339 Use :command:`strip` on your executables.
340
341 .. _thriftier:
342
343 Thriftier: producing a program that gobbles less heap space
344 -----------------------------------------------------------
345
346 .. index::
347    single: memory, using less heap
348    single: space-leaks, avoiding
349    single: heap space, using less
350
351 "I think I have a space leak..."
352
353 Re-run your program with ``+RTS -S``, and remove all doubt! (You'll see the
354 heap usage get bigger and bigger...) (Hmmm... this might be even easier with
355 the ``-G1`` RTS option; so... ``./a.out +RTS -S -G1``)
356
357 .. index::
358     single: -G RTS option
359     single: -S RTS option
360
361 Once again, the profiling facilities (:ref:`profiling`) are the basic
362 tool for demystifying the space behaviour of your program.
363
364 Strict functions are good for space usage, as they are for time, as
365 discussed in the previous section. Strict functions get right down to
366 business, rather than filling up the heap with closures (the system's
367 notes to itself about how to evaluate something, should it eventually be
368 required).