X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=d3eba61502dd33e787f9342f427ba343855bb62b;hb=0a435635320c2fb075694b52ddbce5bb792110f5;hp=f794c4d754c66deb2d7a48ae534a44c40dbb3784;hpb=d8453ba7a64dbc41dc8784078895170746b455a9;p=ghc-hetmet.git diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index f794c4d..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, @@ -110,7 +79,7 @@ While you really can use this stuff to write fast code, All these primitive data types and operations are exported by the library GHC.Prim, for which there is -detailed online documentation. +detailed online documentation. (This documentation is generated from the file compiler/prelude/primops.txt.pp.) @@ -400,14 +369,6 @@ Indeed, the bindings can even be recursive. LEFTWARDS ARROW - - - .. - … - 0x22EF - MIDLINE HORIZONTAL ELLIPSIS - - @@ -826,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.) @@ -911,7 +870,7 @@ it, you can use the flag. - + The recursive do-notation @@ -932,7 +891,7 @@ justOnes = do { rec { xs <- Just (1:xs) } As you can guess justOnes will evaluate to Just [-1,-1,-1,.... -The background and motivation for recusrive do-notation is described in +The background and motivation for recursive do-notation is described in A recursive do for Haskell, by Levent Erkok, John Launchbury, Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania. @@ -1047,7 +1006,7 @@ It supports rebindable syntax (see ). - Mdo-notation (deprecated) + Mdo-notation (deprecated) GHC used to support the flag , which enabled the keyword mdo, precisely as described in @@ -1245,7 +1204,7 @@ then group by e This form of grouping is essentially the same as the one described above. However, since no function to use for the grouping has been supplied it will fall back on the groupWith function defined in - GHC.Exts. This + GHC.Exts. This is the form of the group statement that we made use of in the opening example. @@ -1697,7 +1656,7 @@ and the fixity declaration applies wherever the binding is in scope. For example, in a let, it applies in the right-hand sides of other let-bindings and the body of the letC. Or, in recursive do -expressions (), the local fixity +expressions (), the local fixity declarations of a let statement scope over other statements in the group, just as the bound name does. @@ -1904,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 @@ -6697,7 +6676,7 @@ The arrows web page at With the flag, GHC supports the arrow notation described in the second of these papers, translating it using combinators from the -Control.Arrow +Control.Arrow module. What follows is a brief introduction to the notation; it won't make much sense unless you've read Hughes's paper. @@ -6812,7 +6791,7 @@ the arrow f, and matches its output against y. In the next line, the output is discarded. The arrow returnA is defined in the -Control.Arrow +Control.Arrow module as arr id. The above example is treated as an abbreviation for @@ -6829,7 +6808,7 @@ arr (\ x -> (x, x)) >>> Note that variables not used later in the composition are projected out. After simplification using rewrite rules (see ) defined in the -Control.Arrow +Control.Arrow module, this reduces to arr (\ x -> (x+1, x)) >>> @@ -7125,7 +7104,7 @@ additional restrictions: The module must import -Control.Arrow. +Control.Arrow. @@ -7485,11 +7464,11 @@ 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 Language.Haskell.Extension + url="&libraryCabalLocation;/Language-Haskell-Extension.html">Language.Haskell.Extension may be used. GHC will report an error if any of the requested extensions are not supported. @@ -7615,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 @@ -7657,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 @@ -7667,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 @@ -8045,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 @@ -8780,8 +8833,24 @@ r) -> Special built-in functions GHC has a few built-in functions with special behaviour. These are now described in the module GHC.Prim -in the library documentation. +url="&libraryGhcPrimLocation;/GHC-Prim.html">GHC.Prim +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. + + + @@ -9087,7 +9156,6 @@ standard behaviour.