Update link to paper about demand analyser in user guide
[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     :default: off
200
201     A very experimental flag that makes dictionary-valued expressions
202     seem cheap to the optimiser.
203
204 .. ghc-flag:: -fdicts-strict
205
206     :default: off
207
208     Make dictionaries strict.
209
210 .. ghc-flag:: -fdmd-tx-dict-sel
211
212     :default: on
213
214     Use a special demand transformer for dictionary selectors.
215
216 .. ghc-flag:: -fdo-eta-reduction
217
218     :default: on
219
220     Eta-reduce lambda expressions, if doing so gets rid of a whole group of
221     lambdas.
222
223 .. ghc-flag:: -fdo-lambda-eta-expansion
224
225     :default: on
226
227     Eta-expand let-bindings to increase their arity.
228
229 .. ghc-flag:: -feager-blackholing
230
231     :default: off
232
233     Usually GHC black-holes a thunk only when it switches threads. This
234     flag makes it do so as soon as the thunk is entered. See `Haskell on
235     a shared-memory
236     multiprocessor <http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/>`__.
237
238 .. ghc-flag:: -fexcess-precision
239
240     :default: off
241
242     When this option is given, intermediate floating point values can
243     have a *greater* precision/range than the final type. Generally this
244     is a good thing, but some programs may rely on the exact
245     precision/range of ``Float``/``Double`` values and should not use
246     this option for their compilation.
247
248     Note that the 32-bit x86 native code generator only supports
249     excess-precision mode, so neither ``-fexcess-precision`` nor
250     ``-fno-excess-precision`` has any effect. This is a known bug, see
251     :ref:`bugs-ghc`.
252
253 .. ghc-flag:: -fexpose-all-unfoldings
254
255     :default: off
256
257     An experimental flag to expose all unfoldings, even for very large
258     or recursive functions. This allows for all functions to be inlined
259     while usually GHC would avoid inlining larger functions.
260
261 .. ghc-flag:: -ffloat-in
262
263     :default: on
264
265     Float let-bindings inwards, nearer their binding
266     site. See `Let-floating: moving bindings to give faster programs
267     (ICFP'96) <http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz>`__.
268
269     This optimisation moves let bindings closer to their use site. The
270     benefit here is that this may avoid unnecessary allocation if the
271     branch the let is now on is never executed. It also enables other
272     optimisation passes to work more effectively as they have more
273     information locally.
274
275     This optimisation isn't always beneficial though (so GHC applies
276     some heuristics to decide when to apply it). The details get
277     complicated but a simple example is that it is often beneficial to
278     move let bindings outwards so that multiple let bindings can be
279     grouped into a larger single let binding, effectively batching their
280     allocation and helping the garbage collector and allocator.
281
282 .. ghc-flag:: -ffull-laziness
283
284     :default: on
285
286     Run the full laziness optimisation (also known as
287     let-floating), which floats let-bindings outside enclosing lambdas,
288     in the hope they will be thereby be computed less often. See
289     `Let-floating: moving bindings to give faster programs
290     (ICFP'96) <http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz>`__.
291     Full laziness increases sharing, which can lead to increased memory
292     residency.
293
294     .. note::
295        GHC doesn't implement complete full-laziness. When
296        optimisation in on, and ``-fno-full-laziness`` is not given, some
297        transformations that increase sharing are performed, such as
298        extracting repeated computations from a loop. These are the same
299        transformations that a fully lazy implementation would do, the
300        difference is that GHC doesn't consistently apply full-laziness, so
301        don't rely on it.
302
303 .. ghc-flag:: -ffun-to-thunk
304
305     :default: off
306
307     Worker-wrapper removes unused arguments, but usually we do not
308     remove them all, lest it turn a function closure into a thunk,
309     thereby perhaps creating a space leak and/or disrupting inlining.
310     This flag allows worker/wrapper to remove *all* value lambdas.
311
312 .. ghc-flag:: -fignore-asserts
313
314     :default: on
315
316     Causes GHC to ignore uses of the function ``Exception.assert`` in source
317     code (in other words, rewriting ``Exception.assert p e`` to ``e`` (see
318     :ref:`assertions`).
319
320 .. ghc-flag:: -fignore-interface-pragmas
321
322     :default: off
323
324     Tells GHC to ignore all inessential information when reading
325     interface files. That is, even if :file:`M.hi` contains unfolding or
326     strictness information for a function, GHC will ignore that
327     information.
328
329 .. ghc-flag:: -flate-dmd-anal
330
331     :default: off
332
333     Run demand analysis again, at the end of the simplification
334     pipeline. We found some opportunities for discovering strictness
335     that were not visible earlier; and optimisations like
336     :ghc-flag:`-fspec-constr` can create functions with unused arguments which
337     are eliminated by late demand analysis. Improvements are modest, but
338     so is the cost. See notes on the :ghc-wiki:`Trac wiki page <LateDmd>`.
339
340 .. ghc-flag:: -fliberate-case
341
342     :default: off but enabled with :ghc-flag:`-O2`.
343
344     Turn on the liberate-case transformation. This unrolls recursive function
345     once in its own RHS, to avoid repeated case analysis of free variables. It's
346     a bit like the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for
347     free variables rather than arguments.
348
349 .. ghc-flag:: -fliberate-case-threshold=<n>
350
351     :default: 2000
352
353     Set the size threshold for the liberate-case transformation.
354
355 .. ghc-flag:: -floopification
356
357     :default: on
358
359     When this optimisation is enabled the code generator will turn all
360     self-recursive saturated tail calls into local jumps rather than
361     function calls.
362
363 .. ghc-flag:: -fmax-inline-alloc-size=<n>
364
365     :default: 128
366
367     Set the maximum size of inline array allocations to n bytes.
368     GHC will allocate non-pinned arrays of statically known size in the current
369     nursery block if they're no bigger than n bytes, ignoring GC overheap. This
370     value should be quite a bit smaller than the block size (typically: 4096).
371
372 .. ghc-flag:: -fmax-inline-memcpy-insn=<n>
373
374     :default: 32
375
376     Inline ``memcpy`` calls if they would generate no more than ⟨n⟩ pseudo-instructions.
377
378 .. ghc-flag:: -fmax-inline-memset-insns=<n>
379
380     :default: 32
381
382     Inline ``memset`` calls if they would generate no more than n pseudo
383     instructions.
384
385 .. ghc-flag:: -fmax-relevant-binds=<n>
386               -fno-max-relevant-bindings
387
388     :default: 6
389
390     The type checker sometimes displays a fragment of the type
391     environment in error messages, but only up to some maximum number,
392     set by this flag. Turning it off with
393     ``-fno-max-relevant-bindings`` gives an unlimited number.
394     Syntactically top-level bindings are also usually excluded (since
395     they may be numerous), but ``-fno-max-relevant-bindings`` includes
396     them too.
397
398 .. ghc-flag:: -fmax-uncovered-patterns=<n>
399
400     :default: 4
401
402     Maximum number of unmatched patterns to be shown in warnings generated by
403     :ghc-flag:`-Wincomplete-patterns` and :ghc-flag:`-Wincomplete-uni-patterns`.
404
405 .. ghc-flag:: -fmax-simplifier-iterations=<n>
406
407     :default: 4
408
409     Sets the maximal number of iterations for the simplifier.
410
411 .. ghc-flag:: -fmax-worker-args=<n>
412
413     :default: 10
414
415     If a worker has that many arguments, none will be unpacked anymore.
416
417 .. ghc-flag:: -fno-opt-coercion
418
419     :default: off
420
421     Turn off the coercion optimiser.
422
423 .. ghc-flag:: -fno-pre-inlining
424
425     :default: off
426
427     Turn off pre-inlining.
428
429 .. ghc-flag:: -fno-state-hack
430
431     :default: off
432
433     Turn off the "state hack" whereby any lambda with a ``State#`` token
434     as argument is considered to be single-entry, hence it is considered
435     okay to inline things inside it. This can improve performance of IO
436     and ST monad code, but it runs the risk of reducing sharing.
437
438 .. ghc-flag:: -fomit-interface-pragmas
439
440     :default: off
441
442     Tells GHC to omit all inessential information from the interface
443     file generated for the module being compiled (say M). This means
444     that a module importing M will see only the *types* of the functions
445     that M exports, but not their unfoldings, strictness info, etc.
446     Hence, for example, no function exported by M will be inlined into
447     an importing module. The benefit is that modules that import M will
448     need to be recompiled less often (only when M's exports change their
449     type, not when they change their implementation).
450
451 .. ghc-flag:: -fomit-yields
452
453     :default: on
454
455     Tells GHC to omit heap checks when no allocation is
456     being performed. While this improves binary sizes by about 5%, it
457     also means that threads run in tight non-allocating loops will not
458     get preempted in a timely fashion. If it is important to always be
459     able to interrupt such threads, you should turn this optimization
460     off. Consider also recompiling all libraries with this optimization
461     turned off, if you need to guarantee interruptibility.
462
463 .. ghc-flag:: -fpedantic-bottoms
464
465     Make GHC be more precise about its treatment of bottom (but see also
466     :ghc-flag:`-fno-state-hack`). In particular, stop GHC eta-expanding through
467     a case expression, which is good for performance, but bad if you are
468     using ``seq`` on partial applications.
469
470 .. ghc-flag:: -fregs-graph
471
472     :default: off due to a performance regression bug (:ghc-ticket:`7679`)
473
474     *Only applies in combination with the native code generator.* Use the graph
475     colouring register allocator for register allocation in the native code
476     generator. By default, GHC uses a simpler, faster linear register allocator.
477     The downside being that the linear register allocator usually generates
478     worse code.
479
480     Note that the graph colouring allocator is a bit experimental and may fail
481     when faced with code with high register pressure :ghc-ticket:`8657`.
482
483 .. ghc-flag:: -fregs-iterative
484
485     :default: off
486
487     *Only applies in combination with the native code generator.* Use the
488     iterative coalescing graph colouring register allocator for register
489     allocation in the native code generator. This is the same register allocator
490     as the :ghc-flag:`-fregs-graph` one but also enables iterative coalescing
491     during register allocation.
492
493 .. ghc-flag:: -fsimplifier-phases=<n>
494
495     :default: 2
496
497     Set the number of phases for the simplifier. Ignored with ``-O0``.
498
499 .. ghc-flag:: -fsimpl-tick-factor=<n>
500
501     :default: 100
502
503     GHC's optimiser can diverge if you write rewrite rules
504     (:ref:`rewrite-rules`) that don't terminate, or (less satisfactorily)
505     if you code up recursion through data types (:ref:`bugs-ghc`). To
506     avoid making the compiler fall into an infinite loop, the optimiser
507     carries a "tick count" and stops inlining and applying rewrite rules
508     when this count is exceeded. The limit is set as a multiple of the
509     program size, so bigger programs get more ticks. The
510     ``-fsimpl-tick-factor`` flag lets you change the multiplier. The
511     default is 100; numbers larger than 100 give more ticks, and numbers
512     smaller than 100 give fewer.
513
514     If the tick-count expires, GHC summarises what simplifier steps it
515     has done; you can use ``-fddump-simpl-stats`` to generate a much
516     more detailed list. Usually that identifies the loop quite
517     accurately, because some numbers are very large.
518
519 .. ghc-flag:: -fspec-constr
520
521     :default: off but enabled by :ghc-flag:`-O2`.
522
523     Turn on call-pattern specialisation; see `Call-pattern specialisation for
524     Haskell programs
525     <https://www.microsoft.com/en-us/research/publication/system-f-with-type-equality-coercions-2/>`__.
526
527     This optimisation specializes recursive functions according to their
528     argument "shapes". This is best explained by example so consider: ::
529
530         last :: [a] -> a
531         last [] = error "last"
532         last (x : []) = x
533         last (x : xs) = last xs
534
535     In this code, once we pass the initial check for an empty list we
536     know that in the recursive case this pattern match is redundant. As
537     such ``-fspec-constr`` will transform the above code to: ::
538
539         last :: [a] -> a
540         last []       = error "last"
541         last (x : xs) = last' x xs
542             where
543               last' x []       = x
544               last' x (y : ys) = last' y ys
545
546     As well avoid unnecessary pattern matching it also helps avoid
547     unnecessary allocation. This applies when a argument is strict in
548     the recursive call to itself but not on the initial entry. As strict
549     recursive branch of the function is created similar to the above
550     example.
551
552     It is also possible for library writers to instruct GHC to perform
553     call-pattern specialisation extremely aggressively. This is
554     necessary for some highly optimized libraries, where we may want to
555     specialize regardless of the number of specialisations, or the size
556     of the code. As an example, consider a simplified use-case from the
557     ``vector`` library: ::
558
559         import GHC.Types (SPEC(..))
560
561         foldl :: (a -> b -> a) -> a -> Stream b -> a
562         {-# INLINE foldl #-}
563         foldl f z (Stream step s _) = foldl_loop SPEC z s
564           where
565             foldl_loop !sPEC z s = case step s of
566                                     Yield x s' -> foldl_loop sPEC (f z x) s'
567                                     Skip       -> foldl_loop sPEC z s'
568                                     Done       -> z
569
570     Here, after GHC inlines the body of ``foldl`` to a call site, it
571     will perform call-pattern specialisation very aggressively on
572     ``foldl_loop`` due to the use of ``SPEC`` in the argument of the
573     loop body. ``SPEC`` from ``GHC.Types`` is specifically recognised by
574     the compiler.
575
576     (NB: it is extremely important you use ``seq`` or a bang pattern on
577     the ``SPEC`` argument!)
578
579     In particular, after inlining this will expose ``f`` to the loop
580     body directly, allowing heavy specialisation over the recursive
581     cases.
582
583 .. ghc-flag:: -fspec-constr-keen
584
585     :default: off
586
587     If this flag is on, call-patten specialision will specialise a call
588     ``(f (Just x))`` with an explicit constructor agument, even if the argument
589     is not scrutinised in the body of the function. This is sometimes
590     beneficial; e.g. the argument might be given to some other function
591     that can itself be specialised.
592
593 .. ghc-flag:: -fspec-constr-count=<n>
594
595     :default: 3
596
597     Set the maximum number of specialisations that will be created for
598     any one function by the SpecConstr transformation.
599
600 .. ghc-flag:: -fspec-constr-threshold=<n>
601
602     :default: 2000
603
604     Set the size threshold for the SpecConstr transformation.
605
606 .. ghc-flag:: -fspecialise
607
608     :default: on
609
610     Specialise each type-class-overloaded function
611     defined in this module for the types at which it is called in this
612     module. If :ghc-flag:`-fcross-module-specialise` is set imported functions
613     that have an INLINABLE pragma (:ref:`inlinable-pragma`) will be
614     specialised as well.
615
616 .. ghc-flag:: -fspecialise-aggressively
617
618     :default: off
619
620     By default only type class methods and methods marked ``INLINABLE`` or
621     ``INLINE`` are specialised. This flag will specialise any overloaded function
622     regardless of size if its unfolding is available. This flag is not
623     included in any optimisation level as it can massively increase code
624     size. It can be used in conjunction with :ghc-flag:`-fexpose-all-unfoldings`
625     if you want to ensure all calls are specialised.
626
627
628 .. ghc-flag:: -fcross-module-specialise
629
630     :default: on
631
632     Specialise ``INLINABLE`` (:ref:`inlinable-pragma`)
633     type-class-overloaded functions imported from other modules for the types at
634     which they are called in this module. Note that specialisation must be
635     enabled (by ``-fspecialise``) for this to have any effect.
636
637 .. ghc-flag:: -fsolve-constant-dicts
638
639     :default: on
640
641     When solving constraints, try to eagerly solve
642     super classes using availible dictionaries.
643
644     For example::
645
646       class M a b where m :: a -> b
647
648       type C a b = (Num a, M a b)
649
650       f :: C Int b => b -> Int -> Int
651       f _ x = x + 1
652
653     The body of `f` requires a `Num Int` instance. We could solve this
654     constraint from the context  because we have `C Int b` and that provides us
655     a
656     solution for `Num Int`. However, we can often produce much better code
657     by directly solving for an availible `Num Int` dictionary we might have at
658     hand. This removes potentially many layers of indirection and crucially
659     allows other optimisations to fire as the dictionary will be statically
660     known and selector functions can be inlined.
661
662     The optimisation also works for GADTs which bind dictionaries. If we
663     statically know which class dictionary we need then we will solve it
664     directly rather than indirectly using the one passed in at run time.
665
666
667
668 .. ghc-flag:: -fstatic-argument-transformation
669
670     :default: off
671
672     Turn on the static argument transformation, which turns a recursive
673     function into a non-recursive one with a local recursive loop. See
674     Chapter 7 of `Andre Santos's PhD
675     thesis <http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz>`__
676
677 .. ghc-flag:: -fstrictness
678
679     :default: on
680
681     Switch on the strictness analyser. The
682     implementation is described in the paper `Theory and Practice of Demand Analysis in Haskell`<https://www.microsoft.com/en-us/research/wp-content/uploads/2017/03/demand-jfp-draft.pdf>`__.
683
684     The strictness analyser figures out when arguments and variables in
685     a function can be treated 'strictly' (that is they are always
686     evaluated in the function at some point). This allow GHC to apply
687     certain optimisations such as unboxing that otherwise don't apply as
688     they change the semantics of the program when applied to lazy
689     arguments.
690
691 .. ghc-flag:: -fstrictness-before=⟨n⟩
692
693     Run an additional strictness analysis before simplifier phase ⟨n⟩.
694
695 .. ghc-flag:: -funbox-small-strict-fields
696
697     :default: on
698
699     .. index::
700        single: strict constructor fields
701        single: constructor fields, strict
702
703     This option causes all constructor fields which
704     are marked strict (i.e. “!”) and which representation is smaller or
705     equal to the size of a pointer to be unpacked, if possible. It is
706     equivalent to adding an ``UNPACK`` pragma (see :ref:`unpack-pragma`)
707     to every strict constructor field that fulfils the size restriction.
708
709     For example, the constructor fields in the following data types ::
710
711         data A = A !Int
712         data B = B !A
713         newtype C = C B
714         data D = D !C
715
716     would all be represented by a single ``Int#`` (see
717     :ref:`primitives`) value with ``-funbox-small-strict-fields``
718     enabled.
719
720     This option is less of a sledgehammer than
721     ``-funbox-strict-fields``: it should rarely make things worse. If
722     you use ``-funbox-small-strict-fields`` to turn on unboxing by
723     default you can disable it for certain constructor fields using the
724     ``NOUNPACK`` pragma (see :ref:`nounpack-pragma`).
725
726     Note that for consistency ``Double``, ``Word64``, and ``Int64``
727     constructor fields are unpacked on 32-bit platforms, even though
728     they are technically larger than a pointer on those platforms.
729
730 .. ghc-flag:: -funbox-strict-fields
731
732     :default: off
733
734     .. index::
735        single: strict constructor fields
736        single: constructor fields, strict
737
738     This option causes all constructor fields which are marked strict
739     (i.e. ``!``) to be unpacked if possible. It is equivalent to adding an
740     ``UNPACK`` pragma to every strict constructor field (see
741     :ref:`unpack-pragma`).
742
743     This option is a bit of a sledgehammer: it might sometimes make
744     things worse. Selectively unboxing fields by using ``UNPACK``
745     pragmas might be better. An alternative is to use
746     ``-funbox-strict-fields`` to turn on unboxing by default but disable
747     it for certain constructor fields using the ``NOUNPACK`` pragma (see
748     :ref:`nounpack-pragma`).
749
750     Alternatively you can use :ghc-flag:`-funbox-small-strict-fields` to only
751     unbox strict fields which are "small".
752
753 .. ghc-flag:: -funfolding-creation-threshold=<n>
754
755     :default: 750
756
757     .. index::
758        single: inlining, controlling
759        single: unfolding, controlling
760
761     Governs the maximum size that GHC will allow a
762     function unfolding to be. (An unfolding has a “size” that reflects
763     the cost in terms of “code bloat” of expanding (aka inlining) that
764     unfolding at a call site. A bigger function would be assigned a
765     bigger cost.)
766
767     Consequences:
768
769     a. nothing larger than this will be inlined (unless it has an ``INLINE`` pragma)
770     b. nothing larger than this will be spewed into an interface file.
771
772     Increasing this figure is more likely to result in longer compile
773     times than faster code. The :ghc-flag:`-funfolding-use-threshold` is more
774     useful.
775
776 .. ghc-flag:: -funfolding-dict-discount=<n>
777
778     :default: 30
779
780     .. index::
781        single: inlining, controlling
782        single: unfolding, controlling
783
784     How eager should the compiler be to inline dictionaries?
785
786 .. ghc-flag:: -funfolding-fun-discount=<n>
787
788     :default: 60
789
790     .. index::
791        single: inlining, controlling
792        single: unfolding, controlling
793
794     How eager should the compiler be to inline functions?
795
796 .. ghc-flag:: -funfolding-keeness-factor=<n>
797
798     :default: 1.5
799
800     .. index::
801        single: inlining, controlling
802        single: unfolding, controlling
803
804     How eager should the compiler be to inline functions?
805
806 .. ghc-flag:: -funfolding-use-threshold=<n>
807
808     :default: 60
809
810     .. index::
811        single: inlining, controlling
812        single: unfolding, controlling
813
814     This is the magic cut-off figure for unfolding (aka
815     inlining): below this size, a function definition will be unfolded
816     at the call-site, any bigger and it won't. The size computed for a
817     function depends on two things: the actual size of the expression
818     minus any discounts that apply depending on the context into which
819     the expression is to be inlined.
820
821     The difference between this and :ghc-flag:`-funfolding-creation-threshold`
822     is that this one determines if a function definition will be inlined
823     *at a call site*. The other option determines if a function
824     definition will be kept around at all for potential inlining.
825
826 .. ghc-flag:: -fvectorisation-avoidance
827
828     :default: on
829
830     .. index::
831        single: -fvectorisation-avoidance
832
833     Part of :ref:`Data Parallel Haskell (DPH) <dph>`.
834
835     Enable the *vectorisation* avoidance optimisation.
836     This optimisation only works when used in combination with the
837     ``-fvectorise`` transformation.
838
839     While vectorisation of code using DPH is often a big win, it can
840     also produce worse results for some kinds of code. This optimisation
841     modifies the vectorisation transformation to try to determine if a
842     function would be better of unvectorised and if so, do just that.
843
844 .. ghc-flag:: -fvectorise
845
846     :default: off
847
848     Part of :ref:`Data Parallel Haskell (DPH) <dph>`.
849
850     Enable the *vectorisation* optimisation
851     transformation. This optimisation transforms the nested data
852     parallelism code of programs using DPH into flat data parallelism.
853     Flat data parallel programs should have better load balancing,
854     enable SIMD parallelism and friendlier cache behaviour.