summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBen Gamari <ben@smart-cactus.org>2017-02-08 15:49:46 -0500
committerBen Gamari <ben@smart-cactus.org>2017-02-08 15:49:46 -0500
commit41c7437e13494c548de83f10154ff35940748aaf (patch)
tree35e3b87798604699c183c96d7c12f809f61652a1
parent7e4e6a7309b2eb74933f95f18d83e74dbf166a7e (diff)
downloadhaskell-41c7437e13494c548de83f10154ff35940748aaf.tar.gz
users-guide: Document defaults for remaining optimization flags
-rw-r--r--docs/users_guide/using-optimisation.rst52
1 files changed, 42 insertions, 10 deletions
diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst
index 123d74bc8f..9436832611 100644
--- a/docs/users_guide/using-optimisation.rst
+++ b/docs/users_guide/using-optimisation.rst
@@ -196,16 +196,20 @@ list.
.. ghc-flag:: -fdicts-cheap
+ :default: off
+
A very experimental flag that makes dictionary-valued expressions
seem cheap to the optimiser.
.. ghc-flag:: -fdicts-strict
+ :default: off
+
Make dictionaries strict.
.. ghc-flag:: -fdmd-tx-dict-sel
- *On by default for ``-O0``, ``-O``, ``-O2``.*
+ :default: on
Use a special demand transformer for dictionary selectors.
@@ -224,6 +228,8 @@ list.
.. ghc-flag:: -feager-blackholing
+ :default: off
+
Usually GHC black-holes a thunk only when it switches threads. This
flag makes it do so as soon as the thunk is entered. See `Haskell on
a shared-memory
@@ -231,6 +237,8 @@ list.
.. ghc-flag:: -fexcess-precision
+ :default: off
+
When this option is given, intermediate floating point values can
have a *greater* precision/range than the final type. Generally this
is a good thing, but some programs may rely on the exact
@@ -244,6 +252,8 @@ list.
.. ghc-flag:: -fexpose-all-unfoldings
+ :default: off
+
An experimental flag to expose all unfoldings, even for very large
or recursive functions. This allows for all functions to be inlined
while usually GHC would avoid inlining larger functions.
@@ -309,6 +319,8 @@ list.
.. ghc-flag:: -fignore-interface-pragmas
+ :default: off
+
Tells GHC to ignore all inessential information when reading
interface files. That is, even if :file:`M.hi` contains unfolding or
strictness information for a function, GHC will ignore that
@@ -316,6 +328,8 @@ list.
.. ghc-flag:: -flate-dmd-anal
+ :default: off
+
Run demand analysis again, at the end of the simplification
pipeline. We found some opportunities for discovering strictness
that were not visible earlier; and optimisations like
@@ -325,11 +339,12 @@ list.
.. ghc-flag:: -fliberate-case
- *Off by default, but enabled by -O2.* Turn on the liberate-case
- transformation. This unrolls recursive function once in its own RHS,
- to avoid repeated case analysis of free variables. It's a bit like
- the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for free
- variables rather than arguments.
+ :default: off but enabled with :ghc-flag:`-O2`.
+
+ Turn on the liberate-case transformation. This unrolls recursive function
+ once in its own RHS, to avoid repeated case analysis of free variables. It's
+ a bit like the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for
+ free variables rather than arguments.
.. ghc-flag:: -fliberate-case-threshold=<n>
@@ -401,14 +416,20 @@ list.
.. ghc-flag:: -fno-opt-coercion
+ :default: off
+
Turn off the coercion optimiser.
.. ghc-flag:: -fno-pre-inlining
+ :default: off
+
Turn off pre-inlining.
.. ghc-flag:: -fno-state-hack
+ :default: off
+
Turn off the "state hack" whereby any lambda with a ``State#`` token
as argument is considered to be single-entry, hence it is considered
okay to inline things inside it. This can improve performance of IO
@@ -416,6 +437,8 @@ list.
.. ghc-flag:: -fomit-interface-pragmas
+ :default: off
+
Tells GHC to omit all inessential information from the interface
file generated for the module being compiled (say M). This means
that a module importing M will see only the *types* of the functions
@@ -495,9 +518,11 @@ list.
.. ghc-flag:: -fspec-constr
- *Off by default, but enabled by -O2.* Turn on call-pattern
- specialisation; see `Call-pattern specialisation for Haskell
- programs <http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm>`__.
+ :default: off but enabled by :ghc-flag:`-O2`.
+
+ Turn on call-pattern specialisation; see `Call-pattern specialisation for
+ Haskell programs
+ <http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm>`__.
This optimisation specializes recursive functions according to their
argument "shapes". This is best explained by example so consider: ::
@@ -601,7 +626,7 @@ list.
.. ghc-flag:: -fsolve-constant-dicts
- :default on
+ :default: on
When solving constraints, try to eagerly solve
super classes using availible dictionaries.
@@ -632,6 +657,8 @@ list.
.. ghc-flag:: -fstatic-argument-transformation
+ :default: off
+
Turn on the static argument transformation, which turns a recursive
function into a non-recursive one with a local recursive loop. See
Chapter 7 of `Andre Santos's PhD
@@ -695,6 +722,8 @@ list.
.. ghc-flag:: -funbox-strict-fields
+ :default: off
+
.. index::
single: strict constructor fields
single: constructor fields, strict
@@ -711,6 +740,9 @@ list.
it for certain constructor fields using the ``NOUNPACK`` pragma (see
:ref:`nounpack-pragma`).
+ Alternatively you can use :ghc-flag:`-funbox-small-strict-fields` to only
+ unbox strict fields which are "small".
+
.. ghc-flag:: -funfolding-creation-threshold=<n>
:default: 750