[commit: ghc] master: Update comments around blackholes (ebfc2fb)

[git at git.haskell.org]

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

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

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

commit ebfc2fb884764eae65df4c5da68d2ad5aaa7b95a
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Tue Jul 7 08:52:53 2015 +0100

    Update comments around blackholes
    
    Test Plan: validate
    
    Reviewers: austin, bgamari
    
    Subscribers: thomie
    
    Differential Revision: https://phabricator.haskell.org/D1047


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

ebfc2fb884764eae65df4c5da68d2ad5aaa7b95a
 rts/StgMiscClosures.cmm | 16 +++++++++-------
 rts/ThreadPaused.c      |  7 ++++---
 rts/sm/Scav.c           |  2 +-
 3 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/rts/StgMiscClosures.cmm b/rts/StgMiscClosures.cmm
index dd25706..e3be2cb 100644
--- a/rts/StgMiscClosures.cmm
+++ b/rts/StgMiscClosures.cmm
@@ -355,17 +355,12 @@ retry:
     }
 }
 
-INFO_TABLE(__stg_EAGER_BLACKHOLE,1,0,BLACKHOLE,"BLACKHOLE","BLACKHOLE")
-    (P_ node)
-{
-    jump ENTRY_LBL(stg_BLACKHOLE) (node);
-}
-
 // CAF_BLACKHOLE is allocated when entering a CAF.  The reason it is
 // distinct from BLACKHOLE is so that we can tell the difference
 // between an update frame on the stack that points to a CAF under
 // evaluation, and one that points to a closure that is under
-// evaluation by another thread (a BLACKHOLE).  See threadPaused().
+// evaluation by another thread (a BLACKHOLE).  see Note [suspend
+// duplicate work] in ThreadPaused.c
 //
 INFO_TABLE(stg_CAF_BLACKHOLE,1,0,BLACKHOLE,"BLACKHOLE","BLACKHOLE")
     (P_ node)
@@ -373,6 +368,13 @@ INFO_TABLE(stg_CAF_BLACKHOLE,1,0,BLACKHOLE,"BLACKHOLE","BLACKHOLE")
     jump ENTRY_LBL(stg_BLACKHOLE) (node);
 }
 
+// EAGER_BLACKHOLE exists for the same reason as CAF_BLACKHOLE (see above).
+INFO_TABLE(__stg_EAGER_BLACKHOLE,1,0,BLACKHOLE,"BLACKHOLE","BLACKHOLE")
+    (P_ node)
+{
+    jump ENTRY_LBL(stg_BLACKHOLE) (node);
+}
+
 INFO_TABLE(stg_BLOCKING_QUEUE_CLEAN,4,0,BLOCKING_QUEUE,"BLOCKING_QUEUE","BLOCKING_QUEUE")
 { foreign "C" barf("BLOCKING_QUEUE_CLEAN object entered!") never returns; }
 
diff --git a/rts/ThreadPaused.c b/rts/ThreadPaused.c
index 15339c4..1f1d0af 100644
--- a/rts/ThreadPaused.c
+++ b/rts/ThreadPaused.c
@@ -211,9 +211,8 @@ threadPaused(Capability *cap, StgTSO *tso)
     maybePerformBlockedException (cap, tso);
     if (tso->what_next == ThreadKilled) { return; }
 
-    // NB. Blackholing is *compulsory*, we must either do lazy
-    // blackholing, or eager blackholing consistently.  See Note
-    // [upd-black-hole] in sm/Scav.c.
+    // NB. Updatable thunks *must* be blackholed, either by eager blackholing or
+    // lazy blackholing.  See Note [upd-black-hole] in sm/Scav.c.
 
     stack_end = tso->stackobj->stack + tso->stackobj->stack_size;
 
@@ -244,6 +243,8 @@ threadPaused(Capability *cap, StgTSO *tso)
 #ifdef THREADED_RTS
         retry:
 #endif
+            // Note [suspend duplicate work]
+            //
             // If the info table is a WHITEHOLE or a BLACKHOLE, then
             // another thread has claimed it (via the SET_INFO()
             // below), or is in the process of doing so.  In that case
diff --git a/rts/sm/Scav.c b/rts/sm/Scav.c
index 781840c..a8f0ab0 100644
--- a/rts/sm/Scav.c
+++ b/rts/sm/Scav.c
@@ -1807,6 +1807,7 @@ scavenge_stack(StgPtr p, StgPtr stack_end)
     switch (info->i.type) {
 
     case UPDATE_FRAME:
+        // Note [upd-black-hole]
         // In SMP, we can get update frames that point to indirections
         // when two threads evaluate the same thunk.  We do attempt to
         // discover this situation in threadPaused(), but it's
@@ -1832,7 +1833,6 @@ scavenge_stack(StgPtr p, StgPtr stack_end)
         // compulsory (otherwise we would have to check for thunks
         // too).
         //
-        // Note [upd-black-hole]
         // One slight hiccup is that the THUNK_SELECTOR machinery can
         // overwrite the updatee with an IND.  In parallel GC, this
         // could even be happening concurrently, so we can't check for