Commit e1a83341 authored by simonm's avatar simonm
Browse files

[project @ 1999-03-16 17:07:21 by simonm]

- Document the pragmas we support
- Fix some lies in the vs. Haskell section.
parent 456eca73
%
% $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.
%
......@@ -60,6 +60,12 @@ Just what it sounds like. We provide <em>lots</em> of rope that you
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.,
......@@ -1730,3 +1736,149 @@ For example:
</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.
......@@ -13,7 +13,7 @@ name="How to report a bug in the GHC system" id="bug-reports"> for a
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.)
......
......@@ -183,56 +183,10 @@ should take care of overloaded local and/or unexported functions.
<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
......@@ -336,48 +290,9 @@ pragmatic information as would be put in an interface file.
%----------------------------------------------------------------
<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.
......@@ -55,12 +55,6 @@ It might work, but it's just begging for trouble.
%************************************************************************
<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>
......@@ -82,11 +76,6 @@ All of these modules begin with @Prel@, so the rule is: don't use any
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>
%************************************************************************
......@@ -98,19 +87,6 @@ comprehensively screwed.
%************************************************************************
<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>
......@@ -143,9 +119,7 @@ main = print (array (1,1) [ 1:=2, 1:=3 ])
<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.
......@@ -155,7 +129,7 @@ stuck on them.
%-------------------------------------------------------------------
<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>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment