[commit: ghc] master: Update a few comments regarding CAF lists (c00b6d2)

[git at git.haskell.org]

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

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

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

commit c00b6d200c5c0c37c2936f12f27c5ebc3716a76f
Author: Ömer Sinan Ağacan <omeragacan at gmail.com>
Date:   Fri Mar 30 14:58:57 2018 +0300

    Update a few comments regarding CAF lists
    
    [skip ci]


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

c00b6d200c5c0c37c2936f12f27c5ebc3716a76f
 includes/rts/storage/Closures.h |  4 +++-
 rts/sm/GC.c                     |  4 ++--
 rts/sm/Storage.c                | 10 +++++-----
 3 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/includes/rts/storage/Closures.h b/includes/rts/storage/Closures.h
index af89507..e5b274d 100644
--- a/includes/rts/storage/Closures.h
+++ b/includes/rts/storage/Closures.h
@@ -122,8 +122,10 @@ typedef struct {
 typedef struct {
     StgHeader     header;
     StgClosure   *indirectee;
-    StgClosure   *static_link;
+    StgClosure   *static_link; // See Note [CAF lists]
     const StgInfoTable *saved_info;
+        // `saved_info` also used for the link field for `debug_caf_list`,
+        // see `newCAF` and Note [CAF lists]
 } StgIndStatic;
 
 typedef struct StgBlockingQueue_ {
diff --git a/rts/sm/GC.c b/rts/sm/GC.c
index d7d3723..9e6bd55 100644
--- a/rts/sm/GC.c
+++ b/rts/sm/GC.c
@@ -1831,8 +1831,8 @@ resize_nursery (void)
    Sanity code for CAF garbage collection.
 
    With DEBUG turned on, we manage a CAF list in addition to the SRT
-   mechanism.  After GC, we run down the CAF list and blackhole any
-   CAFs which have been garbage collected.  This means we get an error
+   mechanism.  After GC, we run down the CAF list and make any
+   CAFs which have been garbage collected GCD_CAF.  This means we get an error
    whenever the program tries to enter a garbage collected CAF.
 
    Any garbage collected CAFs are taken off the CAF list at the same
diff --git a/rts/sm/Storage.c b/rts/sm/Storage.c
index c4dbdc2..9174646 100644
--- a/rts/sm/Storage.c
+++ b/rts/sm/Storage.c
@@ -303,10 +303,10 @@ freeStorage (bool free_heap)
 
    The entry code for every CAF does the following:
 
-      - calls newCaf, which builds a CAF_BLACKHOLE on the heap and atomically
+      - 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
+      - if newCAF returns zero, it re-enters the CAF (see Note [atomic
         CAF entry])
 
       - pushes an update frame pointing to the CAF_BLACKHOLE
@@ -317,7 +317,7 @@ freeStorage (bool free_heap)
    too, and various other parts of the RTS that deal with update
    frames would also need special cases for static update frames.
 
-   newCaf() does the following:
+   newCAF() does the following:
 
       - atomically locks the CAF (see [atomic CAF entry])
 
@@ -335,7 +335,7 @@ freeStorage (bool free_heap)
    ------------------
    Note [atomic CAF entry]
 
-   With THREADED_RTS, newCaf() is required to be atomic (see
+   With THREADED_RTS, newCAF() is required to be atomic (see
    #5558). This is because if two threads happened to enter the same
    CAF simultaneously, they would create two distinct CAF_BLACKHOLEs,
    and so the normal threadPaused() machinery for detecting duplicate
@@ -355,7 +355,7 @@ freeStorage (bool free_heap)
       - we must be able to *revert* CAFs that have been evaluated, to
         their pre-evaluated form.
 
-      To do this, we use an additional CAF list.  When newCaf() is
+      To do this, we use an additional CAF list.  When newCAF() is
       called on a dynamically-loaded CAF, we add it to the CAF list
       instead of the old-generation mutable list, and save away its
       old info pointer (in caf->saved_info) for later reversion.