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. 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 pragma, used thusly:

key_function :: Int -> String -> (Bool, Double)
{-# INLINE key_function #-}

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. However, an INLINE pragma for a function "f" has a number of other effects:

GHC ensures that inlining cannot go on forever: every mutually-recursive group is cut by one or more loop breakers that is never inlined (see Secrets of the GHC inliner, JFP 12(4) July 2002). GHC tries not to select a function with an INLINE pragma as a loop breaker, but when there is no choice even an INLINE function can be selected, in which case the INLINE pragma is ignored. For example, for a self-recursive function, the loop breaker can only be the function itself, so an INLINE pragma is always ignored.

Syntactically, 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:

{-# INLINE thenUs #-}
{-# INLINE returnUs #-}

See also the NOINLINE (Section 7.16.5.3, “NOINLINE pragma”) and INLINABLE (Section 7.16.5.2, “INLINABLE pragma”) pragmas.

Note: the HBC compiler doesn't like INLINE pragmas, so if you want your code to be HBC-compatible you'll have to surround the pragma with C pre-processor directives #ifdef __GLASGOW_HASKELL__...#endif.

An {-# INLINABLE f #-} pragma on a function f has the following behaviour:

The NOINLINE pragma does exactly what you'd expect: it stops the named function from being inlined by the compiler. You shouldn't ever need to do this, unless you're very cautious about code size.

NOTINLINE is a synonym for NOINLINE (NOINLINE is specified by Haskell 98 as the standard way to disable inlining, so it should be used if you want your code to be portable).

An INLINE or NOINLINE pragma may have a CONLIKE modifier, which affects matching in RULEs (only). See Section 7.17.3, “How rules interact with INLINE/NOINLINE and CONLIKE pragmas”.

Sometimes you want to control exactly when in GHC's pipeline the INLINE pragma is switched on. Inlining happens only during runs of the simplifier. Each run of the simplifier has a different phase number; the phase number decreases towards zero. If you use -dverbose-core2core you'll see the sequence of phase numbers for successive runs of the simplifier. In an INLINE pragma you can optionally specify a phase number, thus:

The same information is summarised here:

                           -- Before phase 2     Phase 2 and later
  {-# INLINE   [2]  f #-}  --      No                 Yes
  {-# INLINE   [~2] f #-}  --      Yes                No
  {-# NOINLINE [2]  f #-}  --      No                 Maybe
  {-# NOINLINE [~2] f #-}  --      Maybe              No

  {-# INLINE   f #-}       --      Yes                Yes
  {-# NOINLINE f #-}       --      No                 No

By "Maybe" we mean that the usual heuristic inlining rules apply (if the function body is small, or it is applied to interesting-looking arguments etc). Another way to understand the semantics is this:

The same phase-numbering control is available for RULES (Section 7.17, “Rewrite rules ”).

A SPECIALIZE pragma can optionally be followed with a INLINE or NOINLINE pragma, optionally followed by a phase, as described in Section 7.16.5, “INLINE and NOINLINE pragmas”. The INLINE pragma affects the specialised version of the function (only), and applies even if the function is recursive. The motivating example is this:

-- A GADT for arrays with type-indexed representation
data Arr e where
  ArrInt :: !Int -> ByteArray# -> Arr Int
  ArrPair :: !Int -> Arr e1 -> Arr e2 -> Arr (e1, e2)

(!:) :: Arr e -> Int -> e
{-# SPECIALISE INLINE (!:) :: Arr Int -> Int -> Int #-}
{-# SPECIALISE INLINE (!:) :: Arr (a, b) -> Int -> (a, b) #-}
(ArrInt _ ba)     !: (I# i) = I# (indexIntArray# ba i)
(ArrPair _ a1 a2) !: i      = (a1 !: i, a2 !: i)

Here, (!:) is a recursive function that indexes arrays of type Arr e. Consider a call to (!:) at type (Int,Int). The second specialisation will fire, and the specialised function will be inlined. It has two calls to (!:), both at type Int. Both these calls fire the first specialisation, whose body is also inlined. The result is a type-based unrolling of the indexing function.

You can add explicit phase control (Section 7.16.5.5, “Phase control”) to SPECIALISE INLINE pragma, just like on an INLINE pragma; if you do so, the same phase is used for the rewrite rule and the INLINE control of the specialised function.

Warning: you can make GHC diverge by using SPECIALISE INLINE on an ordinarily-recursive function.

Generally, you can only give a SPECIALIZE pragma for a function defined in the same module. However if a function f is given an INLINABLE pragma at its definition site, then it can subsequently be specialised by importing modules (see Section 7.16.5.2, “INLINABLE pragma”). For example

module Map( lookup, blah blah ) where
  lookup :: Ord key => [(key,a)] -> key -> Maybe a
  lookup = ...
  {-# INLINABLE lookup #-}

module Client where
  import Map( lookup )

  data T = T1 | T2 deriving( Eq, Ord )
  {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a

Here, lookup is declared INLINABLE, but it cannot be specialised for type T at its definition site, because that type does not exist yet. Instead a client module can define T and then specialise lookup at that type.

Moreover, every module that imports Client (or imports a module that imports Client, transitively) will "see", and make use of, the specialised version of lookup. You don't need to put a SPECIALIZE pragma in every module.

Moreover you often don't even need the SPECIALIZE pragma in the first place. When compiling a module M, GHC's optimiser (with -O) automatically considers each top-level overloaded function declared in M, and specialises it for the different types at which it is called in M. The optimiser also considers each imported INLINABLE overloaded function, and specialises it for the different types at which it is called in M. So in our example, it would be enough for lookup to be called at type T:

module Client where
  import Map( lookup )

  data T = T1 | T2 deriving( Eq, Ord )

  findT1 :: [(T,a)] -> Maybe a
  findT1 m = lookup m T1   -- A call of lookup at type T

However, sometimes there are no such calls, in which case the pragma can be useful.

Note: In earlier versions of GHC, it was possible to provide your own specialised function for a given type:

{-# SPECIALIZE hammeredLookup :: [(Int, value)] -> Int -> value = intLookup #-}

This feature has been removed, as it is now subsumed by the RULES pragma (see Section 7.17.5, “Specialisation ”).