X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=d3eba61502dd33e787f9342f427ba343855bb62b;hp=cacf97d7c2868ae975772c5e6f609a6327c38aea;hb=2d874edca55c4f1761a111dc068d17b319cf707e;hpb=bfd7960566a3033182087a411016a04bd74f5eed diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index cacf97d..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 @@ -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 @@ -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.