[commit: ghc] master: Add notes describing SRT concepts (80076fa)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/80076fa68f68e337d74c42311f9c3ebebbdc4680/ghc

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

commit 80076fa68f68e337d74c42311f9c3ebebbdc4680
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Wed Nov 2 15:06:31 2016 -0400

    Add notes describing SRT concepts
    
    Test Plan: Read it
    
    Reviewers: austin, erikd, simonmar
    
    Reviewed By: simonmar
    
    Subscribers: thomie
    
    Differential Revision: https://phabricator.haskell.org/D2663


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

80076fa68f68e337d74c42311f9c3ebebbdc4680
 compiler/stgSyn/CoreToStg.hs      | 28 ++++++++++++++++++++++++++++
 includes/rts/storage/InfoTables.h | 13 ++++++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/compiler/stgSyn/CoreToStg.hs b/compiler/stgSyn/CoreToStg.hs
index d130b74..0e33918 100644
--- a/compiler/stgSyn/CoreToStg.hs
+++ b/compiler/stgSyn/CoreToStg.hs
@@ -86,6 +86,34 @@ import Control.Monad (liftM, ap)
 -- live then so is `q'. Furthermore, if `e' mentions an enclosing
 -- let-no-escaped variable, then its free variables are also live if `v' is.
 
+-- Note [What are these SRTs all about?]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--
+-- Consider the Core program,
+--
+--     fibs = go 1 1
+--       where go a b = let c = a + c
+--                      in c : go b c
+--     add x = map (\y -> x*y) fibs
+--
+-- In this case we have a CAF, 'fibs', which is quite large after evaluation and
+-- has only one possible user, 'add'. Consequently, we want to ensure that when
+-- all references to 'add' die we can garbage collect any bit of 'fibs' that we
+-- have evaluated.
+--
+-- However, how do we know whether there are any references to 'fibs' still
+-- around? Afterall, the only reference to it is buried in the code generated
+-- for 'add'. The answer is that we record the CAFs referred to by a definition
+-- in its info table, namely a part of it known as the Static Reference Table
+-- (SRT).
+--
+-- Since SRTs are so common, we use a special compact encoding for them in: we
+-- produce one table containing a list of CAFs in a module and then include a
+-- bitmap in each info table describing which entries of this table the closure
+-- references.
+--
+-- See also: Commentary/Rts/Storage/GC/CAFs on the GHC Wiki.
+
 -- Note [Collecting live CAF info]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 --
diff --git a/includes/rts/storage/InfoTables.h b/includes/rts/storage/InfoTables.h
index fb14ac5..bb1bac0 100644
--- a/includes/rts/storage/InfoTables.h
+++ b/includes/rts/storage/InfoTables.h
@@ -223,10 +223,21 @@ typedef struct StgInfoTable_ {
       them doesn't affect the layout).
 
    -  If srt_bitmap (in the std info table part) is zero, then the srt
-      field may be omitted.  This only applies if the slow_apply and
+      field needn't be set.  This only applies if the slow_apply and
       bitmap fields have also been omitted.
    -------------------------------------------------------------------------- */
 
+/*
+   Note [Encoding static reference tables]
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   As static reference tables appear frequently in code, we use a special
+   compact encoding for the common case of a module defining only a few CAFs: We
+   produce one table containing a list of CAFs in the module and then include a
+   bitmap in each info table describing which entries of this table the closure
+   references.
+ */
+
 typedef struct StgFunInfoExtraRev_ {
     OFFSET_FIELD(slow_apply_offset); /* apply to args on the stack */
     union {