<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>
<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 ======================= -->
<sect3 id="inlinable-pragma">
<title>INLINABLE pragma</title>
-<para>An INLINABLE pragma works very like an INLINE pragma, except that:
+<para>An <literal>{-# INLINABLE f #-}</literal> pragma on a
+function <literal>f</literal> has the following behaviour:
<itemizedlist>
<listitem><para>
-INLINE says "please inline me", but INLINABLE says "feel free to inline me; use your
+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 INLINE, That decision is made at
+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 INLINE, the INLINABLE pragma retains a copy of the original RHS for
+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>
-If you use the special function <literal>inline</literal> (<xref linkend="special-ids"/>)
-to force inlining at a
-call site, you will get a copy of the the original RHS.
-Indeed, if you intend to use <literal>inline f</literal> it
-is a good idea to mark the definition of <literal>f</literal> INLINABLE,
+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>
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>
<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>
projects / ghc-hetmet.git / blobdiff