X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=3e8df7b4697faf12df8710276e3472d70df91ee5;hp=b7d43c9f3fd80a77247c11acec0527835e47182b;hb=42b8aa9e4a054ae6784e6c90c9adc615a9703b8c;hpb=661c97c65e5fa47177502e592bb763f752b487ac
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index b7d43c9..3e8df7b 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -56,38 +56,7 @@ documentation describes all the libraries that come with GHC.
The flag
is equivalent to enabling the following extensions:
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- ,
- .
+ &what_glasgow_exts_does;
Enabling these options is the only
effect of .
We are trying to move away from this portmanteau flag,
@@ -818,10 +787,8 @@ let {(x -> y) = e1 ;
(y -> x) = e2 } in x
-(We may lift this
-restriction in the future; the only cost is that type checking patterns
-would get a little more complicated.)
-
+(For some amplification on this design choice see
+Trac #4061.)
@@ -1896,6 +1863,26 @@ not * then an explicit kind annotation must be used
Nevertheless, they can be useful when defining "phantom types".
+
+Data type contexts
+
+Haskell allows datatypes to be given contexts, e.g.
+
+
+data Eq a => Set a = NilSet | ConsSet a (Set a)
+
+
+give constructors with types:
+
+
+NilSet :: Set a
+ConsSet :: Eq a => a -> Set a -> Set a
+
+
+In GHC this feature is an extension called
+DatatypeContexts, and on by default.
+
+
Infix type constructors, classes, and type variables
@@ -7477,7 +7464,7 @@ Assertion failures can be caught, see the documentation for the
A list of all supported language extensions can be obtained by invoking
- ghc --supported-languages (see ).
+ ghc --supported-extensions (see ).
Any extension from the Extension type defined in
String -> (Bool, Double)
function "f" has a number of other effects:
-No functions are inlined into f. Otherwise
-GHC might inline a big function into f's right hand side,
-making f big; and then inline f blindly.
+While GHC is keen to inline the function, it does not do so
+blindly. For example, if you write
+
+map key_function xs
+
+there really isn't any point in inlining key_function to get
+
+map (\x -> body) xs
+
+In general, GHC only inlines the function if there is some reason (no matter
+how slight) to supose that it is useful to do so.
+
-The float-in, float-out, and common-sub-expression transformations are not
-applied to the body of f.
+Moreover, GHC will only inline the function if it is fully applied,
+where "fully applied"
+means applied to as many arguments as appear (syntactically)
+on the LHS of the function
+definition. For example:
+
+comp1 :: (b -> c) -> (a -> b) -> a -> c
+{-# INLINE comp1 #-}
+comp1 f g = \x -> f (g x)
+
+comp2 :: (b -> c) -> (a -> b) -> a -> c
+{-# INLINE comp2 #-}
+comp2 f g x = f (g x)
+
+The two functions comp1 and comp2 have the
+same semantics, but comp1 will be inlined when applied
+to two arguments, while comp2 requires
+three. This might make a big difference if you say
+
+map (not `comp1` not) xs
+
+which will optimise better than the corresponding use of `comp2`.
+
+
+
+It is useful for GHC to optimise the definition of an
+INLINE function f just like any other non-INLINE function,
+in case the non-inlined version of f is
+ultimately called. But we don't want to inline
+the optimised version
+of f;
+a major reason for INLINE pragmas is to expose functions
+in f's RHS that have
+rewrite rules, and it's no good if those functions have been optimised
+away.
+
+
+So GHC guarantees to inline precisely the code that you wrote, no more
+and no less. It does this by capturing a copy of the definition of the function to use
+for inlining (we call this the "inline-RHS"), which it leaves untouched,
+while optimising the ordinarly RHS as usual. For externally-visible functions
+the inline-RHS (not the optimised RHS) is recorded in the interface file.
An INLINE function is not worker/wrappered by strictness analysis.
It's going to be inlined wholesale instead.
-All of these effects are aimed at ensuring that what gets inlined is
-exactly what you asked for, no more and no less.
GHC ensures that inlining cannot go on forever: every mutually-recursive
group is cut by one or more loop breakers that is never inlined
@@ -7649,8 +7683,9 @@ itself, so an INLINE pragma is always ignored.
{-# INLINE returnUs #-}
- See also the NOINLINE pragma ().
+ See also the NOINLINE ()
+ and INLINABLE ()
+ pragmas.Note: the HBC compiler doesn't like INLINE pragmas,
so if you want your code to be HBC-compatible you'll have to surround
@@ -7659,6 +7694,36 @@ itself, so an INLINE pragma is always ignored.
+
+ INLINABLE pragma
+
+An INLINABLE pragma works very like an INLINE pragma, except that:
+
+
+INLINE says "please inline me", but 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
+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
+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,
+so that GHC guarantees to expose an unfolding regardless of how big it is.
+
+
+
+
+
+
NOINLINE pragma
@@ -8773,7 +8838,23 @@ r) ->
GHC has a few built-in functions with special behaviour. These
are now described in the module GHC.Prim
-in the library documentation.
+in the library documentation.
+In particular:
+
+
+inline
+allows control over inlining on a per-call-site basis.
+
+
+lazy
+restrains the strictness analyser.
+
+
+lazy
+allows you to fool the type checker.
+
+
+
@@ -9079,7 +9160,6 @@ standard behaviour.