X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=d3eba61502dd33e787f9342f427ba343855bb62b;hb=1c1ed8694bdd24b003fa5935d001a1835e9b0f4e;hp=d156de8b48f9d4d16a21ea5ba0bac03e9fd78a17;hpb=ceb5840878cd876f8425293fa3c8d56e9cbf3a2e;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index d156de8..d3eba61 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,
@@ -7625,21 +7594,68 @@ key_function :: Int -> 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
@@ -7667,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
@@ -7677,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
@@ -8055,10 +8102,6 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
directly in the T constructor. The
unpacker can see through newtypes, too.
- If a field cannot be unpacked, you will not get a warning,
- so it might be an idea to check the generated code with
- .
-
See also the flag,
which essentially has the effect of adding
{-# UNPACK #-} to every strict
@@ -8791,7 +8834,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.
+
+
+