Improve documentation of INLINE, esp its interactions with other transformations

diff --git a/compiler/simplCore/CSE.lhs b/compiler/simplCore/CSE.lhs
index 66d6adc..e0584ad 100644 (file)
--- a/compiler/simplCore/CSE.lhs
+++ b/compiler/simplCore/CSE.lhs
@@ -171,7 +171,7 @@ Not CSE-ing inside INLINE also solves an annoying bug in CSE. Consider
 a worker/wrapper, in which the worker has turned into a single variable:
        $wf = h
        f = \x -> ...$wf...
-Now CSE may transoform to
+Now CSE may transform to
        f = \x -> ...h...
 But the WorkerInfo for f still says $wf, which is now dead!  This won't
 happen now that we don't look inside INLINEs (which wrappers are).

diff --git a/compiler/simplCore/FloatOut.lhs b/compiler/simplCore/FloatOut.lhs
index 2af48bd..7cac08d 100644 (file)
--- a/compiler/simplCore/FloatOut.lhs
+++ b/compiler/simplCore/FloatOut.lhs
@@ -321,7 +321,9 @@ floatExpr lvl (Note InlineMe expr)  -- Other than SCCs
        -- more efficient to test once here than to avoid putting
        -- them into floating_defns (which would mean testing for
        -- inlineCtxt  at every let)
-    (fs, [], Note InlineMe (install floating_defns expr')) }   -- See notes in SetLevels
+    (fs, [], Note InlineMe (install floating_defns expr')) }
+       -- See Note [FloatOut inside INLINE]
+       -- I'm guessing that floating_dens should be empty
 
 floatExpr lvl (Note note expr) -- Other than SCCs
   = case (floatExpr lvl expr)    of { (fs, floating_defns, expr') ->

diff --git a/compiler/simplCore/SetLevels.lhs b/compiler/simplCore/SetLevels.lhs
index 844c6a1..043b036 100644 (file)
--- a/compiler/simplCore/SetLevels.lhs
+++ b/compiler/simplCore/SetLevels.lhs
@@ -126,8 +126,8 @@ allocation becomes static instead of dynamic.  We always start with
 context @Level 0 0@.  
 
 
-InlineCtxt
-~~~~~~~~~~
+Note [FloatOut inside INLINE]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 @InlineCtxt@ very similar to @Level 0 0@, but is used for one purpose:
 to say "don't float anything out of here".  That's exactly what we
 want for the body of an INLINE, where we don't want to float anything

diff --git a/compiler/simplCore/SimplUtils.lhs b/compiler/simplCore/SimplUtils.lhs
index 9bc7826..9d0aa07 100644 (file)
--- a/compiler/simplCore/SimplUtils.lhs
+++ b/compiler/simplCore/SimplUtils.lhs
@@ -591,7 +591,7 @@ y's occurrence info, which breaks the invariant.  It matters: y
 might have a BIG rhs, which will now be dup'd at every occurrenc of x.
 
 
-Evne RHSs labelled InlineMe aren't caught here, because there might be
+Even RHSs labelled InlineMe aren't caught here, because there might be
 no benefit from inlining at the call site.
 
 [Sept 01] Don't unconditionally inline a top-level thing, because that

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index f30b9f7..4f02239 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -5858,8 +5858,26 @@ key_function :: Int -> String -> (Bool, Double)
         <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
-        inline it.</para>
-
+        inline it.  However, an <literal>INLINE</literal> pragma for a 
+       function "<literal>f</literal>" has a number of other effects:
+<itemizedlist>
+<listitem><para>
+No funtions 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.
+</para></listitem>
+<listitem><para>
+The float-in, float-out, and common-sub-expression transformations are not 
+applied to the body of <literal>f</literal>.  
+</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>Syntactically, an <literal>INLINE</literal> pragma for a
         function can be put anywhere its type signature could be
         put.</para>