[commit: ghc] master: Update and deduplicate the comments on CAF management (#8590) (fe68ad5)

[git at git.haskell.org]

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

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

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

commit fe68ad50f3fa7d73df691f9fd9decd17a72b8b46
Author: Patrick Palka <patrick at parcs.ath.cx>
Date:   Wed Dec 4 10:38:47 2013 -0500

    Update and deduplicate the comments on CAF management (#8590)


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

fe68ad50f3fa7d73df691f9fd9decd17a72b8b46
 compiler/codeGen/StgCmmBind.hs |   35 ++++-------------------------------
 rts/sm/Storage.c               |   14 +++++++++-----
 2 files changed, 13 insertions(+), 36 deletions(-)

diff --git a/compiler/codeGen/StgCmmBind.hs b/compiler/codeGen/StgCmmBind.hs
index 05aae0a..2336792 100644
--- a/compiler/codeGen/StgCmmBind.hs
+++ b/compiler/codeGen/StgCmmBind.hs
@@ -695,44 +695,17 @@ emitUpdateFrame dflags frame lbl updatee = do
 -----------------------------------------------------------------------------
 -- Entering a CAF
 --
--- When a CAF is first entered, it creates a black hole in the heap,
--- and updates itself with an indirection to this new black hole.
---
--- We update the CAF with an indirection to a newly-allocated black
--- hole in the heap.  We also set the blocking queue on the newly
--- allocated black hole to be empty.
---
--- Why do we make a black hole in the heap when we enter a CAF?
---
---     - for a  generational garbage collector, which needs a fast
---       test for whether an updatee is in an old generation or not
---
---     - for the parallel system, which can implement updates more
---       easily if the updatee is always in the heap. (allegedly).
---
--- When debugging, we maintain a separate CAF list so we can tell when
--- a CAF has been garbage collected.
-
--- newCAF must be called before the itbl ptr is overwritten, since
--- newCAF records the old itbl ptr in order to do CAF reverting
--- (which Hugs needs to do in order that combined mode works right.)
---
+-- See Note [CAF management] in rts/sm/Storage.c
 
 link_caf :: LocalReg           -- pointer to the closure
          -> Bool               -- True <=> updatable, False <=> single-entry
          -> FCode CmmExpr      -- Returns amode for closure to be updated
--- To update a CAF we must allocate a black hole, link the CAF onto the
--- CAF list, then update the CAF to point to the fresh black hole.
 -- This function returns the address of the black hole, so it can be
--- updated with the new value when available.  The reason for all of this
--- is that we only want to update dynamic heap objects, not static ones,
--- so that generational GC is easier.
+-- updated with the new value when available.
 link_caf node _is_upd = do
   { dflags <- getDynFlags
-        -- Call the RTS function newCAF to add the CAF to the CafList
-        -- so that the garbage collector can find them
-        -- This must be done *before* the info table pointer is overwritten,
-        -- because the old info table ptr is needed for reversion
+        -- Call the RTS function newCAF, returning the newly-allocated
+        -- blackhole indirection closure
   ; let newCAF_lbl = mkForeignLabel (fsLit "newCAF") Nothing
                                     ForeignLabelInExternalPackage IsFunction
   ; bh <- newTemp (bWord dflags)
diff --git a/rts/sm/Storage.c b/rts/sm/Storage.c
index 755b3d9..0f28820 100644
--- a/rts/sm/Storage.c
+++ b/rts/sm/Storage.c
@@ -268,14 +268,12 @@ freeStorage (rtsBool free_heap)
 }
 
 /* -----------------------------------------------------------------------------
-   CAF management.
+   Note [CAF management].
 
    The entry code for every CAF does the following:
 
-      - builds a CAF_BLACKHOLE in the heap
-
-      - calls newCaf, which atomically updates the CAF with
-        IND_STATIC pointing to the CAF_BLACKHOLE
+      - calls newCaf, which builds a CAF_BLACKHOLE on the heap and atomically
+        updates the CAF with IND_STATIC pointing to the CAF_BLACKHOLE
 
       - if newCaf returns zero, it re-enters the CAF (see Note [atomic
         CAF entry])
@@ -290,6 +288,10 @@ freeStorage (rtsBool free_heap)
 
    newCaf() does the following:
 
+      - atomically locks the CAF (see [atomic CAF entry])
+
+      - it builds a CAF_BLACKHOLE on the heap
+
       - it updates the CAF with an IND_STATIC pointing to the
         CAF_BLACKHOLE, atomically.
 
@@ -297,6 +299,8 @@ freeStorage (rtsBool free_heap)
         This is so that we treat the CAF as a root when collecting
         younger generations.
 
+      - links the CAF onto the CAF list (see below)
+
    ------------------
    Note [atomic CAF entry]