Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in / Register
Toggle navigation
Menu
Open sidebar
Glasgow Haskell Compiler
GHC
Commits
9ea0721d
Commit
9ea0721d
authored
Mar 23, 2012
by
dterei
Browse files
Improve documentation on optimisations.
parent
f5584e69
Changes
1
Hide whitespace changes
Inline
Side-by-side
docs/users_guide/using.xml
View file @
9ea0721d
...
...
@@ -31,7 +31,8 @@ main = putStrLn "Hello, World!"
<para>
To compile the program, use GHC like this:
</para>
<screen>
$ ghc hello.hs
</screen>
$ ghc hello.hs
</screen>
<para>
(where
<literal>
$
</literal>
represents the prompt: don't
type it). GHC will compile the source
...
...
@@ -58,7 +59,8 @@ $ ghc hello.hs</screen>
<screen>
$ ./hello
Hello World!
</screen>
Hello World!
</screen>
<para>
If your program contains multiple modules, then you only need to
...
...
@@ -725,7 +727,8 @@ olleh
<para>
Thus, a common invocation would be:
</para>
<screen>
ghc -c Foo.hs
</screen>
ghc -c Foo.hs
</screen>
<para>
to compile the Haskell source file
<filename>
Foo.hs
</filename>
to an object file
...
...
@@ -874,19 +877,25 @@ ghc -c Foo.hs</screen>
<para>
For example:
</para>
<screen>
test.hs:3:6: parse error on input `where'
</screen>
<screen>
test.hs:3:6: parse error on input `where'
</screen>
<para>
becomes:
</para>
<screen>
test296.hs:3:6-10: parse error on input `where'
</screen>
<screen>
test296.hs:3:6-10: parse error on input `where'
</screen>
<para>
And multi-line spans are possible too:
</para>
<screen>
test.hs:(5,4)-(6,7):
<screen>
test.hs:(5,4)-(6,7):
Conflicting definitions for `a'
Bound at: test.hs:5:4
test.hs:6:7
In the binding group for: a, b, a
</screen>
In the binding group for: a, b, a
</screen>
<para>
Note that line numbers start counting at one, but
column numbers start at zero. This choice was made to
...
...
@@ -1100,13 +1109,17 @@ ghc -c Foo.hs</screen>
</indexterm>
<para>
Causes a warning to be emitted for foreign imports of
the following form:
</para>
<programlisting>
foreign import "f" f :: FunPtr t
</programlisting>
<para>
on the grounds that it probably should be
</para>
<programlisting>
foreign import "
&
f" f :: FunPtr t
</programlisting>
<para>
The first form declares that `f` is a (pure) C
function that takes no arguments and returns a pointer to a
C function with type `t`, whereas the second form declares
...
...
@@ -1246,9 +1259,11 @@ foreign import "&f" f :: FunPtr t
non-empty lists, so the compiler will emit a warning about
this when
<option>
-fwarn-incomplete-patterns
</option>
is
enabled.
<programlisting>
g [] = 2
</programlisting>
This option isn't enabled by default because it can be
a bit noisy, and it doesn't always indicate a bug in the
program. However, it's generally considered good practice
...
...
@@ -1259,10 +1274,12 @@ g [] = 2
similar, except that it
applies only to lambda-expressions and pattern bindings, constructs
that only allow a single pattern:
<programlisting>
h = \[] -> 2
Just k = f y
</programlisting>
</para>
</listitem>
</varlistentry>
...
...
@@ -1325,6 +1342,7 @@ f foo = foo { x = 6 }
that does not explicitly list the entities brought into scope. For
example
</para>
<programlisting>
module M where
import X( f )
...
...
@@ -1332,6 +1350,7 @@ module M where
import qualified Z
p x = f x x
</programlisting>
<para>
The
<option>
-fwarn-import-lists
</option>
flag will warn about the import
of
<literal>
Y
</literal>
but not
<literal>
X
</literal>
...
...
@@ -1756,9 +1775,11 @@ f "2" = 2
<variablelist>
<varlistentry>
<term>
<option>
-fexcess-precision
</option>
:
</term>
<listitem
>
<term>
<option>
-fexcess-precision
</option
>
<indexterm><primary><option>
-fexcess-precision
</option></primary></indexterm>
</term>
<listitem>
<para>
When this option is given, intermediate floating
point values can have a
<emphasis>
greater
</emphasis>
precision/range than the final type. Generally this is a
...
...
@@ -1770,9 +1791,11 @@ f "2" = 2
</varlistentry>
<varlistentry>
<term>
<option>
-fignore-asserts
</option>
:
</term>
<listitem
>
<term>
<option>
-fignore-asserts
</option
>
<indexterm><primary><option>
-fignore-asserts
</option></primary></indexterm>
</term>
<listitem>
<para>
Causes GHC to ignore uses of the function
<literal>
Exception.assert
</literal>
in source code (in
other words, rewriting
<literal>
Exception.assert p
...
...
@@ -1802,6 +1825,7 @@ f "2" = 2
</term>
<listitem>
<para>
Turn on the liberate-case transformation.
</para>
TODO: Document optimisation
</listitem>
</varlistentry>
...
...
@@ -1812,7 +1836,7 @@ f "2" = 2
</term>
<listitem>
<para>
Turns off the common-sub-expression elimination optimisation.
Can be useful if you have some
<literal>
unsafePerformIO
</literal>
Can be useful if you have some
<literal>
unsafePerformIO
</literal>
expressions that you don't want commoned-up.
</para>
</listitem>
</varlistentry>
...
...
@@ -1835,9 +1859,11 @@ f "2" = 2
</term>
<listitem>
<para>
Turns off the full laziness optimisation (also known as
let-floating).
Full laziness increases sharing, which can lead
let-floating). Full laziness increases sharing, which can lead
to increased memory residency.
</para>
TODO: Document optimisation
<para>
NOTE: GHC doesn't implement complete full-laziness.
When optimisation in on, and
<option>
-fno-full-laziness
</option>
is not given, some
...
...
@@ -1857,6 +1883,7 @@ f "2" = 2
</term>
<listitem>
<para>
Turns off the float-in transformation.
</para>
TODO: Document optimisation
</listitem>
</varlistentry>
...
...
@@ -1867,6 +1894,7 @@ f "2" = 2
</term>
<listitem>
<para>
Turns off the automatic specialisation of overloaded functions.
</para>
TODO: Document optimisation
</listitem>
</varlistentry>
...
...
@@ -1877,9 +1905,9 @@ f "2" = 2
</term>
<listitem>
<para>
Turn off the "state hack" whereby any lambda with a
<literal>
State#
</literal>
token as argument is considered to be
single-entry, hence it is considered OK to inline things inside
it.
This can improve performance of IO and ST monad code, but it
<literal>
State#
</literal>
token as argument is considered to be
single-entry, hence it is considered OK to inline things inside
it. This can improve performance of IO and ST monad code, but it
runs the risk of reducing sharing.
</para>
</listitem>
</varlistentry>
...
...
@@ -1891,10 +1919,10 @@ f "2" = 2
</term>
<listitem>
<para>
Make GHC be more precise about its treatment of bottom (but see also
<option>
-fno-state-hack
</option>
). In particular, stop GHC
eta-expanding through a case expression, which is good for
performance, but bad if you are using
<literal>
seq
</literal>
on
partial applications.
</para>
<option>
-fno-state-hack
</option>
). In particular, stop GHC
eta-expanding through a case expression, which is good for
performance, but bad if you are using
<literal>
seq
</literal>
on
partial applications.
</para>
</listitem>
</varlistentry>
...
...
@@ -1904,15 +1932,15 @@ f "2" = 2
<indexterm><primary><option>
-fomit-interface-pragmas
</option></primary></indexterm>
</term>
<listitem>
<para>
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
<emphasis>
types
</emphasis>
of the functions that M exports, but not
their unfoldings, strictness info, etc. Hence, for example,
no function exported by M will be inlined
into an importing module. The benefit is that modules that import M will
need to be recompiled less often (only when M's exports change their type,
not when they change their implementation).
</para>
<para>
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
<emphasis>
types
</emphasis>
of the functions that M exports, but
not their unfoldings, strictness info, etc. Hence, for example,
no function exported by M will be inlined into an importing module.
The benefit is that modules that import M will need to be
recompiled less often (only when M's exports change their type, not
when they change their implementation).
</para>
</listitem>
</varlistentry>
...
...
@@ -1923,18 +1951,19 @@ f "2" = 2
</term>
<listitem>
<para>
GHC's optimiser can diverge if you write rewrite rules (
<xref
linkend=
"rewrite-rules"
/>
)
that don't terminate, or (less satisfactorily) if you
code up recursion through data types
(
<xref
linkend=
"bugs-ghc"
/>
). To avoid making the compiler fall into an infinite
loop, the optimiser carries a "tick count" and stops inlining and applying rewrite rules
when this count is exceeded. The limit is set as a multiple of the program size, so
bigger programs get more ticks. The
<option>
-fsimpl-tick-factor
</option>
flag lets
you change the multiplier. The default is 100; numbers larger than 100 give more ticks,
and numbers smaller than 100 give fewer.
</para>
that don't terminate, or (less satisfactorily) if you
code up recursion through data types
(
<xref
linkend=
"bugs-ghc"
/>
). To avoid making the compiler fall into an infinite
loop, the optimiser carries a "tick count" and stops inlining and applying rewrite rules
when this count is exceeded. The limit is set as a multiple of the program size, so
bigger programs get more ticks. The
<option>
-fsimpl-tick-factor
</option>
flag lets
you change the multiplier. The default is 100; numbers larger than 100 give more ticks,
and numbers smaller than 100 give fewer.
</para>
<para>
If the tick-count expires, GHC summarises what simplifier steps it has done;
you can use
<option>
-fddump-simpl-stats
</option>
to generate a much more detailed list.
Usually that identifies the loop quite accurately, because some numbers are very large.
</para>
</para>
</listitem>
</varlistentry>
...
...
@@ -1945,6 +1974,7 @@ f "2" = 2
</term>
<listitem>
<para>
Turn on the static argument transformation.
</para>
TODO: Document optimisation
</listitem>
</varlistentry>
...
...
@@ -1955,6 +1985,7 @@ f "2" = 2
</term>
<listitem>
<para>
Turn on call-pattern specialisation.
</para>
TODO: Document optimisation
</listitem>
</varlistentry>
...
...
@@ -1966,22 +1997,19 @@ f "2" = 2
<indexterm><primary>
constructor fields, strict
</primary></indexterm>
</term>
<listitem>
<para>
This option causes all constructor fields which are
marked strict (i.e.
“
!
”
) to be unboxed or
unpacked if possible. It is equivalent to adding an
<literal>
UNPACK
</literal>
pragma to every strict
constructor field (see
<xref
linkend=
"unpack-pragma"
/>
).
</para>
<para>
This option is a bit of a sledgehammer: it might
sometimes make things worse. Selectively unboxing fields
by using
<literal>
UNPACK
</literal>
pragmas might be
better. An alternative is to use
<option>
-funbox-strict-fields
</option>
to turn on
unboxing by default but disable it for certain constructor
fields using the
<literal>
NOUNPACK
</literal>
pragma
(see
<xref
linkend=
"nounpack-pragma"
/>
).
</para>
<para>
This option causes all constructor fields which are marked
strict (i.e.
“
!
”
) to be unpacked if possible. It is
equivalent to adding an
<literal>
UNPACK
</literal>
pragma to every
strict constructor field (see
<xref
linkend=
"unpack-pragma"
/>
).
</para>
<para>
This option is a bit of a sledgehammer: it might sometimes
make things worse. Selectively unboxing fields by using
<literal>
UNPACK
</literal>
pragmas might be better. An alternative
is to use
<option>
-funbox-strict-fields
</option>
to turn on
unboxing by default but disable it for certain constructor
fields using the
<literal>
NOUNPACK
</literal>
pragma (see
<xref
linkend=
"nounpack-pragma"
/>
).
</para>
</listitem>
</varlistentry>
...
...
@@ -1993,40 +2021,49 @@ f "2" = 2
<indexterm><primary>
unfolding, controlling
</primary></indexterm>
</term>
<listitem>
<para>
(Default: 45) Governs the maximum size that GHC will
allow a function unfolding to be. (An unfolding has a
“
size
”
that reflects the cost in terms of
“
code bloat
”
of expanding that unfolding
at a call site. A bigger function would be assigned a
bigger cost.)
</para>
<para>
Consequences: (a) nothing larger than this will be
<para>
(Default: 45) Governs the maximum size that GHC will allow a
function unfolding to be. (An unfolding has a
“
size
”
that reflects the cost in terms of
“
code bloat
”
of
expanding (aka inlining) that unfolding at a call site. A bigger
function would be assigned a bigger cost.)
</para>
<para>
Consequences: (a) nothing larger than this will be
inlined (unless it has an INLINE pragma); (b) nothing
larger than this will be spewed into an interface
file.
</para>
<para>
Increasing this figure is more likely to result in longer
compile times than faster code. The next
option is more
useful:
</para>
<para>
Increasing this figure is more likely to result in longer
compile times than faster code. The
<option>
-funfolding-use-threshold
</
option
>
is more
useful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>
-funfolding-use-threshold=
<replaceable>
n
</replaceable></option></term>
<listitem
>
<term>
<option>
-funfolding-use-threshold=
<replaceable>
n
</replaceable></option
>
<indexterm><primary><option>
-funfolding-use-threshold
</option></primary></indexterm>
<indexterm><primary>
inlining, controlling
</primary></indexterm>
<indexterm><primary>
unfolding, controlling
</primary></indexterm>
<para>
(Default: 8) This is the magic cut-off figure for
unfolding: below this size, a function definition will be
unfolded at the call-site, any bigger and it won't. The
size computed for a function depends on two things: the
actual size of the expression minus any discounts that
</term>
<listitem>
<para>
(Default: 8) This is the magic cut-off figure for unfolding
(aka inlining): below this size, a function definition will be
unfolded at the call-site, any bigger and it won't. The size
computed for a function depends on two things: the actual size of
the expression minus any discounts that
apply (see
<option>
-funfolding-con-discount
</option>
).
</para>
<para>
The difference between this and
<option>
-funfolding-creation-threshold
</option>
is that this one
determines if a function definition will be inlined at a call
site. The other option determines if a function definition will
be kept around to begin with for potential inlining.
</para>
TODO: Is above para correct?
</listitem>
</varlistentry>
</variablelist>
</sect2>
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment