[commit: ghc] master: documentation and comments for -ffun-to-thunk and -flate-dmd-anal (34728de)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/34728de0f059d8e076981448392203f2501aa120/ghc

>---------------------------------------------------------------

commit 34728de0f059d8e076981448392203f2501aa120
Author: Nicolas Frisby <nicolas.frisby at gmail.com>
Date:   Wed Sep 4 13:25:30 2013 -0500

    documentation and comments for -ffun-to-thunk and -flate-dmd-anal


>---------------------------------------------------------------

34728de0f059d8e076981448392203f2501aa120
 compiler/stranal/WwLib.lhs |    7 +++++--
 docs/users_guide/flags.xml |   28 +++++++++++++++++-----------
 docs/users_guide/using.xml |   25 ++++++++++++++++++-------
 3 files changed, 40 insertions(+), 20 deletions(-)

diff --git a/compiler/stranal/WwLib.lhs b/compiler/stranal/WwLib.lhs
index ca64a7f..2ab4bd9 100644
--- a/compiler/stranal/WwLib.lhs
+++ b/compiler/stranal/WwLib.lhs
@@ -214,8 +214,11 @@ the sharing of E. Since absence analysis and worker-wrapper are keen
 to remove such unused arguments, we add in a void argument to prevent
 the function from becoming a thunk.
 
-The user can avoid that argument with the -ffun-to-thunk
-flag. However, removing all the value argus may introduce space leaks.
+The user can avoid adding the void argument with the -ffun-to-thunk
+flag. However, this can create sharing, which may be bad in two ways. 1) It can
+create a space leak. 2) It can prevent inlining *under a lambda*. If w/w
+removes the last argument from a function f, then f now looks like a thunk, and
+so f can't be inlined *under a lambda*.
 
 Note [All One-Shot Arguments of a Worker]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index ee577e6..1ec1e89 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1586,17 +1586,6 @@
           </row>
 
           <row>
-            <entry><option>-ffun-to-thunk</option></entry>
-            <entry>Worker-wrapper removes unused arguments; this flag
-            lets it thusly remove all value lambdas. Doing so creates
-            a thunk where it was previously a function closure, which
-            may save recomputation but also risks a space leak. Off by
-            default.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-fun-to-thunk</option></entry>
-          </row>
-
-          <row>
             <entry><option>-fdo-eta-reduction</option></entry>
             <entry>Enable eta-reduction. Implied by <option>-O</option>.</entry>
             <entry>dynamic</entry>
@@ -1662,6 +1651,15 @@
           </row>
 
           <row>
+            <entry><option>-ffun-to-thunk</option></entry>
+            <entry>Allow worker-wrapper to convert a function closure into a
+            thunk if the function does not use any of its arguments. Off by
+            default.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-fun-to-thunk</option></entry>
+          </row>
+
+          <row>
             <entry><option>-fignore-asserts</option></entry>
             <entry>Ignore assertions in the source</entry>
             <entry>dynamic</entry>
@@ -1676,6 +1674,14 @@
           </row>
 
           <row>
+            <entry><option>-flate-dmd-anal</option></entry>
+            <entry>Run demand analysis again, at the end of the simplification
+            pipeline</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-late-dmd-anal</option></entry>
+          </row>
+
+          <row>
             <entry><option>-fliberate-case</option></entry>
             <entry>Turn on the liberate-case transformation. Implied by <option>-O2</option>.</entry>
             <entry>dynamic</entry>
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 4440eec..f6db219 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -2095,16 +2095,15 @@ f "2"    = 2
 
         <varlistentry>
           <term>
-            <option>--ffun-to-thunk</option>
+            <option>-ffun-to-thunk</option>
             <indexterm><primary><option>-fignore-asserts</option></primary></indexterm>
           </term>
           <listitem>
-            <para>Worker-wrapper removes unused arguments, but usually we 
-            do not remove them all, lest it turn a function closure into a thunk,
-            thereby perhaps causing extra allocation (since let-no-escape can't happen)
-            and/or a space leak.  This flag
-            allows worker/wrapper to remove <emphasis>all</emphasis> value lambdas.
-            Off by default.
+            <para>Worker-wrapper removes unused arguments, but usually we do
+            not remove them all, lest it turn a function closure into a thunk,
+            thereby perhaps creating a space leak and/or disrupting inlining.
+            This flag allows worker/wrapper to remove <emphasis>all</emphasis>
+            value lambdas.  Off by default.
             </para>
           </listitem>
         </varlistentry>
@@ -2139,6 +2138,18 @@ f "2"    = 2
 
         <varlistentry>
           <term>
+            <option>-flate-dmd-anal</option>
+            <indexterm><primary><option>-flate-dmd-anal</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para><emphasis>Off by default.</emphasis>Run demand analysis
+            again, at the end of the simplification pipeline
+            </para>
+            </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
             <option>-fliberate-case</option>
             <indexterm><primary><option>-fliberate-case</option></primary></indexterm>
           </term>