--------------------------------
[haskell-report.git] / report / pragmas.verb
1 %
2 % $Header: /home/cvs/root/haskell-report/report/pragmas.verb,v 1.4 2002/12/02 14:53:30 simonpj Exp $
3 %
4 %**<title>The Haskell 98 Report: Pragmas</title>
5 %**~header
6 \section{Compiler Pragmas}
7 \label{pragmas}
8 \index{pragmas}
9
10 Some compiler implementations support compiler {\em pragmas}, which are
11 used to give additional instructions or hints to the compiler, but which
12 do not form part of the \Haskell{} language proper and do not change a
13 program's semantics.  This
14 section summarizes this existing practice.  An implementation is not
15 required to respect any pragma, but the pragma should be ignored if an
16 implementation is not prepared to handle it.  
17 Lexically, pragmas appear as comments, except that the enclosing
18 syntax is @{-#@ @#-}@.
19
20 \subsection{Inlining}
21 \index{inlining}
22 @@@
23 decl -> @{-#@ @INLINE@ qvars @#-}@
24 decl -> @{-#@ @NOINLINE@ qvars @#-}@
25 @@@
26 % The optional digit represents the level of optimization at which the
27 % inlining is to occur.  If omitted, it is assumed to be 0.  A compiler
28 % may use a numeric optimization level setting in which increasing level
29 % numbers indicate increasing amounts of optimization.  Trivial
30 % inlinings that have no 
31 % impact on compilation time or code size should have an optimization
32 % level of 0; more complex inlinings that may lead to slow compilation
33 % or large executables should be associated with higher optimization levels.
34
35 The @INLINE@ pragma instructs the compiler to inline the specified variables
36 at their use sites.
37 Compilers will often automatically inline simple expressions.  This
38 may be prevented by the @NOINLINE@ pragma.
39
40 \subsection{Specialization}
41 @@@
42 decl -> @{-#@ @SPECIALIZE@ spec_1 @,@ ... @,@ spec_k @#-}@ & (k>=1)
43 spec -> vars :: type
44 @@@
45 Specialization is used to avoid inefficiencies involved in dispatching
46 overloaded functions.  For example, in
47 \bprog
48 @
49 factorial :: Num a => a -> a
50 factorial 0 = 0
51 factorial n = n * factorial (n-1)
52 {-# SPECIALIZE factorial :: Int -> Int,
53                factorial :: Integer -> Integer #-}
54 @
55 \eprog
56 calls to @factorial@ in which the compiler can detect that the
57 parameter is either @Int@ or @Integer@ will
58 use specialized versions of @factorial@ which do not involve
59 overloaded numeric operations.
60
61
62 %**~footer