From 96f7d7818558a8bb3744bb52d589f8b9a9e1c7d5 Mon Sep 17 00:00:00 2001
From: "simonpj@microsoft.com" <unknown>
Date: Fri, 30 May 2008 13:33:07 +0000
Subject: [PATCH] Improve documentation for INLINE pragma

---
 docs/users_guide/glasgow_exts.xml |   25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 656d2db..8b6ec73 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -6220,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
@@ -6253,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>
@@ -6265,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">
-- 
1.7.10.4