%************************************************************************
%*                                                                      *
<sect>Advice on: sooner, faster, smaller, stingier
<label id="sooner-faster-quicker">
<p>
%*                                                                      *
%************************************************************************

Please advise us of other ``helpful hints'' that should go here!

%************************************************************************
%*                                                                      *
<sect1>Sooner: producing a program more quickly
<label id="sooner">
<p>
<nidx>compiling faster</nidx>
<nidx>faster compiling</nidx>
%*                                                                      *
%************************************************************************

<descrip>
%----------------------------------------------------------------
<tag>Don't use @-O@ or (especially) @-O2@:</tag>
By using them, you are telling GHC that you are willing to suffer
longer compilation times for better-quality code.

GHC is surprisingly zippy for normal compilations without @-O@!

%----------------------------------------------------------------
<tag>Use more memory:</tag>
Within reason, more memory for heap space means less garbage
collection for GHC, which means less compilation time.  If you use
the @-Rgc-stats@ option, you'll get a garbage-collector report.
(Again, you can use the cheap-and-nasty @-optCrts-Sstderr@ option to
send the GC stats straight to standard error.)

If it says you're using more than 20\% of total time in garbage
collecting, then more memory would help.

If the heap size is approaching the maximum (64M by default), and you
have lots of memory, try increasing the maximum with the
@-M<size>@<nidx>-M&lt;size&gt; option</nidx> option, e.g.: @ghc -c -O
-M16m Foo.hs@.

Increasing the default allocation area size used by the compiler's RTS
might also help: use the @-A<size>@<nidx>-A&lt;size&gt; option</nidx>
option.

If GHC persists in being a bad memory citizen, please report it as a
bug.

%----------------------------------------------------------------
<tag>Don't use too much memory!</tag>
As soon as GHC plus its ``fellow citizens'' (other processes on your
machine) start using more than the <em>real memory</em> on your
machine, and the machine starts ``thrashing,'' <em>the party is
over</em>.  Compile times will be worse than terrible!  Use something
like the csh-builtin @time@ command to get a report on how many page
faults you're getting.

If you don't know what virtual memory, thrashing, and page faults are,
or you don't know the memory configuration of your machine,
<em>don't</em> try to be clever about memory use: you'll just make
your life a misery (and for other people, too, probably).

%----------------------------------------------------------------
<tag>Try to use local disks when linking:</tag>
Because Haskell objects and libraries tend to be large, it can take
many real seconds to slurp the bits to/from a remote filesystem.

It would be quite sensible to <em>compile</em> on a fast machine using
remotely-mounted disks; then <em>link</em> on a slow machine that had
your disks directly mounted.

%----------------------------------------------------------------
<tag>Don't derive/use @Read@ unnecessarily:</tag>
It's ugly and slow.

%----------------------------------------------------------------
<tag>GHC compiles some program constructs slowly:</tag>
Deeply-nested list comprehensions seem to be one such; in the past,
very large constant tables were bad, too.

We'd rather you reported such behaviour as a bug, so that we can try
to correct it.

The parts of the compiler that seem most prone to wandering off for a
long time are the abstract interpreters (strictness and update
analysers).  You can turn these off individually with
@-fno-strictness@<nidx>-fno-strictness anti-option</nidx> and
@-fno-update-analysis@.<nidx>-fno-update-analysis anti-option</nidx>

To figure out which part of the compiler is badly behaved, the
@-dshow-passes@<nidx>-dshow-passes option</nidx> option is your
friend.

If your module has big wads of constant data, GHC may produce a huge
basic block that will cause the native-code generator's register
allocator to founder.  Bring on @-fvia-C@<nidx>-fvia-C option</nidx>
(not that GCC will be that quick about it, either).

%----------------------------------------------------------------
<tag>Avoid the consistency-check on linking:</tag>

Use @-no-link-chk@<nidx>-no-link-chk</nidx>; saves effort.  This is
probably safe in a I-only-compile-things-one-way setup.

%----------------------------------------------------------------
<tag>Explicit @import@ declarations:</tag>

Instead of saying @import Foo@, say @import Foo (...stuff I want...)@.

Truthfully, the reduction on compilation time will be very small.
However, judicious use of @import@ declarations can make a
program easier to understand, so it may be a good idea anyway.
</descrip>

%************************************************************************
%*                                                                      *
<sect1>Faster: producing a program that runs quicker
<label id="faster">
<p>
<nidx>faster programs, how to produce</nidx>
%*                                                                      *
%************************************************************************

The key tool to use in making your Haskell program run faster are
GHC's profiling facilities, described separately in Section <ref
name="Profiling" id="profiling">.  There is <em>no substitute</em> for
finding where your program's time/space is <em>really</em> going, as
opposed to where you imagine it is going.

