[[project @ 2003-06-13 08:45:32 by simonmar] simonmar**20030613084532 - 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. ] { hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3451 - -INLINE pragma + <sect2 id="deprecated-pragma"> + <title>DEPRECATED pragma + DEPRECATED + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3456 -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. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3460 - -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. + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3472 - -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: hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3517 -(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.) - hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3518 - -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.) hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3522 - -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. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3527 - -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: hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3545 - - - -The NOINLINE pragma + See also the NOINLINE pragma (). + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3549 -NOINLINE pragma -pragmaNOINLINE -NOTINLINE pragma -pragmaNOTINLINE + + NOINLINE pragma + + NOINLINE + NOTINLINE hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3555 - -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. - + 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. hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3560 -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). - + 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). + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3567 + + Phase control hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3570 - -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: hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3580 - 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": hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3587 - + + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3590 - 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": hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3596 - + + + + + If you omit the phase indicator, you mean "inline in + all phases". + + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3605 - 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": + 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": hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3615 - + + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3618 - 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": hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3625 - + + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3628 - 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". + + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3634 + The same phase-numbering control is available for RULES + (). + + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3639 + + LINE pragma hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3642 - + 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 + + +{-# LINE 42 "Foo.vhs" #-} + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3653 - -RULES pragma + 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. + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3660 - -The RULES pragma lets you specify rewrite rules. It is described in -. - + + OPTIONS pragma + OPTIONS + + pragmaOPTIONS + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3667 - + 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 hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3676 + The RULES pragma lets you specify rewrite rules. It is + described in . + hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3770 - -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. - hunk ./ghc/docs/users_guide/glasgow_exts.sgml 3771 - - - -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 . - - }