Pragmas

The Glasgow Haskell Compiler User's Guide, Version 5.04
Prev | Chapter 7. GHC Language Features | Next

# 7.6. Pragmas

GHC supports several pragmas, or instructions to the compiler placed in the source code. Pragmas don't normally affect the meaning of the program, but they might affect the efficiency of the generated code.

Pragmas all take the form `{-# `word` ... #-}` where `word` indicates the type of pragma, and is followed optionally by information specific to that type of pragma. Case is ignored in `word`. The various values for `word` that GHC understands are described in the following sections; any pragma encountered with an unrecognised `word` is (silently) ignored.

## 7.6.1. INLINE pragma

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

    key_function :: Int -> String -> (Bool, Double)

    #ifdef __GLASGOW_HASKELL__
    {-# INLINE key_function #-}
    #endif

(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:

    #ifdef __GLASGOW_HASKELL__
    {-# INLINE thenUs #-}
    {-# INLINE returnUs #-}
    #endif

## 7.6.2. NOINLINE pragma

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` (`NOTINLINE` 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).

## 7.6.3. SPECIALIZE pragma

(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:

    hammeredLookup :: Ord key => [(key, value)] -> key -> value

If it is heavily used on lists with `Widget` keys, you could specialise it as follows:

    {-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}

To get very fancy, you can also specify a named function to use for the specialised value, as in:

    {-# RULES hammeredLookup = blah #-}

where `blah` is an implementation of `hammerdLookup` written specialy for `Widget` lookups. It's Your Responsibility to make sure that `blah` really behaves as a specialised version of `hammeredLookup`!!!

Note we use the `RULE` pragma here to indicate that `hammeredLookup` applied at a certain type should be replaced by `blah`. See Section 7.6.6 for more information on `RULES`.

An example in which using `RULES` for specialisation will Win Big:

    toDouble :: Real a => a -> Double
    toDouble = fromRational . toRational

    {-# SPECIALIZE toDouble :: Int -> Double = i2d #-}
    i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly

The `i2d` function is virtually one machine instruction; the default conversion—via an intermediate `Rational`—is obscenely expensive by comparison.

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

## 7.6.4. SPECIALIZE instance pragma

Same idea, except for instance declarations. For example:

    instance (Eq a) => Eq (Foo a) where {
       {-# SPECIALIZE instance Eq (Foo [(Int, Bar)]) #-}
       ... usual stuff ...
     }

The pragma must occur inside the `where` part of the instance declaration.

Compatible with HBC, by the way, except perhaps in the placement of the pragma.

## 7.6.5. LINE pragma

This pragma is similar to C's `#line` pragma, and is mainly for use in automatically generated Haskell code. It lets you specify the line number and filename of the original code; for example

    {-# LINE 42 "Foo.vhs" #-}

if you'd generated the current file from something called `Foo.vhs` and this line corresponds to line 42 in the original. GHC will adjust its error messages to refer to the line/file named in the `LINE` pragma.

## 7.6.6. RULES pragma

The RULES pragma lets you specify rewrite rules. It is described in Section 7.7.

## 7.6.7. DEPRECATED pragma

The DEPRECATED pragma lets you specify that a particular function, class, or type, is deprecated. There are two forms.

- You can deprecate an entire module thus:

         module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
           ...

  When you compile any module that import `Wibble`, GHC will print the specified message.

- You can deprecate a function, class, or type, with the following top-level declaration:

         {-# DEPRECATED f, C, T "Don't use these" #-}

  When you compile any module that imports and uses any of the specifed entities, GHC will print the specified message.

You can suppress the warnings with the flag `-fno-warn-deprecations`.

Prev | Home | Next
Syntactic extensions | Up | Rewrite rules