Add notes describing SRT concepts
authorBen Gamari <bgamari.foss@gmail.com>
Wed, 2 Nov 2016 19:06:31 +0000 (15:06 -0400)
committerBen Gamari <ben@smart-cactus.org>
Wed, 2 Nov 2016 19:42:01 +0000 (15:42 -0400)
Test Plan: Read it

Reviewers: austin, erikd, simonmar

Reviewed By: simonmar

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2663

compiler/stgSyn/CoreToStg.hs
includes/rts/storage/InfoTables.h

index d130b74..0e33918 100644 (file)
@@ -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]
 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 --
index fb14ac5..bb1bac0 100644 (file)
@@ -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 {