X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=0beed8e3123f66fa056938001cce22e2b566d886;hb=dfcf88523ec5988fbcaa2cbf812cc5862ad621cf;hp=beaaad616a393caf66fc20809d502363266087fb;hpb=0065d5ab628975892cea1ec7303f968c3338cbe1;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index beaaad6..0beed8e 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -128,6 +128,45 @@ documentation describes all the libraries that come with GHC.
+ :
+
+
+
+
+ As an experimental change, we are exploring the possibility of
+ making pattern bindings monomorphic; that is, not generalised at all.
+ A pattern binding is a binding whose LHS has no function arguments,
+ and is not a simple variable. For example:
+
+ f x = x -- Not a pattern binding
+ f = \x -> x -- Not a pattern binding
+ f :: Int -> Int = \x -> x -- Not a pattern binding
+
+ (g,h) = e -- A pattern binding
+ (f) = e -- A pattern binding
+ [x] = e -- A pattern binding
+
+Experimentally, GHC now makes pattern bindings monomorphic by
+default. Use to recover the
+standard behaviour.
+
+
+
+
+
+
+ :
+
+
+
+ Use GHCi's extended default rules in a regular module ().
+ Independent of the
+ flag.
+
+
+
+
+
@@ -140,7 +179,7 @@ documentation describes all the libraries that come with GHC.
-
+
@@ -244,7 +283,8 @@ documentation describes all the libraries that come with GHC.
Enables Template Haskell (see ). Currently also implied by
+ linkend="template-haskell"/>). This flag must
+ be given explicitly; it is no longer implied by
.Syntax stolen: [|,
@@ -616,7 +656,7 @@ clunky env var1 var1 = case lookup env var1 of
Nothing -> fail
Just val2 -> val1 + val2
where
- fail = val1 + val2
+ fail = var1 + var2
@@ -1009,8 +1049,8 @@ in a type synonym, thus:
f :: Discard a
f x y = (x, show y)
- g :: Discard Int -> (Int,Bool) -- A rank-2 type
- g f = f Int True
+ g :: Discard Int -> (Int,String) -- A rank-2 type
+ g f = f 3 True
@@ -2089,7 +2129,7 @@ option, you can use arbitrary
types in both an instance context and instance head. Termination is ensured by having a
fixed-depth recursion stack. If you exceed the stack depth you get a
sort of backtrace, and the opportunity to increase the stack depth
-with N.
+with N.
@@ -2106,7 +2146,9 @@ can be modified by two flags:
and
-fallow-incoherent-instances
-, as this section discusses.
+, as this section discusses. Both these
+flags are dynamic flags, and can be set on a per-module basis, using
+an OPTIONS_GHC pragma if desired ().
When GHC tries to resolve, say, the constraint C Int Bool,
it tries to match every instance declaration against the
@@ -3742,20 +3784,17 @@ Derived instance declarations are constructed as follows. Consider the
declaration (after expansion of any type synonyms)
- newtype T v1...vn = T' (S t1...tk vk+1...vn) deriving (c1...cm)
+ newtype T v1...vn = T' (t vk+1...vn) deriving (c1...cm)
where
- S is a type constructor,
-
-
- The t1...tk are types,
+ The type t is an arbitrary type
- The vk+1...vn are type variables which do not occur in any of
- the ti, and
+ The vk+1...vn are type variables which do not occur in
+ t, and
The ci are partial applications of
@@ -3773,7 +3812,7 @@ where
Then, for each ci, the derived instance
declaration is:
- instance ci (S t1...tk vk+1...v) => ci (T v1...vp)
+ instance ci (t vk+1...v) => ci (T v1...vp)
where p is chosen so that T v1...vp is of the
right kind for the last parameter of class Ci.
@@ -4089,9 +4128,8 @@ Tim Sheard is going to expand it.)
constructions. You need to use the flag
to switch these syntactic extensions on
- ( is currently implied by
- , but you are encouraged to
- specify it explicitly).
+ ( is no longer implied by
+ ).
@@ -4239,7 +4277,46 @@ Hello
+
+
+Using Template Haskell with Profiling
+profilingwith Template Haskell
+Template Haskell relies on GHC's built-in bytecode compiler and
+interpreter to run the splice expressions. The bytecode interpreter
+runs the compiled expression on top of the same runtime on which GHC
+itself is running; this means that the compiled code referred to by
+the interpreted expression must be compatible with this runtime, and
+in particular this means that object code that is compiled for
+profiling cannot be loaded and used by a splice
+expression, because profiled object code is only compatible with the
+profiling version of the runtime.
+
+This causes difficulties if you have a multi-module program
+containing Template Haskell code and you need to compile it for
+profiling, because GHC cannot load the profiled object code and use it
+when executing the splices. Fortunately GHC provides a workaround.
+The basic idea is to compile the program twice:
+
+
+
+ Compile the program or library first the normal way, without
+ .
+
+
+ Then compile it again with , and
+ additionally use
+ to name the object files differentliy (you can choose any suffix
+ that isn't the normal object suffix here). GHC will automatically
+ load the object files built in the first step when executing splice
+ expressions. If you omit the flag when
+ building with and Template Haskell is used,
+ GHC will emit an error message.
+
+
+
+
@@ -5013,63 +5090,58 @@ key_function :: Int -> String -> (Bool, Double)
If you use you'll see the
sequence of phase numbers for successive runs of the
simplifier. In an INLINE pragma you can optionally specify a
- phase number, thus:
-
+ phase number, thus:
- You can say "inline f in Phase 2
- and all subsequent phases":
-
- {-# INLINE [2] f #-}
-
-
-
-
+ "INLINE[k] f" means: do not inline
+ f
+ until phase k, but from phase
+ k onwards be very keen to inline it.
+
- You can say "inline g in all
- phases up to, but not including, Phase 3":
-
- {-# INLINE [~3] g #-}
-
-
-
-
+ "INLINE[~k] f" means: be very keen to inline
+ f
+ until phase k, but from phase
+ k onwards do not inline it.
+
- If you omit the phase indicator, you mean "inline in
- all phases".
-
+ "NOINLINE[k] f" means: do not inline
+ f
+ until phase k, but from phase
+ k onwards be willing to inline it (as if
+ there was no pragma).
+
+
+ "INLINE[~k] f" means: be willing to inline
+ f
+ until phase k, but from phase
+ k onwards do not inline it.
+
-
- You can use a phase number on a NOINLINE pragma too:
-
-
-
- You can say "do not inline f
- until Phase 2; in Phase 2 and subsequently behave as if
- there was no pragma at all":
+The same information is summarised here:
- {-# NOINLINE [2] f #-}
-
-
-
+ -- Before phase 2 Phase 2 and later
+ {-# INLINE [2] f #-} -- No Yes
+ {-# INLINE [~2] f #-} -- Yes No
+ {-# NOINLINE [2] f #-} -- No Maybe
+ {-# NOINLINE [~2] f #-} -- Maybe No
-
- You can say "do not inline g in
- Phase 3 or any subsequent phase; before that, behave as if
- there was no pragma":
-
- {-# NOINLINE [~3] g #-}
+ {-# INLINE f #-} -- Yes Yes
+ {-# NOINLINE f #-} -- No No
-
-
-
-
- If you omit the phase indicator, you mean "never
- inline this function".
-
-
-
- The same phase-numbering control is available for RULES
+By "Maybe" we mean that the usual heuristic inlining rules apply (if the
+function body is small, or it is applied to interesting-looking arguments etc).
+Another way to understand the semantics is this:
+
+For both INLINE and NOINLINE, the phase number says
+when inlining is allowed at all.
+The INLINE pragma has the additional effect of making the
+function body look small, so that when inlining is allowed it is very likely to
+happen.
+
+
+
+The same phase-numbering control is available for RULES
().
@@ -5347,7 +5419,9 @@ The programmer can specify rewrite rules as part of the source program
(in a pragma). GHC applies these rewrite rules wherever it can, provided (a)
the flag () is on,
and (b) the flag
-() is not specified.
+() is not specified, and (c) the
+ ()
+flag is active.
@@ -5669,7 +5743,7 @@ The following are good producers:
- filter
+take, filter
@@ -5732,7 +5806,7 @@ The following are good consumers:
- filter
+take, filter
@@ -5997,6 +6071,89 @@ r) ->
+
+Special built-in functions
+GHC has a few built-in funcions with special behaviour,
+described in this section. All are exported by
+GHC.Exts.
+
+The inline function
+
+The inline function is somewhat experimental.
+
+ inline :: a -> a
+
+The call (inline f) arranges that f
+is inlined, regardless of its size. More precisely, the call
+(inline f) rewrites to the right-hand side of f's
+definition.
+This allows the programmer to control inlining from
+a particular call site
+rather than the definition site of the function
+(c.f. INLINE pragmas ).
+
+
+This inlining occurs regardless of the argument to the call
+or the size of f's definition; it is unconditional.
+The main caveat is that f's definition must be
+visible to the compiler. That is, f must be
+let-bound in the current scope.
+If no inlining takes place, the inline function
+expands to the identity function in Phase zero; so its use imposes
+no overhead.
+
+ If the function is defined in another
+module, GHC only exposes its inlining in the interface file if the
+function is sufficiently small that it might be
+inlined by the automatic mechanism. There is currently no way to tell
+GHC to expose arbitrarily-large functions in the interface file. (This
+shortcoming is something that could be fixed, with some kind of pragma.)
+
+
+
+The lazy function
+
+The lazy function restrains strictness analysis a little:
+
+ lazy :: a -> a
+
+The call (lazy e) means the same as e,
+but lazy has a magical property so far as strictness
+analysis is concerned: it is lazy in its first argument,
+even though its semantics is strict. After strictness analysis has run,
+calls to lazy are inlined to be the identity function.
+
+
+This behaviour is occasionally useful when controlling evaluation order.
+Notably, lazy is used in the library definition of
+Control.Parallel.par:
+
+ par :: a -> b -> b
+ par x y = case (par# x) of { _ -> lazy y }
+
+If lazy were not lazy, par would
+look strict in y which would defeat the whole
+purpose of par.
+
+
+
+The unsafeCoerce# function
+
+The function unsafeCoerce# allows you to side-step the
+typechecker entirely. It has type
+
+ unsafeCoerce# :: a -> b
+
+That is, it allows you to coerce any type into any other type. If you use this
+function, you had better get it right, otherwise segmentation faults await.
+It is generally used when you want to write a program that you know is
+well-typed, but where Haskell's type system is not expressive enough to prove
+that it is well typed.
+
+
+
+
+
Generic classes