[commit: ghc] master: Add Note [BLACKHOLE points to IND] (cf80995)

[git at git.haskell.org]

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

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

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

commit cf809950efb744ca884e0e0833a80ffd50527ca1
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Sun Mar 25 14:02:16 2018 -0400

    Add Note [BLACKHOLE points to IND]
    
    Test Plan: ci
    
    Reviewers: osa1, bgamari, erikd
    
    Reviewed By: osa1
    
    Subscribers: rwbarton, thomie, carter
    
    Differential Revision: https://phabricator.haskell.org/D4517


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

cf809950efb744ca884e0e0833a80ffd50527ca1
 rts/Messages.c          |  1 +
 rts/StgMiscClosures.cmm |  1 +
 rts/sm/Evac.c           | 13 +++++++++++++
 3 files changed, 15 insertions(+)

diff --git a/rts/Messages.c b/rts/Messages.c
index a9c794d..2b13b63 100644
--- a/rts/Messages.c
+++ b/rts/Messages.c
@@ -203,6 +203,7 @@ loop:
         // just been replaced with an IND by another thread in
         // updateThunk().  In which case, if we read the indirectee
         // again we should get the value.
+        // See Note [BLACKHOLE pointing to IND] in sm/Evac.c
         goto loop;
     }
 
diff --git a/rts/StgMiscClosures.cmm b/rts/StgMiscClosures.cmm
index 595d3ce..9fd5fb8 100644
--- a/rts/StgMiscClosures.cmm
+++ b/rts/StgMiscClosures.cmm
@@ -302,6 +302,7 @@ retry:
         // This could happen, if e.g. we got a BLOCKING_QUEUE that has
         // just been replaced with an IND by another thread in
         // wakeBlockingQueue().
+        // See Note [BLACKHOLE pointing to IND] in sm/Evac.c
         goto retry;
     }
 
diff --git a/rts/sm/Evac.c b/rts/sm/Evac.c
index 27f2806..06648c3 100644
--- a/rts/sm/Evac.c
+++ b/rts/sm/Evac.c
@@ -747,6 +747,19 @@ loop:
               copy(p,info,q,sizeofW(StgInd),gen_no);
               return;
           }
+          // Note [BLACKHOLE pointing to IND]
+          //
+          // BLOCKING_QUEUE can be overwritten by IND (see
+          // wakeBlockingQueue()). However, when this happens we must
+          // be updating the BLACKHOLE, so the BLACKHOLE's indirectee
+          // should now point to the value.
+          //
+          // The mutator might observe an inconsistent state, because
+          // the writes are happening in another thread, so it's
+          // possible for the mutator to follow an indirectee and find
+          // an IND. But this should never happen in the GC, because
+          // the mutators are all stopped and the writes have
+          // completed.
           ASSERT(i != &stg_IND_info);
       }
       q = r;