Add a CSE pass to Stg (#9291)
[ghc.git] / docs / users_guide / using-optimisation.rst
1 .. _options-optimise:
2
3 Optimisation (code improvement)
4 -------------------------------
5
6 .. index::
7    single: optimisation
8    single: improvement, code
9
10 The ``-O*`` options specify convenient "packages" of optimisation flags;
11 the ``-f*`` options described later on specify *individual*
12 optimisations to be turned on/off; the ``-m*`` options specify
13 *machine-specific* optimisations to be turned on/off.
14
15 Most of these options are boolean and have options to turn them both "on" and
16 "off" (beginning with the prefix ``no-``). For instance, while ``-fspecialise``
17 enables specialisation, ``-fno-specialise`` disables it. When multiple flags for
18 the same option appear in the command-line they are evaluated from left to
19 right. For instance, ``-fno-specialise -fspecialise`` will enable
20 specialisation.
21
22 It is important to note that the ``-O*`` flags are roughly equivalent to
23 combinations of ``-f*`` flags. For this reason, the effect of the
24 ``-O*`` and ``-f*`` flags is dependent upon the order in which they
25 occur on the command line.
26
27 For instance, take the example of ``-fno-specialise -O1``. Despite the
28 ``-fno-specialise`` appearing in the command line, specialisation will
29 still be enabled. This is the case as ``-O1`` implies ``-fspecialise``,
30 overriding the previous flag. By contrast, ``-O1 -fno-specialise`` will
31 compile without specialisation, as one would expect.
32
33 .. _optimise-pkgs:
34
35 ``-O*``: convenient “packages” of optimisation flags.
36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37
38 There are *many* options that affect the quality of code produced by
39 GHC. Most people only have a general goal, something like "Compile
40 quickly" or "Make my program run like greased lightning." The following
41 "packages" of optimisations (or lack thereof) should suffice.
42
43 Note that higher optimisation levels cause more cross-module
44 optimisation to be performed, which can have an impact on how much of
45 your program needs to be recompiled when you change something. This is
46 one reason to stick to no-optimisation when developing code.
47
48 .. ghc-flag:: -O*
49
50     This is taken to mean: “Please compile quickly; I'm not
51     over-bothered about compiled-code quality.” So, for example:
52     ``ghc -c Foo.hs``
53
54 .. ghc-flag:: -O0
55
56     Means "turn off all optimisation", reverting to the same settings as
57     if no ``-O`` options had been specified. Saying ``-O0`` can be
58     useful if e.g. ``make`` has inserted a ``-O`` on the command line
59     already.
60
61 .. ghc-flag:: -O
62               -O1
63
64     .. index::
65        single: optimise; normally
66
67     Means: "Generate good-quality code without taking too long about
68     it." Thus, for example: ``ghc -c -O Main.lhs``
69
70 .. ghc-flag:: -O2
71
72     .. index::
73        single: optimise; aggressively
74
75     Means: "Apply every non-dangerous optimisation, even if it means
76     significantly longer compile times."
77
78     The avoided "dangerous" optimisations are those that can make
79     runtime or space *worse* if you're unlucky. They are normally turned
80     on or off individually.
81
82 .. ghc-flag:: -Odph
83
84     .. index::
85        single: optimise; DPH
86
87     Enables all ``-O2`` optimisation, sets
88     ``-fmax-simplifier-iterations=20`` and ``-fsimplifier-phases=3``.
89     Designed for use with :ref:`Data Parallel Haskell (DPH) <dph>`.
90
91 We don't use a ``-O*`` flag for day-to-day work. We use ``-O`` to get
92 respectable speed; e.g., when we want to measure something. When we want
93 to go for broke, we tend to use ``-O2`` (and we go for lots of coffee
94 breaks).
95
96 The easiest way to see what ``-O`` (etc.) “really mean” is to run with
97 :ghc-flag:`-v`, then stand back in amazement.
98
99 .. _options-f:
100
101 ``-f*``: platform-independent flags
102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103
104 .. index::
105    single: -f\* options (GHC)
106    single: -fno-\* options (GHC)
107
108 These flags turn on and off individual optimisations. Flags marked as
109 on by default are enabled by ``-O``, and as such you shouldn't
110 need to set any of them explicitly. A flag ``-fwombat`` can be negated
111 by saying ``-fno-wombat``. See :ref:`options-f-compact` for a compact
112 list.
113
114 .. ghc-flag:: -fcase-merge
115
116     :default: on
117
118     Merge immediately-nested case expressions that scrutinise the same variable.
119     For example, ::
120
121           case x of
122              Red -> e1
123              _   -> case x of
124                       Blue -> e2
125                       Green -> e3
126
127     Is transformed to, ::
128
129           case x of
130              Red -> e1
131              Blue -> e2
132              Green -> e2
133
134 .. ghc-flag:: -fcase-folding
135
136     :default: on
137
138     Allow constant folding in case expressions that scrutinise some primops:
139     For example, ::
140
141           case x `minusWord#` 10## of
142              10## -> e1
143              20## -> e2
144              v    -> e3
145
146     Is transformed to, ::
147
148           case x of
149              20## -> e1
150              30## -> e2
151              _    -> let v = x `minusWord#` 10## in e3
152
153 .. ghc-flag:: -fcall-arity
154
155     :default: on
156
157     Enable call-arity analysis.
158
159 .. ghc-flag:: -fcmm-elim-common-blocks
160
161     :default: on
162
163     Enables the common block elimination optimisation
164     in the code generator. This optimisation attempts to find identical
165     Cmm blocks and eliminate the duplicates.
166
167 .. ghc-flag:: -fcmm-sink
168
169     :default: on
170
171     Enables the sinking pass in the code generator.
172     This optimisation attempts to find identical Cmm blocks and
173     eliminate the duplicates attempts to move variable bindings closer
174     to their usage sites. It also inlines simple expressions like
175     literals or registers.
176
177 .. ghc-flag:: -fcpr-off
178
179     Switch off CPR analysis in the demand analyser.
180
181 .. ghc-flag:: -fcse
182
183     :default: on
184
185     Enables the common-sub-expression elimination
186     optimisation. Switching this off can be useful if you have some
187     ``unsafePerformIO`` expressions that you don't want commoned-up.
188
189 .. ghc-flag:: -fstg-cse
190
191     :default: on
192
193     Enables the common-sub-expression elimination optimisation on the STG
194     intermediate language, where it is able to common up some subexpressions
195     that differ in their types, but not their represetation.
196
197 .. ghc-flag:: -fdicts-cheap
198
199     A very experimental flag that makes dictionary-valued expressions
200     seem cheap to the optimiser.
201
202 .. ghc-flag:: -fdicts-strict
203
204     Make dictionaries strict.
205
206 .. ghc-flag:: -fdmd-tx-dict-sel
207
208     *On by default for ``-O0``, ``-O``, ``-O2``.*
209
210     Use a special demand transformer for dictionary selectors.
211
212 .. ghc-flag:: -fdo-eta-reduction
213
214     :default: on
215
216     Eta-reduce lambda expressions, if doing so gets rid of a whole group of
217     lambdas.
218
219 .. ghc-flag:: -fdo-lambda-eta-expansion
220
221     :default: on
222
223     Eta-expand let-bindings to increase their arity.
224
225 .. ghc-flag:: -feager-blackholing
226
227     Usually GHC black-holes a thunk only when it switches threads. This
228     flag makes it do so as soon as the thunk is entered. See `Haskell on
229     a shared-memory
230     multiprocessor <http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/>`__.
231
232 .. ghc-flag:: -fexcess-precision
233
234     When this option is given, intermediate floating point values can
235     have a *greater* precision/range than the final type. Generally this
236     is a good thing, but some programs may rely on the exact
237     precision/range of ``Float``/``Double`` values and should not use
238     this option for their compilation.
239
240     Note that the 32-bit x86 native code generator only supports
241     excess-precision mode, so neither ``-fexcess-precision`` nor
242     ``-fno-excess-precision`` has any effect. This is a known bug, see
243     :ref:`bugs-ghc`.
244
245 .. ghc-flag:: -fexpose-all-unfoldings
246
247     An experimental flag to expose all unfoldings, even for very large
248     or recursive functions. This allows for all functions to be inlined
249     while usually GHC would avoid inlining larger functions.
250
251 .. ghc-flag:: -ffloat-in
252
253     :default: on
254
255     Float let-bindings inwards, nearer their binding
256     site. See `Let-floating: moving bindings to give faster programs
257     (ICFP'96) <http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz>`__.
258
259     This optimisation moves let bindings closer to their use site. The
260     benefit here is that this may avoid unnecessary allocation if the
261     branch the let is now on is never executed. It also enables other
262     optimisation passes to work more effectively as they have more
263     information locally.
264
265     This optimisation isn't always beneficial though (so GHC applies
266     some heuristics to decide when to apply it). The details get
267     complicated but a simple example is that it is often beneficial to
268     move let bindings outwards so that multiple let bindings can be
269     grouped into a larger single let binding, effectively batching their
270     allocation and helping the garbage collector and allocator.
271
272 .. ghc-flag:: -ffull-laziness
273
274     :default: on
275
276     Run the full laziness optimisation (also known as
277     let-floating), which floats let-bindings outside enclosing lambdas,
278     in the hope they will be thereby be computed less often. See
279     `Let-floating: moving bindings to give faster programs
280     (ICFP'96) <http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz>`__.
281     Full laziness increases sharing, which can lead to increased memory
282     residency.
283
284     .. note::
285        GHC doesn't implement complete full-laziness. When
286        optimisation in on, and ``-fno-full-laziness`` is not given, some
287        transformations that increase sharing are performed, such as
288        extracting repeated computations from a loop. These are the same
289        transformations that a fully lazy implementation would do, the
290        difference is that GHC doesn't consistently apply full-laziness, so
291        don't rely on it.
292
293 .. ghc-flag:: -ffun-to-thunk
294
295     :default: off
296
297     Worker-wrapper removes unused arguments, but usually we do not
298     remove them all, lest it turn a function closure into a thunk,
299     thereby perhaps creating a space leak and/or disrupting inlining.
300     This flag allows worker/wrapper to remove *all* value lambdas.
301
302 .. ghc-flag:: -fignore-asserts
303
304     :default: on
305
306     Causes GHC to ignore uses of the function ``Exception.assert`` in source
307     code (in other words, rewriting ``Exception.assert p e`` to ``e`` (see
308     :ref:`assertions`).
309
310 .. ghc-flag:: -fignore-interface-pragmas
311
312     Tells GHC to ignore all inessential information when reading
313     interface files. That is, even if :file:`M.hi` contains unfolding or
314     strictness information for a function, GHC will ignore that
315     information.
316
317 .. ghc-flag:: -flate-dmd-anal
318
319     Run demand analysis again, at the end of the simplification
320     pipeline. We found some opportunities for discovering strictness
321     that were not visible earlier; and optimisations like
322     :ghc-flag:`-fspec-constr` can create functions with unused arguments which
323     are eliminated by late demand analysis. Improvements are modest, but
324     so is the cost. See notes on the :ghc-wiki:`Trac wiki page <LateDmd>`.
325
326 .. ghc-flag:: -fliberate-case
327
328     *Off by default, but enabled by -O2.* Turn on the liberate-case
329     transformation. This unrolls recursive function once in its own RHS,
330     to avoid repeated case analysis of free variables. It's a bit like
331     the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for free
332     variables rather than arguments.
333
334 .. ghc-flag:: -fliberate-case-threshold=<n>
335
336     :default: 2000
337
338     Set the size threshold for the liberate-case transformation.
339
340 .. ghc-flag:: -floopification
341
342     :default: on
343
344     When this optimisation is enabled the code generator will turn all
345     self-recursive saturated tail calls into local jumps rather than
346     function calls.
347
348 .. ghc-flag:: -fmax-inline-alloc-size=<n>
349
350     :default: 128
351
352     Set the maximum size of inline array allocations to n bytes.
353     GHC will allocate non-pinned arrays of statically known size in the current
354     nursery block if they're no bigger than n bytes, ignoring GC overheap. This
355     value should be quite a bit smaller than the block size (typically: 4096).
356
357 .. ghc-flag:: -fmax-inline-memcpy-insn=<n>
358
359     :default: 32
360
361     Inline ``memcpy`` calls if they would generate no more than ⟨n⟩ pseudo-instructions.
362
363 .. ghc-flag:: -fmax-inline-memset-insns=<n>
364
365     :default: 32
366
367     Inline ``memset`` calls if they would generate no more than n pseudo
368     instructions.
369
370 .. ghc-flag:: -fmax-relevant-binds=<n>
371               -fno-max-relevant-bindings
372
373     :default: 6
374
375     The type checker sometimes displays a fragment of the type
376     environment in error messages, but only up to some maximum number,
377     set by this flag. Turning it off with
378     ``-fno-max-relevant-bindings`` gives an unlimited number.
379     Syntactically top-level bindings are also usually excluded (since
380     they may be numerous), but ``-fno-max-relevant-bindings`` includes
381     them too.
382
383 .. ghc-flag:: -fmax-uncovered-patterns=<n>
384
385     :default: 4
386
387     Maximum number of unmatched patterns to be shown in warnings generated by
388     :ghc-flag:`-Wincomplete-patterns` and :ghc-flag:`-Wincomplete-uni-patterns`.
389
390 .. ghc-flag:: -fmax-simplifier-iterations=<n>
391
392     :default: 4
393
394     Sets the maximal number of iterations for the simplifier.
395
396 .. ghc-flag:: -fmax-worker-args=<n>
397
398     :default: 10
399
400     If a worker has that many arguments, none will be unpacked anymore.
401
402 .. ghc-flag:: -fno-opt-coercion
403
404     Turn off the coercion optimiser.
405
406 .. ghc-flag:: -fno-pre-inlining
407
408     Turn off pre-inlining.
409
410 .. ghc-flag:: -fno-state-hack
411
412     Turn off the "state hack" whereby any lambda with a ``State#`` token
413     as argument is considered to be single-entry, hence it is considered
414     okay to inline things inside it. This can improve performance of IO
415     and ST monad code, but it runs the risk of reducing sharing.
416
417 .. ghc-flag:: -fomit-interface-pragmas
418
419     Tells GHC to omit all inessential information from the interface
420     file generated for the module being compiled (say M). This means
421     that a module importing M will see only the *types* of the functions
422     that M exports, but not their unfoldings, strictness info, etc.
423     Hence, for example, no function exported by M will be inlined into
424     an importing module. The benefit is that modules that import M will
425     need to be recompiled less often (only when M's exports change their
426     type, not when they change their implementation).
427
428 .. ghc-flag:: -fomit-yields
429
430     :default: on
431
432     Tells GHC to omit heap checks when no allocation is
433     being performed. While this improves binary sizes by about 5%, it
434     also means that threads run in tight non-allocating loops will not
435     get preempted in a timely fashion. If it is important to always be
436     able to interrupt such threads, you should turn this optimization
437     off. Consider also recompiling all libraries with this optimization
438     turned off, if you need to guarantee interruptibility.
439
440 .. ghc-flag:: -fpedantic-bottoms
441
442     Make GHC be more precise about its treatment of bottom (but see also
443     :ghc-flag:`-fno-state-hack`). In particular, stop GHC eta-expanding through
444     a case expression, which is good for performance, but bad if you are
445     using ``seq`` on partial applications.
446
447 .. ghc-flag:: -fregs-graph
448
449     :default: off due to a performance regression bug (:ghc-ticket:`7679`)
450
451     *Only applies in combination with the native code generator.* Use the graph
452     colouring register allocator for register allocation in the native code
453     generator. By default, GHC uses a simpler, faster linear register allocator.
454     The downside being that the linear register allocator usually generates
455     worse code.
456
457     Note that the graph colouring allocator is a bit experimental and may fail
458     when faced with code with high register pressure :ghc-ticket:`8657`.
459
460 .. ghc-flag:: -fregs-iterative
461
462     :default: off
463
464     *Only applies in combination with the native code generator.* Use the
465     iterative coalescing graph colouring register allocator for register
466     allocation in the native code generator. This is the same register allocator
467     as the :ghc-flag:`-fregs-graph` one but also enables iterative coalescing
468     during register allocation.
469
470 .. ghc-flag:: -fsimplifier-phases=<n>
471
472     :default: 2
473
474     Set the number of phases for the simplifier. Ignored with ``-O0``.
475
476 .. ghc-flag:: -fsimpl-tick-factor=<n>
477
478     :default: 100
479
480     GHC's optimiser can diverge if you write rewrite rules
481     (:ref:`rewrite-rules`) that don't terminate, or (less satisfactorily)
482     if you code up recursion through data types (:ref:`bugs-ghc`). To
483     avoid making the compiler fall into an infinite loop, the optimiser
484     carries a "tick count" and stops inlining and applying rewrite rules
485     when this count is exceeded. The limit is set as a multiple of the
486     program size, so bigger programs get more ticks. The
487     ``-fsimpl-tick-factor`` flag lets you change the multiplier. The
488     default is 100; numbers larger than 100 give more ticks, and numbers
489     smaller than 100 give fewer.
490
491     If the tick-count expires, GHC summarises what simplifier steps it
492     has done; you can use ``-fddump-simpl-stats`` to generate a much
493     more detailed list. Usually that identifies the loop quite
494     accurately, because some numbers are very large.
495
496 .. ghc-flag:: -fspec-constr
497
498     *Off by default, but enabled by -O2.* Turn on call-pattern
499     specialisation; see `Call-pattern specialisation for Haskell
500     programs <http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm>`__.
501
502     This optimisation specializes recursive functions according to their
503     argument "shapes". This is best explained by example so consider: ::
504
505         last :: [a] -> a
506         last [] = error "last"
507         last (x : []) = x
508         last (x : xs) = last xs
509
510     In this code, once we pass the initial check for an empty list we
511     know that in the recursive case this pattern match is redundant. As
512     such ``-fspec-constr`` will transform the above code to: ::
513
514         last :: [a] -> a
515         last []       = error "last"
516         last (x : xs) = last' x xs
517             where
518               last' x []       = x
519               last' x (y : ys) = last' y ys
520
521     As well avoid unnecessary pattern matching it also helps avoid
522     unnecessary allocation. This applies when a argument is strict in
523     the recursive call to itself but not on the initial entry. As strict
524     recursive branch of the function is created similar to the above
525     example.
526
527     It is also possible for library writers to instruct GHC to perform
528     call-pattern specialisation extremely aggressively. This is
529     necessary for some highly optimized libraries, where we may want to
530     specialize regardless of the number of specialisations, or the size
531     of the code. As an example, consider a simplified use-case from the
532     ``vector`` library: ::
533
534         import GHC.Types (SPEC(..))
535
536         foldl :: (a -> b -> a) -> a -> Stream b -> a
537         {-# INLINE foldl #-}
538         foldl f z (Stream step s _) = foldl_loop SPEC z s
539           where
540             foldl_loop !sPEC z s = case step s of
541                                     Yield x s' -> foldl_loop sPEC (f z x) s'
542                                     Skip       -> foldl_loop sPEC z s'
543                                     Done       -> z
544
545     Here, after GHC inlines the body of ``foldl`` to a call site, it
546     will perform call-pattern specialisation very aggressively on
547     ``foldl_loop`` due to the use of ``SPEC`` in the argument of the
548     loop body. ``SPEC`` from ``GHC.Types`` is specifically recognised by
549     the compiler.
550
551     (NB: it is extremely important you use ``seq`` or a bang pattern on
552     the ``SPEC`` argument!)
553
554     In particular, after inlining this will expose ``f`` to the loop
555     body directly, allowing heavy specialisation over the recursive
556     cases.
557
558 .. ghc-flag:: -fspec-constr-count=<n>
559
560     :default: 3
561
562     Set the maximum number of specialisations that will be created for
563     any one function by the SpecConstr transformation.
564
565 .. ghc-flag:: -fspec-constr-threshold=<n>
566
567     :default: 2000
568
569     Set the size threshold for the SpecConstr transformation.
570
571 .. ghc-flag:: -fspecialise
572
573     :default: on
574
575     Specialise each type-class-overloaded function
576     defined in this module for the types at which it is called in this
577     module. If :ghc-flag:`-fcross-module-specialise` is set imported functions
578     that have an INLINABLE pragma (:ref:`inlinable-pragma`) will be
579     specialised as well.
580
581 .. ghc-flag:: -fcross-module-specialise
582
583     :default: on
584
585     Specialise ``INLINABLE`` (:ref:`inlinable-pragma`)
586     type-class-overloaded functions imported from other modules for the types at
587     which they are called in this module. Note that specialisation must be
588     enabled (by ``-fspecialise``) for this to have any effect.
589
590 .. ghc-flag:: -fstatic-argument-transformation
591
592     Turn on the static argument transformation, which turns a recursive
593     function into a non-recursive one with a local recursive loop. See
594     Chapter 7 of `Andre Santos's PhD
595     thesis <http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz>`__
596
597 .. ghc-flag:: -fstrictness
598
599     :default: on
600
601     Switch on the strictness analyser. There is a very
602     old paper about GHC's strictness analyser, `Measuring the
603     effectiveness of a simple strictness
604     analyser <http://research.microsoft.com/en-us/um/people/simonpj/papers/simple-strictnes-analyser.ps.gz>`__,
605     but the current one is quite a bit different.
606
607     The strictness analyser figures out when arguments and variables in
608     a function can be treated 'strictly' (that is they are always
609     evaluated in the function at some point). This allow GHC to apply
610     certain optimisations such as unboxing that otherwise don't apply as
611     they change the semantics of the program when applied to lazy
612     arguments.
613
614 .. ghc-flag:: -fstrictness-before=⟨n⟩
615
616     Run an additional strictness analysis before simplifier phase ⟨n⟩.
617
618 .. ghc-flag:: -funbox-small-strict-fields
619
620     :default: on
621
622     .. index::
623        single: strict constructor fields
624        single: constructor fields, strict
625
626     This option causes all constructor fields which
627     are marked strict (i.e. “!”) and which representation is smaller or
628     equal to the size of a pointer to be unpacked, if possible. It is
629     equivalent to adding an ``UNPACK`` pragma (see :ref:`unpack-pragma`)
630     to every strict constructor field that fulfils the size restriction.
631
632     For example, the constructor fields in the following data types ::
633
634         data A = A !Int
635         data B = B !A
636         newtype C = C B
637         data D = D !C
638
639     would all be represented by a single ``Int#`` (see
640     :ref:`primitives`) value with ``-funbox-small-strict-fields``
641     enabled.
642
643     This option is less of a sledgehammer than
644     ``-funbox-strict-fields``: it should rarely make things worse. If
645     you use ``-funbox-small-strict-fields`` to turn on unboxing by
646     default you can disable it for certain constructor fields using the
647     ``NOUNPACK`` pragma (see :ref:`nounpack-pragma`).
648
649     Note that for consistency ``Double``, ``Word64``, and ``Int64``
650     constructor fields are unpacked on 32-bit platforms, even though
651     they are technically larger than a pointer on those platforms.
652
653 .. ghc-flag:: -funbox-strict-fields
654
655     .. index::
656        single: strict constructor fields
657        single: constructor fields, strict
658
659     This option causes all constructor fields which are marked strict
660     (i.e. ``!``) to be unpacked if possible. It is equivalent to adding an
661     ``UNPACK`` pragma to every strict constructor field (see
662     :ref:`unpack-pragma`).
663
664     This option is a bit of a sledgehammer: it might sometimes make
665     things worse. Selectively unboxing fields by using ``UNPACK``
666     pragmas might be better. An alternative is to use
667     ``-funbox-strict-fields`` to turn on unboxing by default but disable
668     it for certain constructor fields using the ``NOUNPACK`` pragma (see
669     :ref:`nounpack-pragma`).
670
671 .. ghc-flag:: -funfolding-creation-threshold=<n>
672
673     :default: 750
674
675     .. index::
676        single: inlining, controlling
677        single: unfolding, controlling
678
679     Governs the maximum size that GHC will allow a
680     function unfolding to be. (An unfolding has a “size” that reflects
681     the cost in terms of “code bloat” of expanding (aka inlining) that
682     unfolding at a call site. A bigger function would be assigned a
683     bigger cost.)
684
685     Consequences:
686
687     a. nothing larger than this will be inlined (unless it has an ``INLINE`` pragma)
688     b. nothing larger than this will be spewed into an interface file.
689
690     Increasing this figure is more likely to result in longer compile
691     times than faster code. The :ghc-flag:`-funfolding-use-threshold` is more
692     useful.
693
694 .. ghc-flag:: -funfolding-dict-discount=<n>
695
696     :default: 30
697
698     .. index::
699        single: inlining, controlling
700        single: unfolding, controlling
701
702     How eager should the compiler be to inline dictionaries?
703
704 .. ghc-flag:: -funfolding-fun-discount=<n>
705
706     :default: 60
707
708     .. index::
709        single: inlining, controlling
710        single: unfolding, controlling
711
712     How eager should the compiler be to inline functions?
713
714 .. ghc-flag:: -funfolding-keeness-factor=<n>
715
716     :default: 1.5
717
718     .. index::
719        single: inlining, controlling
720        single: unfolding, controlling
721
722     How eager should the compiler be to inline functions?
723
724 .. ghc-flag:: -funfolding-use-threshold=<n>
725
726     :default: 60
727
728     .. index::
729        single: inlining, controlling
730        single: unfolding, controlling
731
732     This is the magic cut-off figure for unfolding (aka
733     inlining): below this size, a function definition will be unfolded
734     at the call-site, any bigger and it won't. The size computed for a
735     function depends on two things: the actual size of the expression
736     minus any discounts that apply depending on the context into which
737     the expression is to be inlined.
738
739     The difference between this and :ghc-flag:`-funfolding-creation-threshold`
740     is that this one determines if a function definition will be inlined
741     *at a call site*. The other option determines if a function
742     definition will be kept around at all for potential inlining.
743
744 .. ghc-flag:: -fvectorisation-avoidance
745
746     :default: on
747
748     .. index::
749        single: -fvectorisation-avoidance
750
751     Part of :ref:`Data Parallel Haskell (DPH) <dph>`.
752
753     Enable the *vectorisation* avoidance optimisation.
754     This optimisation only works when used in combination with the
755     ``-fvectorise`` transformation.
756
757     While vectorisation of code using DPH is often a big win, it can
758     also produce worse results for some kinds of code. This optimisation
759     modifies the vectorisation transformation to try to determine if a
760     function would be better of unvectorised and if so, do just that.
761
762 .. ghc-flag:: -fvectorise
763
764     :default: off
765
766     Part of :ref:`Data Parallel Haskell (DPH) <dph>`.
767
768     Enable the *vectorisation* optimisation
769     transformation. This optimisation transforms the nested data
770     parallelism code of programs using DPH into flat data parallelism.
771     Flat data parallel programs should have better load balancing,
772     enable SIMD parallelism and friendlier cache behaviour.