[commit: ghc] master: Add a comment about how SRTs work (5289958)

[Simon Marlow]

Repository : ssh://darcs.haskell.org//srv/darcs/ghc

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/52899586000d82be1587566d5f74525404e1b07e

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

commit 52899586000d82be1587566d5f74525404e1b07e
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Thu Jul 12 09:12:45 2012 +0100

    Add a comment about how SRTs work

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

 compiler/cmm/CmmBuildInfoTables.hs |   38 ++++++++++++++++++++++++++++++++++++
 1 files changed, 38 insertions(+), 0 deletions(-)

diff --git a/compiler/cmm/CmmBuildInfoTables.hs b/compiler/cmm/CmmBuildInfoTables.hs
index 3d430a4..fb025b5 100644
--- a/compiler/cmm/CmmBuildInfoTables.hs
+++ b/compiler/cmm/CmmBuildInfoTables.hs
@@ -70,6 +70,44 @@ foldSet = Set.foldr
 -- THE CLOSURE AND INLINE THEM INTO ANY SRT THAT MAY MENTION THE CLOSURE.
 -- (I.E. TAKE THE TRANSITIVE CLOSURE, but only for non-static closures).
 
+{- EXAMPLE
+
+f = \x. ... g ...
+  where
+    g = \y. ... h ... c1 ...
+    h = \z. ... c2 ...
+
+c1 & c2 are CAFs
+
+g and h are local functions, but they have no static closures.  When
+we generate code for f, we start with a CmmGroup of four CmmDecls:
+
+   [ f_closure, f_entry, g_entry, h_entry ]
+
+we process each CmmDecl separately in cpsTop, giving us a list of
+CmmDecls. e.g. for f_entry, we might end up with
+
+   [ f_entry, f1_ret, f2_proc ]
+
+where f1_ret is a return point, and f2_proc is a proc-point.  We have
+a CAFSet for each of these CmmDecls, let's suppose they are
+
+   [ f_entry{g_closure}, f1_ret{g_closure}, f2_proc{} ]
+   [ g_entry{h_closure, c1_closure} ]
+   [ h_entry{c2_closure} ]
+
+Now, note that we cannot use g_closure and h_closure in an SRT,
+because there are no static closures corresponding to these functions.
+So we have to flatten out the structure, replacing g_closure and
+h_closure with their contents:
+
+   [ f_entry{c2_closure, c1_closure}, f1_ret{c2_closure,c1_closure}, f2_proc{} ]
+   [ g_entry{c2_closure, c1_closure} ]
+   [ h_entry{c2_closure} ]
+
+This is what mkTopCAFInfo is doing.
+
+-}
 
 -----------------------------------------------------------------------
 -- Finding the CAFs used by a procedure