Fix a MSG_BLACKHOLE sanity check, add some comments

Reviewers: simonmar, bgamari, erikd

Reviewed By: simonmar

Subscribers: rwbarton, carter

GHC Trac Issues: #15508

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

includes/rts/storage/Closures.h

@@ -130,10 +130,13 @@ typedef struct {
 
 typedef struct StgBlockingQueue_ {
     StgHeader   header;
-    struct StgBlockingQueue_ *link; // here so it looks like an IND
+    struct StgBlockingQueue_ *link;
+        // here so it looks like an IND, to be able to skip the queue without
+        // deleting it (done in wakeBlockingQueue())
     StgClosure *bh;  // the BLACKHOLE
     StgTSO     *owner;
     struct MessageBlackHole_ *queue;
+        // holds TSOs blocked on `bh`
 } StgBlockingQueue;
 
 typedef struct {
@@ -400,6 +403,8 @@ typedef struct MessageThrowTo_ {
 typedef struct MessageBlackHole_ {
     StgHeader   header;
     struct MessageBlackHole_ *link;
+        // here so it looks like an IND, to be able to skip the message without
+        // deleting it (done in throwToMsg())
     StgTSO     *tso;
     StgClosure *bh;
 } MessageBlackHole;

rts/sm/Sanity.c

@@ -292,8 +292,12 @@ checkClosure( const StgClosure* p )
         ASSERT(LOOKS_LIKE_CLOSURE_PTR(bq->bh));
 
         ASSERT(get_itbl((StgClosure *)(bq->owner))->type == TSO);
-        ASSERT(bq->queue == (MessageBlackHole*)END_TSO_QUEUE
-               || bq->queue->header.info == &stg_MSG_BLACKHOLE_info);
+        ASSERT(// A bq with no other blocked TSOs:
+               bq->queue == (MessageBlackHole*)END_TSO_QUEUE ||
+               // A bq with blocked TSOs in its queue:
+               bq->queue->header.info == &stg_MSG_BLACKHOLE_info ||
+               // A bq with a deleted (in throwToMsg()) MSG_BLACKHOLE:
+               bq->queue->header.info == &stg_IND_info);
         ASSERT(bq->link == (StgBlockingQueue*)END_TSO_QUEUE ||
                get_itbl((StgClosure *)(bq->link))->type == IND ||
                get_itbl((StgClosure *)(bq->link))->type == BLOCKING_QUEUE);