Improve documentation for INLINE pragma

[ghc-hetmet.git] / docs / users_guide / glasgow_exts.xml

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index f6ca80e..8b6ec73 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -323,11 +323,11 @@ became out of date, and wrong information is worse than none.</para>
 
 <para>The Real Truth about what primitive types there are, and what operations
 work over those types, is held in the file
-<filename>fptools/ghc/compiler/prelude/primops.txt.pp</filename>.
+<filename>compiler/prelude/primops.txt.pp</filename>.
 This file is used directly to generate GHC's primitive-operation definitions, so
 it is always correct!  It is also intended for processing into text.</para>
 
-<para> Indeed,
+<para>Indeed,
 the result of such processing is part of the description of the 
  <ulink
       url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">External
@@ -366,6 +366,20 @@ would use in C: <literal>Int&num;</literal> (long int),
 know and love&mdash;usually one instruction.
 </para>
 
+<para> For some primitive types we have special syntax for literals.
+Anything that would be an integer lexeme followed by a
+<literal>&num;</literal> is an <literal>Int&num;</literal> literal, e.g.
+<literal>32&num;</literal> and <literal>-0x3A&num;</literal>. Likewise,
+any non-negative integer literal followed by
+<literal>&num;&num;</literal> is a <literal>Word&num;</literal> literal.
+Likewise, any floating point literal followed by a
+<literal>&num;</literal> is a <literal>Float&num;</literal> literal, and
+followed by <literal>&num;&num;</literal> is a
+<literal>Double&num;</literal>. Finally, a string literal followed by a
+<literal>&num;</literal>, e.g. <literal>&quot;foo&quot;&num;</literal>,
+is a <literal>Addr&num;</literal> literal.
+</para>
+
 <para>
 Primitive (unboxed) types cannot be defined in Haskell, and are
 therefore built into the language and compiler.  Primitive types are
@@ -6206,16 +6220,9 @@ Assertion failures can be caught, see the documentation for the
 
 <programlisting>
 key_function :: Int -> String -> (Bool, Double)
-
-#ifdef __GLASGOW_HASKELL__
 {-# INLINE key_function #-}
-#endif
 </programlisting>
 
-       <para>(You don't need to do the C pre-processor carry-on
-        unless you're going to stick the code through HBC&mdash;it
-        doesn't like <literal>INLINE</literal> pragmas.)</para>
-
         <para>The major effect of an <literal>INLINE</literal> pragma
         is to declare a function's &ldquo;cost&rdquo; to be very low.
         The normal unfolding machinery will then be very keen to
@@ -6239,6 +6246,16 @@ 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.
 </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
+(see <ulink url="http://research.microsoft.com/%7Esimonpj/Papers/inlining/index.htm">
+Secrets of the GHC inliner, JFP 12(4) July 2002</ulink>).
+GHC tries not to select a function with an INLINE pragma as a loop breaker, but
+when there is no choice even an INLINE function can be selected, in which case
+the INLINE pragma is ignored.
+For example, for a self-recursive function, the loop breaker can only be the function
+itself, so an INLINE pragma is always ignored.</para>
+
        <para>Syntactically, an <literal>INLINE</literal> pragma for a
         function can be put anywhere its type signature could be
         put.</para>
@@ -6251,14 +6268,18 @@ exactly what you asked for, no more and no less.
         <literal>UniqueSupply</literal> monad code, we have:</para>
 
 <programlisting>
-#ifdef __GLASGOW_HASKELL__
 {-# INLINE thenUs #-}
 {-# INLINE returnUs #-}
-#endif
 </programlisting>
 
        <para>See also the <literal>NOINLINE</literal> pragma (<xref
         linkend="noinline-pragma"/>).</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
+         the pragma with C pre-processor directives 
+         <literal>#ifdef __GLASGOW_HASKELL__</literal>...<literal>#endif</literal>.</para>
+
       </sect3>
 
       <sect3 id="noinline-pragma">
@@ -6767,7 +6788,7 @@ infeasible in most interesting cases.  The responsibility is entirely the progra
 terminating.  For example:
 
 <programlisting>
-  "loop"        forall x,y.  f x y = f y x
+  "loop"        forall x y.  f x y = f y x
 </programlisting>
 
 This rule will cause the compiler to go into an infinite loop.