Update comments around blackholes

Test Plan: validate

Reviewers: austin, bgamari

Subscribers: thomie

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

3 files changed, 14 insertions, 11 deletions

diff --git a/rts/StgMiscClosures.cmm b/rts/StgMiscClosures.cmm
index dd2570617d..e3be2cb697 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 15339c40c7..1f1d0afe58 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 781840cbae..a8f0ab037f 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