X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=a29e7478c81cd9554eb0358c9831e27cee769146;hb=d91240674cd45cb4677adca5829a1851ba3cd044;hp=161371b8c3ed65b5e109d83212444a9578ea77ff;hpb=92b30c6bd5123897b154aa158a0cd05b8b76f67a;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 161371b..a29e747 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -3,8 +3,9 @@
language, GHCextensions, GHC
As with all known Haskell systems, GHC implements some extensions to
-the language. They are all enabled by options; by default GHC
-understands only plain Haskell 98.
+the language. They can all be enabled or disabled by commandline flags
+or language pragmas. By default GHC understands the most recent Haskell
+version it supports, plus a handful of extensions.
@@ -39,8 +40,7 @@ documentation describes all the libraries that come with GHC.
The language option flags control what variation of the language are
- permitted. Leaving out all of them gives you standard Haskell
- 98.
+ permitted.Language options can be controlled in two ways:
@@ -439,10 +439,10 @@ Indeed, the bindings can even be recursive.
'x'# has type Char#"foo"# has type Addr#3# has type Int#. In general,
- any Haskell 98 integer lexeme followed by a # is an Int# literal, e.g.
+ any Haskell integer lexeme followed by a # is an Int# literal, e.g.
-0x3A# as well as 32#.3## has type Word#. In general,
- any non-negative Haskell 98 integer lexeme followed by ##
+ any non-negative Haskell integer lexeme followed by ##
is a Word#. 3.2# has type Float#.3.2## has type Double#
@@ -460,11 +460,11 @@ Indeed, the bindings can even be recursive.
option. In the new syntax, the prefix form of a qualified
operator is
written module.(symbol)
- (in Haskell 98 this would
+ (without NewQualifiedOperators this would
be (module.symbol)),
and the infix form is
written `module.(symbol)`
- (in Haskell 98 this would
+ (without NewQualifiedOperators this would
be `module.symbol`.
For example:
@@ -476,13 +476,13 @@ Indeed, the bindings can even be recursive.
like Prelude... For example,
when NewQualifiedOperators is on, it is possible to
write the enumerated sequence [Monday..]
- without spaces, whereas in Haskell 98 this would be a
+ without spaces, whereas without NewQualifiedOperators this would be a
reference to the operator ‘.‘
from module Monday.
- When is on, the old Haskell
- 98 syntax for qualified operators is not accepted, so this
- option may cause existing Haskell 98 code to break.
+ When is on, the old
+ syntax for qualified operators is not accepted, so this
+ option may cause existing code to break.
@@ -7712,27 +7712,48 @@ itself, so an INLINE pragma is always ignored.
INLINABLE pragma
-An INLINABLE pragma works very like an INLINE pragma, except that:
+An {-# INLINABLE f #-} pragma on a
+function f has the following behaviour:
-INLINE says "please inline me", but INLINABLE says "feel free to inline me; use your
+While INLINE says "please inline me", the INLINABLE
+says "feel free to inline me; use your
discretion". In other words the choice is left to GHC, which uses the same
-rules as for pragma-free functions. Unlike INLINE, That decision is made at
+rules as for pragma-free functions. Unlike INLINE, that decision is made at
the call site, and
will therefore be affected by the inlining threshold, optimisation level etc.
-Like INLINE, the INLINABLE pragma retains a copy of the original RHS for
+Like INLINE, the INLINABLE pragma retains a
+copy of the original RHS for
inlining purposes, and persists it in the interface file, regardless of
the size of the RHS.
+
-If you use the special function inline ()
-to force inlining at a
-call site, you will get a copy of the the original RHS.
-Indeed, if you intend to use inline f it
-is a good idea to mark the definition of f INLINABLE,
+One way to use INLINABLE is in conjunction with
+the special function inline ().
+The call inline f tries very hard to inline f.
+To make sure that f can be inlined,
+it is a good idea to mark the definition
+of f as INLINABLE,
so that GHC guarantees to expose an unfolding regardless of how big it is.
+Moreover, by annotating f as INLINABLE,
+you ensure that f's original RHS is inlined, rather than
+whatever random optimised version of f GHC's optimiser
+has produced.
+
+
+
+The INLINABLE pragma also works with SPECIALISE:
+if you mark function f as INLINABLE, then
+you can subsequently SPECIALISE in another module
+(see ).
+
+
+Unlike INLINE, it is OK to use
+an INLINABLE pragma on a recursive function.
+The principal reason do to so to allow later use of SPECIALISE
@@ -7995,6 +8016,9 @@ RULE with a somewhat-complex left-hand side (try it yourself), so it might not f
well. If you use this kind of specialisation, let us know how well it works.
+
+ SPECIALIZE INLINE
+
A SPECIALIZE pragma can optionally be followed with a
INLINE or NOINLINE pragma, optionally
followed by a phase, as described in .
@@ -8023,6 +8047,66 @@ specialisation, whose body is also inlined. The result is a type-based
unrolling of the indexing function.Warning: you can make GHC diverge by using SPECIALISE INLINE
on an ordinarily-recursive function.
+
+
+SPECIALIZE for imported functions
+
+
+Generally, you can only give a SPECIALIZE pragma
+for a function defined in the same module.
+However if a function f is given an INLINABLE
+pragma at its definition site, then it can subequently be specialised by
+importing modules (see ).
+For example
+
+module Map( lookup, blah blah ) where
+ lookup :: Ord key => [(key,a)] -> key -> Maybe a
+ lookup = ...
+ {-# INLINABLE lookup #-}
+
+module Client where
+ import Map( lookup )
+
+ data T = T1 | T2 deriving( Eq, Ord )
+ {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a
+
+Here, lookup is declared INLINABLE, but
+it cannot be specialised for type T at its definition site,
+because that type does not exist yet. Instead a client module can define T
+and then specialise lookup at that type.
+
+
+Moreover, every module that imports Client (or imports a module
+that imports Client, transitively) will "see", and make use of,
+the specialised version of lookup. You don't need to put
+a SPECIALIZE pragma in every module.
+
+
+Moreover you often don't even need the SPECIALIZE pragma in the
+first place. When compiling a module M,
+GHC's optimiser (with -O) automatically considers each top-level
+overloaded function declared in M, and specialises it
+for the different types at which it is called in M. The optimiser
+also considers each imported
+INLINABLE overloaded function, and specialises it
+for the different types at which it is called in M.
+So in our example, it would be enough for lookup to
+be called at type T:
+
+module Client where
+ import Map( lookup )
+
+ data T = T1 | T2 deriving( Eq, Ord )
+
+ findT1 :: [(T,a)] -> Maybe a
+ findT1 m = lookup m T1 -- A call of lookup at type T
+
+However, sometimes there are no such calls, in which case the
+pragma can be useful.
+
+
+
+Obselete SPECIALIZE syntaxNote: In earlier versions of GHC, it was possible to provide your own
specialised function for a given type:
@@ -8033,6 +8117,7 @@ on an ordinarily-recursive function.
This feature has been removed, as it is now subsumed by the
RULES pragma (see ).
+
@@ -8157,7 +8242,7 @@ Here is an example:
Use the debug flag to see what rules fired.
If you need more information, then shows you
-each individual rule firing in detail.
+each individual rule firing and also shows what the code looks like before and after the rewrite.
@@ -8742,7 +8827,8 @@ If you add you get a more detailed listing.
- Use to see in great detail what rules are being fired.
+ Use or
+to see in great detail what rules are being fired.
If you add you get a still more detailed listing.