<indexterm><primary>language, GHC</primary></indexterm>
<indexterm><primary>extensions, GHC</primary></indexterm>
As with all known Haskell systems, GHC implements some extensions to
-the language. They are all enabled by options; by default GHC
-understands only plain Haskell 98.
+the language. They can all be enabled or disabled by commandline flags
+or language pragmas. By default GHC understands the most recent Haskell
+version it supports, plus a handful of extensions.
</para>
<para>
</indexterm>
<para>The language option flags control what variation of the language are
- permitted. Leaving out all of them gives you standard Haskell
- 98.</para>
+ permitted.</para>
<para>Language options can be controlled in two ways:
<itemizedlist>
<para>The flag <option>-fglasgow-exts</option>
<indexterm><primary><option>-fglasgow-exts</option></primary></indexterm>
is equivalent to enabling the following extensions:
- <option>-XPrintExplicitForalls</option>,
- <option>-XForeignFunctionInterface</option>,
- <option>-XUnliftedFFITypes</option>,
- <option>-XGADTs</option>,
- <option>-XImplicitParams</option>,
- <option>-XScopedTypeVariables</option>,
- <option>-XUnboxedTuples</option>,
- <option>-XTypeSynonymInstances</option>,
- <option>-XStandaloneDeriving</option>,
- <option>-XDeriveDataTypeable</option>,
- <option>-XFlexibleContexts</option>,
- <option>-XFlexibleInstances</option>,
- <option>-XConstrainedClassMethods</option>,
- <option>-XMultiParamTypeClasses</option>,
- <option>-XFunctionalDependencies</option>,
- <option>-XMagicHash</option>,
- <option>-XPolymorphicComponents</option>,
- <option>-XExistentialQuantification</option>,
- <option>-XUnicodeSyntax</option>,
- <option>-XPostfixOperators</option>,
- <option>-XPatternGuards</option>,
- <option>-XLiberalTypeSynonyms</option>,
- <option>-XExplicitForAll</option>,
- <option>-XRankNTypes</option>,
- <option>-XImpredicativeTypes</option>,
- <option>-XTypeOperators</option>,
- <option>-XDoRec</option>,
- <option>-XParallelListComp</option>,
- <option>-XEmptyDataDecls</option>,
- <option>-XKindSignatures</option>,
- <option>-XGeneralizedNewtypeDeriving</option>,
- <option>-XTypeFamilies</option>.
+ &what_glasgow_exts_does;
Enabling these options is the <emphasis>only</emphasis>
effect of <option>-fglasgow-exts</option>.
We are trying to move away from this portmanteau flag,
<listitem><para> <literal>'x'#</literal> has type <literal>Char#</literal></para> </listitem>
<listitem><para> <literal>"foo"#</literal> has type <literal>Addr#</literal></para> </listitem>
<listitem><para> <literal>3#</literal> has type <literal>Int#</literal>. In general,
- any Haskell 98 integer lexeme followed by a <literal>#</literal> is an <literal>Int#</literal> literal, e.g.
+ any Haskell integer lexeme followed by a <literal>#</literal> is an <literal>Int#</literal> literal, e.g.
<literal>-0x3A#</literal> as well as <literal>32#</literal></para>.</listitem>
<listitem><para> <literal>3##</literal> has type <literal>Word#</literal>. In general,
- any non-negative Haskell 98 integer lexeme followed by <literal>##</literal>
+ any non-negative Haskell integer lexeme followed by <literal>##</literal>
is a <literal>Word#</literal>. </para> </listitem>
<listitem><para> <literal>3.2#</literal> has type <literal>Float#</literal>.</para> </listitem>
<listitem><para> <literal>3.2##</literal> has type <literal>Double#</literal></para> </listitem>
</para>
</sect2>
- <sect2 id="new-qualified-operators">
- <title>New qualified operator syntax</title>
-
- <para>A new syntax for referencing qualified operators is
- planned to be introduced by Haskell', and is enabled in GHC
- with
- the <option>-XNewQualifiedOperators</option><indexterm><primary><option>-XNewQualifiedOperators</option></primary></indexterm>
- option. In the new syntax, the prefix form of a qualified
- operator is
- written <literal><replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)</literal>
- (in Haskell 98 this would
- be <literal>(<replaceable>module</replaceable>.<replaceable>symbol</replaceable>)</literal>),
- and the infix form is
- written <literal>`<replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)`</literal>
- (in Haskell 98 this would
- be <literal>`<replaceable>module</replaceable>.<replaceable>symbol</replaceable>`</literal>.
- For example:
-<programlisting>
- add x y = Prelude.(+) x y
- subtract y = (`Prelude.(-)` y)
-</programlisting>
- The new form of qualified operators is intended to regularise
- the syntax by eliminating odd cases
- like <literal>Prelude..</literal>. For example,
- when <literal>NewQualifiedOperators</literal> is on, it is possible to
- write the enumerated sequence <literal>[Monday..]</literal>
- without spaces, whereas in Haskell 98 this would be a
- reference to the operator ‘<literal>.</literal>‘
- from module <literal>Monday</literal>.</para>
-
- <para>When <option>-XNewQualifiedOperators</option> is on, the old Haskell
- 98 syntax for qualified operators is not accepted, so this
- option may cause existing Haskell 98 code to break.</para>
-
- </sect2>
-
-
<!-- ====================== HIERARCHICAL MODULES ======================= -->
hierarchy. It completely defeats that purpose if the
literal "1" means "<literal>Prelude.fromInteger
1</literal>", which is what the Haskell Report specifies.
- So the <option>-XNoImplicitPrelude</option>
- flag <emphasis>also</emphasis> causes
+ So the <option>-XRebindableSyntax</option>
+ flag causes
the following pieces of built-in syntax to refer to
<emphasis>whatever is in scope</emphasis>, not the Prelude
versions:
</para></listitem>
<listitem>
+ <para>Conditionals (e.g. "<literal>if</literal> e1 <literal>then</literal> e2 <literal>else</literal> e3")
+ means "<literal>ifThenElse</literal> e1 e2 e3". However <literal>case</literal> expressions are unaffected.
+ </para></listitem>
+
+ <listitem>
<para>"Do" notation is translated using whatever
functions <literal>(>>=)</literal>,
<literal>(>>)</literal>, and <literal>fail</literal>,
to use this, ask!
</para></listitem>
</itemizedlist>
+<option>-XRebindableSyntax</option> implies <option>-XNoImplicitPrelude</option>.
+</para>
+<para>
In all cases (apart from arrow notation), the static semantics should be that of the desugared form,
even if that is a little unexpected. For example, the
static semantics of the literal <literal>368</literal>
Nevertheless, they can be useful when defining "phantom types".</para>
</sect2>
+<sect2 id="datatype-contexts">
+<title>Data type contexts</title>
+
+<para>Haskell allows datatypes to be given contexts, e.g.</para>
+
+<programlisting>
+data Eq a => Set a = NilSet | ConsSet a (Set a)
+</programlisting>
+
+<para>give constructors with types:</para>
+
+<programlisting>
+NilSet :: Set a
+ConsSet :: Eq a => a -> Set a -> Set a
+</programlisting>
+
+<para>In GHC this feature is an extension called
+<literal>DatatypeContexts</literal>, and on by default.</para>
+</sect2>
+
<sect2 id="infix-tycons">
<title>Infix type constructors, classes, and type variables</title>
There is one (apparent) exception to this general rule that a bang only
makes a difference when it precedes a variable or wild-card: a bang at the
top level of a <literal>let</literal> or <literal>where</literal>
-binding makes the binding strict, regardless of the pattern. For example:
+binding makes the binding strict, regardless of the pattern.
+(We say "apparent" exception because the Right Way to think of it is that the bang
+at the top of a binding is not part of the <emphasis>pattern</emphasis>; rather it
+is part of the syntax of the <emphasis>binding</emphasis>,
+creating a "bang-pattern binding".)
+For example:
<programlisting>
let ![x,y] = e in b
</programlisting>
-is a strict binding: operationally, it evaluates <literal>e</literal>, matches
-it against the pattern <literal>[x,y]</literal>, and then evaluates <literal>b</literal>.
-(We say "apparent" exception because the Right Way to think of it is that the bang
-at the top of a binding is not part of the <emphasis>pattern</emphasis>; rather it
-is part of the syntax of the <emphasis>binding</emphasis>.)
-Nested bangs in a pattern binding behave uniformly with all other forms of
+is a bang-pattern binding. Operationally, it behaves just like a case expression:
+<programlisting>
+case e of [x,y] -> b
+</programlisting>
+Like a case expression, a bang-pattern binding must be non-recursive, and
+is monomorphic.
+
+However, <emphasis>nested</emphasis> bangs in a pattern binding behave uniformly with all other forms of
pattern matching. For example
<programlisting>
let (!x,[y]) = e in b
</para>
<para>A list of all supported language extensions can be obtained by invoking
- <literal>ghc --supported-languages</literal> (see <xref linkend="modes"/>).</para>
+ <literal>ghc --supported-extensions</literal> (see <xref linkend="modes"/>).</para>
<para>Any extension from the <literal>Extension</literal> type defined in
<ulink
function "<literal>f</literal>" has a number of other effects:
<itemizedlist>
<listitem><para>
-No functions are inlined into <literal>f</literal>. Otherwise
-GHC might inline a big function into <literal>f</literal>'s right hand side,
-making <literal>f</literal> big; and then inline <literal>f</literal> blindly.
+While GHC is keen to inline the function, it does not do so
+blindly. For example, if you write
+<programlisting>
+map key_function xs
+</programlisting>
+there really isn't any point in inlining <literal>key_function</literal> to get
+<programlisting>
+map (\x -> <replaceable>body</replaceable>) xs
+</programlisting>
+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.
</para></listitem>
+
<listitem><para>
-The float-in, float-out, and common-sub-expression transformations are not
-applied to the body of <literal>f</literal>.
+Moreover, GHC will only inline the function if it is <emphasis>fully applied</emphasis>,
+where "fully applied"
+means applied to as many arguments as appear (syntactically)
+on the LHS of the function
+definition. For example:
+<programlisting>
+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)
+</programlisting>
+The two functions <literal>comp1</literal> and <literal>comp2</literal> have the
+same semantics, but <literal>comp1</literal> will be inlined when applied
+to <emphasis>two</emphasis> arguments, while <literal>comp2</literal> requires
+<emphasis>three</emphasis>. This might make a big difference if you say
+<programlisting>
+map (not `comp1` not) xs
+</programlisting>
+which will optimise better than the corresponding use of `comp2`.
+</para></listitem>
+
+<listitem><para>
+It is useful for GHC to optimise the definition of an
+INLINE function <literal>f</literal> just like any other non-INLINE function,
+in case the non-inlined version of <literal>f</literal> is
+ultimately called. But we don't want to inline
+the <emphasis>optimised</emphasis> version
+of <literal>f</literal>;
+a major reason for INLINE pragmas is to expose functions
+in <literal>f</literal>'s RHS that have
+rewrite rules, and it's no good if those functions have been optimised
+away.
+</para>
+<para>
+So <emphasis>GHC guarantees to inline precisely the code that you wrote</emphasis>, 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.
</para></listitem>
<listitem><para>
An INLINE function is not worker/wrappered by strictness analysis.
It's going to be inlined wholesale instead.
</para></listitem>
</itemizedlist>
-All of these effects are aimed at ensuring that what gets inlined is
-exactly what you asked for, no more and no less.
</para>
<para>GHC ensures that inlining cannot go on forever: every mutually-recursive
group is cut by one or more <emphasis>loop breakers</emphasis> that is never inlined
{-# INLINE returnUs #-}
</programlisting>
- <para>See also the <literal>NOINLINE</literal> pragma (<xref
- linkend="noinline-pragma"/>).</para>
+ <para>See also the <literal>NOINLINE</literal> (<xref linkend="inlinable-pragma"/>)
+ and <literal>INLINABLE</literal> (<xref linkend="noinline-pragma"/>)
+ pragmas.</para>
<para>Note: the HBC compiler doesn't like <literal>INLINE</literal> pragmas,
so if you want your code to be HBC-compatible you'll have to surround
</sect3>
+ <sect3 id="inlinable-pragma">
+ <title>INLINABLE pragma</title>
+
+<para>An <literal>{-# INLINABLE f #-}</literal> pragma on a
+function <literal>f</literal> has the following behaviour:
+<itemizedlist>
+<listitem><para>
+While <literal>INLINE</literal> says "please inline me", the <literal>INLINABLE</literal>
+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 <literal>INLINE</literal>, that decision is made at
+the <emphasis>call site</emphasis>, and
+will therefore be affected by the inlining threshold, optimisation level etc.
+</para></listitem>
+<listitem><para>
+Like <literal>INLINE</literal>, the <literal>INLINABLE</literal> 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.
+</para></listitem>
+
+<listitem><para>
+One way to use <literal>INLINABLE</literal> is in conjunction with
+the special function <literal>inline</literal> (<xref linkend="special-ids"/>).
+The call <literal>inline f</literal> tries very hard to inline <literal>f</literal>.
+To make sure that <literal>f</literal> can be inlined,
+it is a good idea to mark the definition
+of <literal>f</literal> as <literal>INLINABLE</literal>,
+so that GHC guarantees to expose an unfolding regardless of how big it is.
+Moreover, by annotating <literal>f</literal> as <literal>INLINABLE</literal>,
+you ensure that <literal>f</literal>'s original RHS is inlined, rather than
+whatever random optimised version of <literal>f</literal> GHC's optimiser
+has produced.
+</para></listitem>
+
+<listitem><para>
+The <literal>INLINABLE</literal> pragma also works with <literal>SPECIALISE</literal>:
+if you mark function <literal>f</literal> as <literal>INLINABLE</literal>, then
+you can subsequently <literal>SPECIALISE</literal> in another module
+(see <xref linkend="specialize-pragma"/>).</para></listitem>
+
+<listitem><para>
+Unlike <literal>INLINE</literal>, it is OK to use
+an <literal>INLINABLE</literal> pragma on a recursive function.
+The principal reason do to so to allow later use of <literal>SPECIALISE</literal>
+</para></listitem>
+</itemizedlist>
+</para>
+
+ </sect3>
+
<sect3 id="noinline-pragma">
<title>NOINLINE pragma</title>
well. If you use this kind of specialisation, let us know how well it works.
</para>
+ <sect3 id="specialize-inline">
+ <title>SPECIALIZE INLINE</title>
+
<para>A <literal>SPECIALIZE</literal> pragma can optionally be followed with a
<literal>INLINE</literal> or <literal>NOINLINE</literal> pragma, optionally
followed by a phase, as described in <xref linkend="inline-noinline-pragma"/>.
unrolling of the indexing function.</para>
<para>Warning: you can make GHC diverge by using <literal>SPECIALISE INLINE</literal>
on an ordinarily-recursive function.</para>
+</sect3>
+
+<sect3><title>SPECIALIZE for imported functions</title>
+
+<para>
+Generally, you can only give a <literal>SPECIALIZE</literal> pragma
+for a function defined in the same module.
+However if a function <literal>f</literal> is given an <literal>INLINABLE</literal>
+pragma at its definition site, then it can subequently be specialised by
+importing modules (see <xref linkend="inlinable-pragma"/>).
+For example
+<programlisting>
+module Map( lookup, blah blah ) where
+ lookup :: Ord key => [(key,a)] -> key -> Maybe a
+ lookup = ...
+ {-# INLINABLE lookup #-}
+
+module Client where
+ import Map( lookup )
+
+ data T = T1 | T2 deriving( Eq, Ord )
+ {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a
+</programlisting>
+Here, <literal>lookup</literal> is declared <literal>INLINABLE</literal>, but
+it cannot be specialised for type <literal>T</literal> at its definition site,
+because that type does not exist yet. Instead a client module can define <literal>T</literal>
+and then specialise <literal>lookup</literal> at that type.
+</para>
+<para>
+Moreover, every module that imports <literal>Client</literal> (or imports a module
+that imports <literal>Client</literal>, transitively) will "see", and make use of,
+the specialised version of <literal>lookup</literal>. You don't need to put
+a <literal>SPECIALIZE</literal> pragma in every module.
+</para>
+<para>
+Moreover you often don't even need the <literal>SPECIALIZE</literal> pragma in the
+first place. When compiling a module M,
+GHC's optimiser (with -O) automatically considers each top-level
+overloaded function declared in M, and specialises it
+for the different types at which it is called in M. The optimiser
+<emphasis>also</emphasis> considers each <emphasis>imported</emphasis>
+<literal>INLINABLE</literal> overloaded function, and specialises it
+for the different types at which it is called in M.
+So in our example, it would be enough for <literal>lookup</literal> to
+be called at type <literal>T</literal>:
+<programlisting>
+module Client where
+ import Map( lookup )
+
+ data T = T1 | T2 deriving( Eq, Ord )
+
+ findT1 :: [(T,a)] -> Maybe a
+ findT1 m = lookup m T1 -- A call of lookup at type T
+</programlisting>
+However, sometimes there are no such calls, in which case the
+pragma can be useful.
+</para>
+</sect3>
+
+<sect3><title>Obselete SPECIALIZE syntax</title>
<para>Note: In earlier versions of GHC, it was possible to provide your own
specialised function for a given type:
This feature has been removed, as it is now subsumed by the
<literal>RULES</literal> pragma (see <xref linkend="rule-spec"/>).</para>
+</sect3>
</sect2>
directly in the <function>T</function> constructor. The
unpacker can see through newtypes, too.</para>
- <para>If a field cannot be unpacked, you will not get a warning,
- so it might be an idea to check the generated code with
- <option>-ddump-simpl</option>.</para>
-
<para>See also the <option>-funbox-strict-fields</option> flag,
which essentially has the effect of adding
<literal>{-# UNPACK #-}</literal> to every strict
<para>
Use the debug flag <option>-ddump-simpl-stats</option> to see what rules fired.
If you need more information, then <option>-ddump-rule-firings</option> shows you
-each individual rule firing in detail.
+each individual rule firing and <option>-ddump-rule-rewrites</option> also shows what the code looks like before and after the rewrite.
</para>
<sect2>
<listitem>
<para>
- Use <option>-ddump-rule-firings</option> to see in great detail what rules are being fired.
+ Use <option>-ddump-rule-firings</option> or <option>-ddump-rule-rewrites</option>
+to see in great detail what rules are being fired.
If you add <option>-dppr-debug</option> you get a still more detailed listing.
</para>
</listitem>
<para>GHC has a few built-in functions with special behaviour. These
are now described in the module <ulink
url="&libraryGhcPrimLocation;/GHC-Prim.html"><literal>GHC.Prim</literal></ulink>
-in the library documentation.</para>
+in the library documentation.
+In particular:
+<itemizedlist>
+<listitem><para>
+<ulink url="&libraryGhcPrimLocation;/GHC-Prim.html#v%3Ainline"><literal>inline</literal></ulink>
+allows control over inlining on a per-call-site basis.
+</para></listitem>
+<listitem><para>
+<ulink url="&libraryGhcPrimLocation;/GHC-Prim.html#v%3Alazy"><literal>lazy</literal></ulink>
+restrains the strictness analyser.
+</para></listitem>
+<listitem><para>
+<ulink url="&libraryGhcPrimLocation;/GHC-Prim.html#v%3AunsafeCoerce%23"><literal>lazy</literal></ulink>
+allows you to fool the type checker.
+</para></listitem>
+</itemizedlist>
+</para>
</sect1>
<!-- Emacs stuff:
;;; Local Variables: ***
- ;;; mode: xml ***
;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
;;; ispell-local-dictionary: "british" ***
;;; End: ***
projects / ghc-hetmet.git / blobdiff