Another point to bear in mind: By far the best way to improve a
program's performance <em>dramatically</em> is to use better
algorithms.  Once profiling has thrown the spotlight on the guilty
time-consumer(s), it may be better to re-think your program than to
try all the tweaks listed below.

Another extremely efficient way to make your program snappy is to use
library code that has been Seriously Tuned By Someone Else.  You
<em>might</em> be able to write a better quicksort than the one in the
HBC library, but it will take you much longer than typing @import
QSort@.  (Incidentally, it doesn't hurt if the Someone Else is Lennart
Augustsson.)

Please report any overly-slow GHC-compiled programs.  The current
definition of ``overly-slow'' is ``the HBC-compiled version ran
faster''...

<descrip>
%----------------------------------------------------------------
<tag>Optimise, using @-O@ or @-O2@:</tag> This is the most basic way
to make your program go faster.  Compilation time will be slower,
especially with @-O2@.

At present, @-O2@ is nearly indistinguishable from @-O@.

%----------------------------------------------------------------
<tag>Compile via C and crank up GCC:</tag> Even with @-O@, GHC tries to
use a native-code generator, if available.  But the native
code-generator is designed to be quick, not mind-bogglingly clever.
Better to let GCC have a go, as it tries much harder on register
allocation, etc.

So, when we want very fast code, we use: @-O -fvia-C -O2-for-C@.

%----------------------------------------------------------------
<tag>Overloaded functions are not your friend:</tag>
Haskell's overloading (using type classes) is elegant, neat, etc.,
etc., but it is death to performance if left to linger in an inner
loop.  How can you squash it?

<descrip>
<tag>Give explicit type signatures:</tag>
Signatures are the basic trick; putting them on exported, top-level
functions is good software-engineering practice, anyway.  (Tip: using
@-fwarn-missing-signatures@<nidx>-fwarn-missing-signatures
option</nidx> can help enforce good signature-practice).

The automatic specialisation of overloaded functions (with @-O@)
should take care of overloaded local and/or unexported functions.

<tag>Use @SPECIALIZE@ pragmas:</tag>
<nidx>SPECIALIZE pragma</nidx>
<nidx>overloading, death to</nidx>
(UK spelling also accepted.)  For key overloaded functions, you can
create extra versions (NB: more code space) specialised to particular
types.  Thus, if you have an overloaded function:

<tscreen><verb>
hammeredLookup :: Ord key => [(key, value)] -> key -> value
</verb></tscreen>

If it is heavily used on lists with @Widget@ keys, you could
specialise it as follows:
<tscreen><verb>
{-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}
</verb></tscreen>

