From c8072f7b36603a68b56fb22ffb1d0a98ae87cdb0 Mon Sep 17 00:00:00 2001
From: Simon Marlow <marlowsd@gmail.com>
Date: Fri, 6 Feb 2009 13:06:09 +0000
Subject: [PATCH] add debugging code and comments

---
 rts/parallel/WSDeque.c |   17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/rts/parallel/WSDeque.c b/rts/parallel/WSDeque.c
index ec34a8c..e7fd58a 100644
--- a/rts/parallel/WSDeque.c
+++ b/rts/parallel/WSDeque.c
@@ -30,7 +30,11 @@
  * are synchronised without a lock, based on a cas of the top
  * position. One reader wins, the others return NULL for a failure.
  * 
- * Both popBottom and steal also return NULL when the queue is empty.
+ * Both popWSDeque and stealWSDeque also return NULL when the queue is empty.
+ *
+ * Testing: see testsuite/tests/ghc-regress/rts/testwsdeque.c.  If
+ * there's anything wrong with the deque implementation, this test
+ * will probably catch it.
  * 
  * ---------------------------------------------------------------------------*/
 
@@ -140,6 +144,7 @@ popWSDeque (WSDeque *q)
     }
     removed = *pos;
     if (currSize > 0) { /* no danger, still elements in buffer after b-- */
+        // debugBelch("popWSDeque: t=%ld b=%ld = %ld\n", t, b, removed);
         return removed;
     } 
     /* otherwise, has someone meanwhile stolen the same (last) element?
@@ -153,6 +158,8 @@ popWSDeque (WSDeque *q)
     ASSERT_WSDEQUE_INVARIANTS(q); 
     ASSERT(q->bottom >= q->top);
     
+    // debugBelch("popWSDeque: t=%ld b=%ld = %ld\n", t, b, removed);
+
     return removed;
 }
 
@@ -176,7 +183,8 @@ stealWSDeque_ (WSDeque *q)
     t = q->top;
     
     // NB. b and t are unsigned; we need a signed value for the test
-    // below.
+    // below, because it is possible that t > b during a
+    // concurrent popWSQueue() operation.
     if ((long)b - (long)t <= 0 ) { 
         return NULL; /* already looks empty, abort */
   }
@@ -193,6 +201,8 @@ stealWSDeque_ (WSDeque *q)
         return NULL;
     }  /* else: OK, top has been incremented by the cas call */
 
+    // debugBelch("stealWSDeque_: t=%d b=%d\n", t, b);
+
 // Can't do this on someone else's spark pool:
 // ASSERT_WSDEQUE_INVARIANTS(q); 
     
@@ -211,6 +221,9 @@ stealWSDeque (WSDeque *q)
     return stolen;
 }
 
+/* -----------------------------------------------------------------------------
+ * pushWSQueue
+ * -------------------------------------------------------------------------- */
 
 #define DISCARD_NEW
 
-- 
1.7.10.4