<indexterm><primary><option>-fallow-incoherent-instances</option></primary></indexterm>
</term>
<term>
- <option>-fcontext-stack</option>
+ <option>-fcontext-stack=N</option>
<indexterm><primary><option>-fcontext-stack</option></primary></indexterm>
</term>
<listitem>
Nothing -> fail
Just val2 -> val1 + val2
where
- fail = val1 + val2
+ fail = var1 + var2
</programlisting>
<para>
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
</programlisting>
</para>
</listitem>
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 <option>-fcontext-stack</option><emphasis>N</emphasis>.
+with <option>-fcontext-stack=</option><emphasis>N</emphasis>.
</para>
</sect3>
</primary></indexterm>
and <option>-fallow-incoherent-instances</option>
<indexterm><primary>-fallow-incoherent-instances
-</primary></indexterm>, as this section discusses.</para>
+</primary></indexterm>, as this section discusses. Both these
+flags are dynamic flags, and can be set on a per-module basis, using
+an <literal>OPTIONS_GHC</literal> pragma if desired (<xref linkend="source-file-options"/>).</para>
<para>
When GHC tries to resolve, say, the constraint <literal>C Int Bool</literal>,
it tries to match every instance declaration against the
</programlisting>
</sect2>
+
+<sect2>
+<title>Using Template Haskell with Profiling</title>
+<indexterm><primary>profiling</primary><secondary>with Template Haskell</secondary></indexterm>
+<para>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 <emphasis>cannot</emphasis> be loaded and used by a splice
+expression, because profiled object code is only compatible with the
+profiling version of the runtime.</para>
+
+<para>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:</para>
+
+<orderedlist>
+<listitem>
+ <para>Compile the program or library first the normal way, without
+ <option>-prof</option><indexterm><primary><option>-prof</option></primary></indexterm>.</para>
+</listitem>
+<listitem>
+ <para>Then compile it again with <option>-prof</option>, and
+ additionally use <option>-osuf
+ p_o</option><indexterm><primary><option>-osuf</option></primary></indexterm>
+ 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 <option>-osuf</option> flag when
+ building with <option>-prof</option> and Template Haskell is used,
+ GHC will emit an error message. </para>
+</listitem>
+</orderedlist>
+</sect2>
+
</sect1>
<!-- ===================== Arrow notation =================== -->
If you use <option>-dverbose-core2core</option> 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:</para>
-
+ phase number, thus:
<itemizedlist>
<listitem>
- <para>You can say "inline <literal>f</literal> in Phase 2
- and all subsequent phases":
-<programlisting>
- {-# INLINE [2] f #-}
-</programlisting>
- </para>
- </listitem>
-
+ <para>"<literal>INLINE[k] f</literal>" means: do not inline
+ <literal>f</literal>
+ until phase <literal>k</literal>, but from phase
+ <literal>k</literal> onwards be very keen to inline it.
+ </para></listitem>
<listitem>
- <para>You can say "inline <literal>g</literal> in all
- phases up to, but not including, Phase 3":
-<programlisting>
- {-# INLINE [~3] g #-}
-</programlisting>
- </para>
- </listitem>
-
+ <para>"<literal>INLINE[~k] f</literal>" means: be very keen to inline
+ <literal>f</literal>
+ until phase <literal>k</literal>, but from phase
+ <literal>k</literal> onwards do not inline it.
+ </para></listitem>
<listitem>
- <para>If you omit the phase indicator, you mean "inline in
- all phases".</para>
- </listitem>
+ <para>"<literal>NOINLINE[k] f</literal>" means: do not inline
+ <literal>f</literal>
+ until phase <literal>k</literal>, but from phase
+ <literal>k</literal> onwards be willing to inline it (as if
+ there was no pragma).
+ </para></listitem>
+ <listitem>
+ <para>"<literal>INLINE[~k] f</literal>" means: be willing to inline
+ <literal>f</literal>
+ until phase <literal>k</literal>, but from phase
+ <literal>k</literal> onwards do not inline it.
+ </para></listitem>
</itemizedlist>
-
- <para>You can use a phase number on a NOINLINE pragma too:</para>
-
- <itemizedlist>
- <listitem>
- <para>You can say "do not inline <literal>f</literal>
- until Phase 2; in Phase 2 and subsequently behave as if
- there was no pragma at all":
+The same information is summarised here:
<programlisting>
- {-# NOINLINE [2] f #-}
-</programlisting>
- </para>
- </listitem>
+ -- 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
- <listitem>
- <para>You can say "do not inline <literal>g</literal> in
- Phase 3 or any subsequent phase; before that, behave as if
- there was no pragma":
-<programlisting>
- {-# NOINLINE [~3] g #-}
+ {-# INLINE f #-} -- Yes Yes
+ {-# NOINLINE f #-} -- No No
</programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>If you omit the phase indicator, you mean "never
- inline this function".</para>
- </listitem>
- </itemizedlist>
-
- <para>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:
+<itemizedlist>
+<listitem><para>For both INLINE and NOINLINE, the phase number says
+when inlining is allowed at all.</para></listitem>
+<listitem><para>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.
+</para></listitem>
+</itemizedlist>
+</para>
+<para>The same phase-numbering control is available for RULES
(<xref linkend="rewrite-rules"/>).</para>
</sect3>
</sect2>
(in a pragma). GHC applies these rewrite rules wherever it can, provided (a)
the <option>-O</option> flag (<xref linkend="options-optimise"/>) is on,
and (b) the <option>-frules-off</option> flag
-(<xref linkend="options-f"/>) is not specified.
+(<xref linkend="options-f"/>) is not specified, and (c) the
+<option>-fglasgow-exts</option> (<xref linkend="options-language"/>)
+flag is active.
</para>
<para>
</sect1>
+<sect1 id="special-ids">
+<title>Special built-in functions</title>
+<para>GHC has a few built-in funcions with special behaviour,
+described in this section. All are exported by
+<literal>GHC.Exts</literal>.</para>
+
+<sect2> <title>The <literal>inline</literal> function </title>
+<para>
+The <literal>inline</literal> function is somewhat experimental.
+<programlisting>
+ inline :: a -> a
+</programlisting>
+The call <literal>(inline f)</literal> arranges that <literal>f</literal>
+is inlined, regardless of its size. More precisely, the call
+<literal>(inline f)</literal> rewrites to the right-hand side of <literal>f</literal>'s
+definition.
+This allows the programmer to control inlining from
+a particular <emphasis>call site</emphasis>
+rather than the <emphasis>definition site</emphasis> of the function
+(c.f. <literal>INLINE</literal> pragmas <xref linkend="inline-noinline-pragma"/>).
+</para>
+<para>
+This inlining occurs regardless of the argument to the call
+or the size of <literal>f</literal>'s definition; it is unconditional.
+The main caveat is that <literal>f</literal>'s definition must be
+visible to the compiler. That is, <literal>f</literal> must be
+let-bound in the current scope.
+If no inlining takes place, the <literal>inline</literal> function
+expands to the identity function in Phase zero; so its use imposes
+no overhead.</para>
+
+<para> 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 <emphasis>might</emphasis> 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.)
+</para>
+</sect2>
+
+<sect2> <title>The <literal>lazy</literal> function </title>
+<para>
+The <literal>lazy</literal> function restrains strictness analysis a little:
+<programlisting>
+ lazy :: a -> a
+</programlisting>
+The call <literal>(lazy e)</literal> means the same as <literal>e</literal>,
+but <literal>lazy</literal> 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 <literal>lazy</literal> are inlined to be the identity function.
+</para>
+<para>
+This behaviour is occasionally useful when controlling evaluation order.
+Notably, <literal>lazy</literal> is used in the library definition of
+<literal>Control.Parallel.par</literal>:
+<programlisting>
+ par :: a -> b -> b
+ par x y = case (par# x) of { _ -> lazy y }
+</programlisting>
+If <literal>lazy</literal> were not lazy, <literal>par</literal> would
+look strict in <literal>y</literal> which would defeat the whole
+purpose of <literal>par</literal>.
+</para>
+</sect2>
+
+<sect2> <title>The <literal>unsafeCoerce#</literal> function </title>
+<para>
+The function <literal>unsafeCoerce#</literal> allows you to side-step the
+typechecker entirely. It has type
+<programlisting>
+ unsafeCoerce# :: a -> b
+</programlisting>
+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.
+</para>
+</sect2>
+</sect1>
+
+
<sect1 id="generic-classes">
<title>Generic classes</title>
projects / ghc-hetmet.git / blobdiff