To get very fancy, you can also specify a named function to use for
the specialised value, by adding @= blah@, as in:
<tscreen><verb>
{-# SPECIALIZE hammeredLookup :: ...as before... = blah #-}
</verb></tscreen>
It's <em>Your Responsibility</em> to make sure that @blah@ really
behaves as a specialised version of @hammeredLookup@!!!

[NOTE: this feature isn't implemented in GHC 4.00... ]

An example in which the @= blah@ form will Win Big:
<tscreen><verb>
toDouble :: Real a => a -> Double
toDouble = fromRational . toRational

{-# SPECIALIZE toDouble :: Int -> Double = i2d #-}
i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly
</verb></tscreen>
The @i2d@ function is virtually one machine instruction; the
default conversion---via an intermediate @Rational@---is obscenely
expensive by comparison.

By using the US spelling, your @SPECIALIZE@ pragma will work with
HBC, too.  Note that HBC doesn't support the @= blah@ form.

A @SPECIALIZE@ pragma for a function can be put anywhere its type
signature could be put.

<tag>Use @SPECIALIZE instance@ pragmas:</tag>
Same idea, except for instance declarations.  For example:
<tscreen><verb>
instance (Eq a) => Eq (Foo a) where { ... usual stuff ... }

{-# SPECIALIZE instance Eq (Foo [(Int, Bar)] #-}
</verb></tscreen>
Compatible with HBC, by the way.

% See also: overlapping instances, in Section <ref name="``HBC-ish''
% extensions implemented by GHC" id="glasgow-hbc-exts">.  They are to
% @SPECIALIZE instance@ pragmas what @= blah@ hacks are to @SPECIALIZE@
% (value) pragmas...

%ToDo: there's nothing like this at the moment: --SDM

% <tag>``How do I know what's happening with specialisations?'':</tag>

% The @-fshow-specialisations@<nidx>-fshow-specialisations option</nidx>
% will show the specialisations that actually take place.

% The @-fshow-import-specs@<nidx>-fshow-import-specs option</nidx> will
% show the specialisations that GHC <em>wished</em> were available, but
% were not.  You can add the relevant pragmas to your code if you wish.

% You're a bit stuck if the desired specialisation is of a Prelude
% function.  If it's Really Important, you can just snap a copy of the
% Prelude code, rename it, and then SPECIALIZE that to your heart's
% content.

<tag>``But how do I know where overloading is creeping in?'':</tag>

A low-tech way: grep (search) your interface files for overloaded
type signatures; e.g.,:
<tscreen><verb>
% egrep '^[a-z].*::.*=>' *.hi
</verb></tscreen>
</descrip>

%----------------------------------------------------------------
<tag>Strict functions are your dear friends:</tag>
and, among other things, lazy pattern-matching is your enemy.

(If you don't know what a ``strict function'' is, please consult a
functional-programming textbook.  A sentence or two of
explanation here probably would not do much good.)

Consider these two code fragments:
<tscreen><verb>
f (Wibble x y) =  ... # strict

f arg = let { (Wibble x y) = arg } in ... # lazy
</verb></tscreen>
The former will result in far better code.

A less contrived example shows the use of @cases@ instead
of @lets@ to get stricter code (a good thing):
<tscreen><verb>
f (Wibble x y)  # beautiful but slow
  = let
        (a1, b1, c1) = unpackFoo x
        (a2, b2, c2) = unpackFoo y
    in ...

f (Wibble x y)  # ugly, and proud of it
  = case (unpackFoo x) of { (a1, b1, c1) ->
    case (unpackFoo y) of { (a2, b2, c2) ->
    ...
    }}
</verb></tscreen>

%----------------------------------------------------------------
<tag>GHC loves single-constructor data-types:</tag>

It's all the better if a function is strict in a single-constructor
type (a type with only one data-constructor; for example, tuples are
single-constructor types).

%----------------------------------------------------------------
<tag>Newtypes are better than datatypes:</tag>

If your datatype has a single constructor with a single field, use a
@newtype@ declaration instead of a @data@ declaration.  The @newtype@
will be optimised away in most cases.

%----------------------------------------------------------------
<tag>``How do I find out a function's strictness?''</tag>

Don't guess---look it up.

Look for your function in the interface file, then for the third field
in the pragma; it should say @_S_ <string>@.  The @<string>@
gives the strictness of the function's arguments.  @L@ is lazy
(bad), @S@ and @E@ are strict (good), @P@ is ``primitive'' (good),
@U(...)@ is strict and
``unpackable'' (very good), and @A@ is absent (very good).

For an ``unpackable'' @U(...)@ argument, the info inside
tells the strictness of its components.  So, if the argument is a
pair, and it says @U(AU(LSS))@, that means ``the first component of the
pair isn't used; the second component is itself unpackable, with three
components (lazy in the first, strict in the second \& third).''

If the function isn't exported, just compile with the extra flag @-ddump-simpl@;
next to the signature for any binder, it will print the self-same
pragmatic information as would be put in an interface file.
(Besides, Core syntax is fun to look at!)

%----------------------------------------------------------------
<tag>Force key functions to be @INLINE@d (esp. monads):</tag>

GHC (with @-O@, as always) tries to inline (or ``unfold'')
functions/values that are ``small enough,'' thus avoiding the call
overhead and possibly exposing other more-wonderful optimisations.

You will probably see these unfoldings (in Core syntax) in your
interface files.

Normally, if GHC decides a function is ``too expensive'' to inline, it
will not do so, nor will it export that unfolding for other modules to
use.

The sledgehammer you can bring to bear is the
@INLINE@<nidx>INLINE pragma</nidx> pragma, used thusly:
<tscreen><verb>
key_function :: Int -> String -> (Bool, Double) 

#ifdef __GLASGOW_HASKELL__
{-# INLINE key_function #-}
#endif
</verb></tscreen>
(You don't need to do the C pre-processor carry-on unless you're going
to stick the code through HBC---it doesn't like @INLINE@ pragmas.)

The major effect of an @INLINE@ pragma is to declare a function's
``cost'' to be very low.  The normal unfolding machinery will then be
very keen to inline it.

An @INLINE@ pragma for a function can be put anywhere its type
signature could be put.

@INLINE@ pragmas are a particularly good idea for the
@then@/@return@ (or @bind@/@unit@) functions in a monad.
For example, in GHC's own @UniqueSupply@ monad code, we have:
<tscreen><verb>
#ifdef __GLASGOW_HASKELL__
{-# INLINE thenUs #-}
{-# INLINE returnUs #-}
#endif
</verb></tscreen>

Incedentally, there's also a @NOINLINE@<nidx>NOINLINE pragma</nidx>
pragma which does the obvious thing.

%----------------------------------------------------------------
<tag>Explicit @export@ list:</tag>
If you do not have an explicit export list in a module, GHC must
assume that everything in that module will be exported.  This has
various pessimising effects.  For example, if a bit of code is actually
<em>unused</em> (perhaps because of unfolding effects), GHC will not be
able to throw it away, because it is exported and some other module
may be relying on its existence.

GHC can be quite a bit more aggressive with pieces of code if it knows
they are not exported.

%----------------------------------------------------------------
<tag>Look at the Core syntax!</tag>
(The form in which GHC manipulates your code.)  Just run your
compilation with @-ddump-simpl@ (don't forget the @-O@).

If profiling has pointed the finger at particular functions, look at
their Core code.  @lets@ are bad, @cases@ are good, dictionaries
(@d.<Class>.<Unique>@) [or anything overloading-ish] are bad,
nested lambdas are bad, explicit data constructors are good, primitive
operations (e.g., @eqInt#@) are good, ...

%----------------------------------------------------------------
<tag>Use unboxed types (a GHC extension):</tag>
When you are <em>really</em> desperate for speed, and you want to get
right down to the ``raw bits.''  Please see Section <ref name="Unboxed
types" id="glasgow-unboxed"> for some information about using unboxed
types.

%----------------------------------------------------------------
<tag>Use @_ccall_s@ (a GHC extension) to plug into fast libraries:</tag>
This may take real work, but... There exist piles of
massively-tuned library code, and the best thing is not
to compete with it, but link with it.

Section <ref name="Calling~C directly from Haskell" id="glasgow-ccalls"> says a little about how to use C calls.

%----------------------------------------------------------------
<tag>Don't use @Float@s:</tag>
We don't provide specialisations of Prelude functions for @Float@
(but we do for @Double@).  If you end up executing overloaded
code, you will lose on performance, perhaps badly.

@Floats@ (probably 32-bits) are almost always a bad idea, anyway,
unless you Really Know What You Are Doing.  Use Doubles.  There's
rarely a speed disadvantage---modern machines will use the same
floating-point unit for both.  With @Doubles@, you are much less
likely to hang yourself with numerical errors.

One time when @Float@ might be a good idea is if you have a
<em>lot</em> of them, say a giant array of @Float@s.  They take up
half the space in the heap compared to @Doubles@.  However, this isn't
true on a 64-bit machine.

%----------------------------------------------------------------
<tag>Use a bigger heap!</tag>

If your program's GC stats (@-S@<nidx>-S RTS option</nidx> RTS option)
indicate that it's doing lots of garbage-collection (say, more than
20\% of execution time), more memory might help---with the
@-M<size>@<nidx>-M&lt;size&gt; RTS option</nidx> or
@-A<size>@<nidx>-A&lt;size&gt; RTS option</nidx> RTS options (see
Section <ref name="RTS options to control the garbage-collector"
id="rts-options-gc">).
</descrip>

%************************************************************************
%*                                                                      *
<sect1>Smaller: producing a program that is smaller
<label id="smaller">
<p>
<nidx>smaller programs, how to produce</nidx>
%*                                                                      *
%************************************************************************

Decrease the ``go-for-it'' threshold for unfolding smallish
expressions.  Give a
@-funfolding-use-threshold0@<nidx>-funfolding-use-threshold0
option</nidx> option for the extreme case. (``Only unfoldings with
zero cost should proceed.'')  Warning: except in certain specialiised
cases (like Happy parsers) this is likely to actually
<em>increase</em> the size of your program, because unfolding
generally enables extra simplifying optimisations to be performed.

Avoid @Read@.

Use @strip@ on your executables.

%************************************************************************
%*                                                                      *
<sect1>Stingier: producing a program that gobbles less heap space
<label id="stingier">
<p>
<nidx>memory, using less heap</nidx>
<nidx>space-leaks, avoiding</nidx>
<nidx>heap space, using less</nidx>
%*                                                                      *
%************************************************************************

``I think I have a space leak...''  Re-run your program with
@+RTS -Sstderr@,<nidx>-Sstderr RTS option</nidx> and remove all doubt!
(You'll see the heap usage get bigger and bigger...)  [Hmmm... this
might be even easier with the @-F2s@<nidx>-F2s RTS option</nidx> RTS
option; so...  @./a.out +RTS -Sstderr -F2s@...]

Once again, the profiling facilities (Section <ref name="Profiling"
id="profiling">) are the basic tool for demystifying the space
behaviour of your program.

Strict functions are good for space usage, as they are for time, as
discussed in the previous section.  Strict functions get right down to
business, rather than filling up the heap with closures (the system's
notes to itself about how to evaluate something, should it eventually
be required).