From 5d86a0c4dae6b6c04f03316ffe8a4c10ada38662 Mon Sep 17 00:00:00 2001 From: simonmar Date: Fri, 13 Jun 2003 08:45:32 +0000 Subject: [PATCH] [project @ 2003-06-13 08:45:32 by simonmar] - add the OPTIONS pragma to the section on pragmas, with a cross-ref to the place it is described. - tidy up the section on pragams: re-indent and sort the sections alphabetically. --- ghc/docs/users_guide/glasgow_exts.sgml | 344 +++++++++++++++++--------------- 1 file changed, 182 insertions(+), 162 deletions(-) diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index ed79f5b..b43f6d4 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -3448,24 +3448,64 @@ Assertion failures can be caught, see the documentation for the unrecognised word is (silently) ignored. - -INLINE pragma + <sect2 id="deprecated-pragma"> + <title>DEPRECATED pragma + DEPRECATED + -INLINE and NOINLINE pragmas -pragma, INLINE + The DEPRECATED pragma lets you specify that a particular + function, class, or type, is deprecated. There are two + forms. - -GHC (with , 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. - + + + 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. + - -The sledgehammer you can bring to bear is the -INLINEINLINE pragma pragma, used thusly: + + 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 + . + + + + INLINE and NOINLINE pragmas + + These pragmas control the inlining of function + definitions. + + + INLINE pragma + INLINE + + GHC (with , 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 + INLINEINLINE + pragma pragma, used thusly: key_function :: Int -> String -> (Bool, Double) @@ -3474,25 +3514,26 @@ key_function :: Int -> String -> (Bool, Double) {-# 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. - + (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.) - -Syntactially, an INLINE pragma for a function can be put anywhere its type -signature could be put. - + 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. - -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: + Syntactially, 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__ @@ -3501,95 +3542,140 @@ For example, in GHC's own UniqueSupply monad code, we have: #endif - - - -The NOINLINE pragma + See also the NOINLINE pragma (). + + + + NOINLINE pragma + + NOINLINE + NOTINLINE + + 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). + + + + Phase control + + 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 you'll see the + sequence of phase numbers for successive runs of the + simpifier. In an INLINE pragma you can optionally specify a + phase number, thus: -NOINLINE pragma -pragmaNOINLINE -NOTINLINE pragma -pragmaNOTINLINE - - -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). - - - - -Phase control - - 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 -you'll see the sequence of phase numbers for successive runs of the simpifier. -In an INLINE pragma you can optionally specify a phase number, thus: - - You can say "inline f in Phase 2 and all subsequent -phases": + + + You can say "inline f in Phase 2 + and all subsequent phases": {-# INLINE [2] f #-} - + + - You can say "inline g in all phases up to, but -not including, Phase 3": + + You can say "inline g in all + phases up to, but not including, Phase 3": {-# INLINE [~3] g #-} - + + - If you omit the phase indicator, you mean "inline in all phases". - - -You can use a phase number on a NOINLINE pragma too: - - You can say "do not inline f until Phase 2; in -Phase 2 and subsequently behave as if there was no pragma at all": + + If you omit the phase indicator, you mean "inline in + all phases". + + + + You can use a phase number on a NOINLINE pragma too: + + + + You can say "do not inline f + until Phase 2; in Phase 2 and subsequently behave as if + there was no pragma at all": {-# NOINLINE [2] f #-} - + + - You can say "do not inline g in Phase 3 or any subsequent phase; -before that, behave as if there was no pragma": + + You can say "do not inline g in + Phase 3 or any subsequent phase; before that, behave as if + there was no pragma": {-# NOINLINE [~3] g #-} - + + - If you omit the phase indicator, you mean "never inline this function". - - - -The same phase-numbering control is available for RULES (). - + + If you omit the phase indicator, you mean "never + inline this function". + + + The same phase-numbering control is available for RULES + (). + + + + LINE pragma - + LINEpragma + pragmaLINE + 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 - -RULES pragma + +{-# LINE 42 "Foo.vhs" #-} + - -The RULES pragma lets you specify rewrite rules. It is described in -. - + 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. + - + + OPTIONS pragma + OPTIONS + + pragmaOPTIONS + + + The OPTIONS pragma is used to specify + additional options that are given to the compiler when compiling + this source file. See for + details. + + + + RULES pragma + The RULES pragma lets you specify rewrite rules. It is + described in . + SPECIALIZE pragma @@ -3681,73 +3767,7 @@ of the pragma. - -LINE pragma - - - -LINE pragma -pragma, LINE - - - -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. - - - - - -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 . - - -- 1.7.10.4