%
-% $Id: glasgow_exts.vsgml,v 1.5 1999/02/22 10:22:35 sof Exp $
+% $Id: glasgow_exts.vsgml,v 1.6 1999/03/16 17:07:21 simonm Exp $
%
% GHC Language Extensions.
%
can dangle around your neck. Please see Section <ref name="Calling~C
directly from Haskell" id="glasgow-ccalls">.
+<tag>Pragmas</tag>
+
+Pragmas are special instructions to the compiler placed in the source
+file. The pragmas GHC supports are described in Section <ref
+name="Pragmas" id="pragmas">.
+
</descrip>
Before you get too carried away working at the lowest level (e.g.,
</verb></tscreen>
</itemize>
+
+%-----------------------------------------------------------------------------
+<sect1>Pragmas
+<label id="pragmas">
+<p>
+
+GHC supports several pragmas, or instructions to the compiler placed
+in the source code. Pragmas don't affect the meaning of the program,
+but they might affect the efficiency of the generated code.
+
+<sect2>INLINE pragma
+<label id="inline-pragma">
+<nidx>INLINE pragma</nidx>
+<nidx>pragma, INLINE</nidx>
+<p>
+
+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@<nidx>INLINE pragma</nidx> pragma, used thusly:
+<tscreen><verb>
+key_function :: Int -> String -> (Bool, Double)
+
+#ifdef __GLASGOW_HASKELL__
+{-# INLINE key_function #-}
+#endif
+</verb></tscreen>
+(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:
+<tscreen><verb>
+#ifdef __GLASGOW_HASKELL__
+{-# INLINE thenUs #-}
+{-# INLINE returnUs #-}
+#endif
+</verb></tscreen>
+
+<sect2>NOINLINE pragma
+<label id="noinline-pragma">
+<p>
+<nidx>NOINLINE pragma</nidx>
+<nidx>pragma, NOINLINE</nidx>
+
+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.
+
+<sect2>SPECIALIZE pragma
+<label id="specialize-pragma">
+<p>
+<nidx>SPECIALIZE pragma</nidx>
+<nidx>pragma, SPECIALIZE</nidx>
+<nidx>overloading, death to</nidx>
+
+(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:
+
+<tscreen><verb>
+hammeredLookup :: Ord key => [(key, value)] -> key -> value
+</verb></tscreen>
+
+If it is heavily used on lists with @Widget@ keys, you could
+specialise it as follows:
+<tscreen><verb>
+{-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}
+</verb></tscreen>
+
+To get very fancy, you can also specify a named function to use for
+the specialised value, by adding @= blah@, as in:
+<tscreen><verb>
+{-# SPECIALIZE hammeredLookup :: ...as before... = blah #-}
+</verb></tscreen>
+It's <em>Your Responsibility</em> to make sure that @blah@ really
+behaves as a specialised version of @hammeredLookup@!!!
+
+NOTE: the @=blah@ feature isn't implemented in GHC 4.xx.
+
+An example in which the @= blah@ form will Win Big:
+<tscreen><verb>
+toDouble :: Real a => a -> Double
+toDouble = fromRational . toRational
+
+{-# SPECIALIZE toDouble :: Int -> Double = i2d #-}
+i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly
+</verb></tscreen>
+The @i2d@ function is virtually one machine instruction; the
+default conversion---via an intermediate @Rational@---is obscenely
+expensive by comparison.
+
+By using the US spelling, your @SPECIALIZE@ pragma will work with
+HBC, too. Note that HBC doesn't support the @= blah@ form.
+
+A @SPECIALIZE@ pragma for a function can be put anywhere its type
+signature could be put.
+
+<sect2>SPECIALIZE instance pragma
+<label id="specialize-instance-pragma">
+<p>
+<nidx>SPECIALIZE pragma</nidx>
+<nidx>overloading, death to</nidx>
+Same idea, except for instance declarations. For example:
+<tscreen><verb>
+instance (Eq a) => Eq (Foo a) where { ... usual stuff ... }
+
+{-# SPECIALIZE instance Eq (Foo [(Int, Bar)] #-}
+</verb></tscreen>
+Compatible with HBC, by the way.
+
+<sect2>LINE pragma
+<label id="line-pragma">
+<p>
+<nidx>LINE pragma</nidx>
+<nidx>pragma, LINE</nidx>
+
+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
+
+<tscreen><verb>
+{-# LINE 42 "Foo.vhs" #-}
+</verb></tscreen>
+
+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.
list of things we'd like to know about your bug. If in doubt, send a
report---we love mail from irate users :-!
-(Section <ref name="Haskell 1.4 vs. Glasgow Haskell 4.00: language
+(Section <ref name="Haskell 98 vs. Glasgow Haskell: language
non-compliance" id="vs-Haskell-defn">, which describes Glasgow
Haskell's shortcomings vs.~the Haskell language definition, may also
be of interest.)
<tag>Use @SPECIALIZE@ pragmas:</tag>
<nidx>SPECIALIZE pragma</nidx>
<nidx>overloading, death to</nidx>
-(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:
-<tscreen><verb>
-hammeredLookup :: Ord key => [(key, value)] -> key -> value
-</verb></tscreen>
-
-If it is heavily used on lists with @Widget@ keys, you could
-specialise it as follows:
-<tscreen><verb>
-{-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}
-</verb></tscreen>
-
-To get very fancy, you can also specify a named function to use for
-the specialised value, by adding @= blah@, as in:
-<tscreen><verb>
-{-# SPECIALIZE hammeredLookup :: ...as before... = blah #-}
-</verb></tscreen>
-It's <em>Your Responsibility</em> to make sure that @blah@ really
-behaves as a specialised version of @hammeredLookup@!!!
-
-[NOTE: this feature isn't implemented in GHC 4.00... ]
-
-An example in which the @= blah@ form will Win Big:
-<tscreen><verb>
-toDouble :: Real a => a -> Double
-toDouble = fromRational . toRational
-
-{-# SPECIALIZE toDouble :: Int -> Double = i2d #-}
-i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly
-</verb></tscreen>
-The @i2d@ function is virtually one machine instruction; the
-default conversion---via an intermediate @Rational@---is obscenely
-expensive by comparison.
-
-By using the US spelling, your @SPECIALIZE@ pragma will work with
-HBC, too. Note that HBC doesn't support the @= blah@ form.
-
-A @SPECIALIZE@ pragma for a function can be put anywhere its type
-signature could be put.
-
-<tag>Use @SPECIALIZE instance@ pragmas:</tag>
-Same idea, except for instance declarations. For example:
-<tscreen><verb>
-instance (Eq a) => Eq (Foo a) where { ... usual stuff ... }
-
-{-# SPECIALIZE instance Eq (Foo [(Int, Bar)] #-}
-</verb></tscreen>
-Compatible with HBC, by the way.
+Specialize the overloading on key functions in your program. See
+Sections <ref name="SPECIALIZE pragmas" id="specialize-pragma"> and
+<ref name="SPECIALIZE instance pragmas" id="specialize-instance-pragma">
% See also: overlapping instances, in Section <ref name="``HBC-ish''
% extensions implemented by GHC" id="glasgow-hbc-exts">. They are to
%----------------------------------------------------------------
<tag>Force key functions to be @INLINE@d (esp. monads):</tag>
-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@<nidx>INLINE pragma</nidx> pragma, used thusly:
-<tscreen><verb>
-key_function :: Int -> String -> (Bool, Double)
-
-#ifdef __GLASGOW_HASKELL__
-{-# INLINE key_function #-}
-#endif
-</verb></tscreen>
-(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:
-<tscreen><verb>
-#ifdef __GLASGOW_HASKELL__
-{-# INLINE thenUs #-}
-{-# INLINE returnUs #-}
-#endif
-</verb></tscreen>
-
-Incedentally, there's also a @NOINLINE@<nidx>NOINLINE pragma</nidx>
-pragma which does the obvious thing.
+Placing @INLINE@ pragmas on certain functions that are used a lot can
+have a dramatic effect. See Section <ref name="INLINE pragmas"
+id="inline-pragma">.
%----------------------------------------------------------------
<tag>Explicit @export@ list:</tag>
%************************************************************************
%* *
-<sect1>Haskell~1.4 vs.~Glasgow Haskell~4.00: language non-compliance
+<sect1>Haskell~98 vs.~Glasgow Haskell: language non-compliance
<label id="vs-Haskell-defn">
<p>
-<nidx>GHC vs the Haskell 1.4 language</nidx>
-<nidx>Haskell 1.4 language vs GHC</nidx>
+<nidx>GHC vs the Haskell 98 language</nidx>
+<nidx>Haskell 98 language vs GHC</nidx>
%* *
%************************************************************************
This section lists Glasgow Haskell infelicities in its implementation
-of Haskell~1.4. See also the ``when things go wrong'' section
+of Haskell~98. See also the ``when things go wrong'' section
(Section <ref name="What to do when something goes wrong" id="wrong">)
for information about crashes, space leaks, and other undesirable
phenomena.
<descrip>
%-------------------------------------------------------------------
-<tag>Derived instances of @Read@ and @Show@ for infix constructors:</tag>
-All the carry-on about derived @readsPrec@ and @showsPrec@ for infix
-constructors---we don't do it (yet). We treat them the same way as
-all other constructors.
-
-%-------------------------------------------------------------------
<tag>Derived instances for records:</tag> Hmmm.
</descrip>
modules beginning with @Prel@ in your program, or you will be
comprehensively screwed.
-% Not true anymore? -- Simon M.
-%-------------------------------------------------------------------
-% <tag>Can't export primitive types (e.g., @Int#@):</tag>
-% Don't even try...
-
</descrip>
%************************************************************************
%************************************************************************
<descrip>
-% Not true anymore? We use Rationals all the way -- Simon M.
-%-------------------------------------------------------------------
-% <tag>Very large/small fractional constants:</tag>
-% (i.e., with a decimal point somewhere) GHC does not check that these
-% are out of range (e.g., for a @Float@), and bad things will inevitably
-% follow. (To be corrected?)
-%
-% This problem does <em>not</em> exist for integral constants.
-%
-% For very large/small fractional constants near the limits of your
-% floating-point precision, things may go wrong. (It's better than it
-% used to be.) Please report any such bugs.
-
%-------------------------------------------------------------------
<tag>Unchecked arithmetic:</tag>
<descrip>
%-------------------------------------------------------------------
<tag>Arbitrary-sized tuples:</tag>
-Plain old tuples of arbitrary size <em>do</em> work. Note that lots of
-overloading can give rise to large tuples ``under the hood'' of your
-program.
+Plain old tuples of arbitrary size <em>do</em> work.
HOWEVER: standard instances for tuples (@Eq@, @Ord@, @Bounded@, @Ix@
@Read@, and @Show@) are available <em>only</em> up to 5-tuples.
%-------------------------------------------------------------------
<tag>Unicode character set:</tag>
-Haskell 1.4 embraces the Unicode character set, but GHC 4.00 doesn't
+Haskell 98 embraces the Unicode character set, but GHC doesn't
handle it. Yet.
</descrip>
projects / ghc-hetmet.git / commitdiff