%
% $Header: /home/cvs/root/haskell-report/report/pragmas.verb,v 1.6 2002/12/10 11:51:11 simonpj Exp $
%
%**<title>The Haskell 98 Report: Compiler Pragmas</title>
%**~header
\section{Compiler Pragmas}
\label{pragmas}
\index{pragmas}

Some compiler implementations support compiler {\em pragmas}, which are
used to give additional instructions or hints to the compiler, but which
do not form part of the \Haskell{} language proper and do not change a
program's semantics.  This
chapter summarizes this existing practice.  An implementation is not
required to respect any pragma, but the pragma should be ignored if an
implementation is not prepared to handle it.  
Lexically, pragmas appear as comments, except that the enclosing
syntax is @{-#@ @#-}@.

\subsection{Inlining}
\index{inlining}
@@@
decl -> @{-#@ @INLINE@ qvars @#-}@
decl -> @{-#@ @NOINLINE@ qvars @#-}@
@@@
% The optional digit represents the level of optimization at which the
% inlining is to occur.  If omitted, it is assumed to be 0.  A compiler
% may use a numeric optimization level setting in which increasing level
% numbers indicate increasing amounts of optimization.  Trivial
% inlinings that have no 
% impact on compilation time or code size should have an optimization
% level of 0; more complex inlinings that may lead to slow compilation
% or large executables should be associated with higher optimization levels.

The @INLINE@ pragma instructs the compiler to inline the specified variables
at their use sites.
Compilers will often automatically inline simple expressions.  This
may be prevented by the @NOINLINE@ pragma.

\subsection{Specialization}
@@@
decl -> @{-#@ @SPECIALIZE@ spec_1 @,@ ... @,@ spec_k @#-}@ & (k>=1)
spec -> vars :: type
@@@
Specialization is used to avoid inefficiencies involved in dispatching
overloaded functions.  For example, in
\bprog
@
factorial :: Num a => a -> a
factorial 0 = 0
factorial n = n * factorial (n-1)
{-# SPECIALIZE factorial :: Int -> Int,
               factorial :: Integer -> Integer #-}
@
\eprog
calls to @factorial@ in which the compiler can detect that the
parameter is either @Int@ or @Integer@ will
use specialized versions of @factorial@ which do not involve
overloaded numeric operations.


%**~footer
