Added comments and asserts.

Author: preshing

common/autoresetevent.h

@@ -41,7 +41,7 @@ class AutoResetEvent
             if (m_status.compare_exchange_weak(oldStatus, newStatus, std::memory_order_release, std::memory_order_relaxed))
                 break;
             // The compare-exchange failed, likely because another thread changed m_status.
-            // oldStatus now has its latest value (passed by reference). Retry the CAS loop.
+            // oldStatus has been updated. Retry the CAS loop.
         }
         if (oldStatus < 0)
             m_sema.signal();    // Release one waiting thread.

common/bitfield.h

@@ -55,7 +55,7 @@ struct BitFieldMember : BitField<T>
 
     void set(T v)
     {
-        assert(v <= Maximum);
+        assert(v <= Maximum);   // v must fit inside the bitfield member
         this->value = (this->value & ~Mask) | (v << Offset);
     }
 
@@ -66,7 +66,7 @@ struct BitFieldMember : BitField<T>
 
     void add(T v)
     {
-        assert(get() + v <= Maximum);
+        assert(get() + v <= Maximum);   // result must fit inside the bitfield member
         this->value += v << Offset;
     }
 
@@ -77,7 +77,7 @@ struct BitFieldMember : BitField<T>
 
     void sub(T v)
     {
-        assert(get() >= v);
+        assert(get() >= v);     // result must not underflow
         this->value -= v << Offset;
     }
 
@@ -108,7 +108,11 @@ struct BitFieldArray : BitField<T>
     BitFieldArray() = delete;
 
     T maximum() const { return Maximum; }
-    int offset(int i) const { return BaseOffset + BitsPerItem * i; }
+    int offset(int i) const
+    {
+        assert(i >= 0 && i < NumItems);     // array index must be in range
+        return BaseOffset + BitsPerItem * i;
+    }
     T one(int i) const { return T(1) << offset(i); }
     T mask(int i) const { return Maximum << offset(i); }
     int numItems() const { return NumItems; }
@@ -120,7 +124,7 @@ struct BitFieldArray : BitField<T>
 
     void set(int i, T v)
     {
-        assert(v <= Maximum);
+        assert(v <= Maximum);   // v must fit inside the bitfield member
         this->value = (this->value & ~mask(i)) | (v << offset(i));
     }
 
@@ -131,7 +135,7 @@ struct BitFieldArray : BitField<T>
 
     void add(int i, T v)
     {
-        assert(get(i) + v <= Maximum);
+        assert(get(i) + v <= Maximum);   // result must fit inside the bitfield member
         this->value += v << offset(i);
     }
 
@@ -143,7 +147,7 @@ struct BitFieldArray : BitField<T>
 
     void sub(int i, T v)
     {
-        assert(get(i) >= v);
+        assert(get(i) >= v);    // result must not underflow
         this->value -= v << offset(i);
     }
 

common/diningphilosophers.h

@@ -238,7 +238,7 @@ class LockReducedDiningPhilosophers
             // Sanity check.
             for (int i = 0; i < m_numPhilos; i++)
                 assert(newStatus.philos().get(i) <= IntType(m_numPhilos));
-            // CAS until successful.
+            // CAS until successful. On failure, oldStatus will be updated with the latest value.
             if (m_allStatus.compare_exchange_strong(oldStatus.value, newStatus.value, std::memory_order_relaxed))
                 break;
         }
@@ -273,7 +273,7 @@ class LockReducedDiningPhilosophers
             // Sanity check.
             for (int i = 0; i < m_numPhilos; i++)
                 assert(newStatus.philos().get(i) <= IntType(m_numPhilos));
-            // CAS until successful.
+            // CAS until successful. On failure, oldStatus will be updated with the latest value.
             if (m_allStatus.compare_exchange_strong(oldStatus.value, newStatus.value, std::memory_order_relaxed))
                 break;
         }

common/rwlock.h

@@ -47,6 +47,7 @@ class NonRecursiveRWLock
             {
                 newStatus.readers().add(1);
             }
+            // CAS until successful. On failure, oldStatus will be updated with the latest value.
         }
         while (!m_status.compare_exchange_weak(oldStatus.value, newStatus.value,
                                                std::memory_order_acquire, std::memory_order_relaxed));
@@ -93,6 +94,7 @@ class NonRecursiveRWLock
                 newStatus.waitToRead().set(0);
                 newStatus.readers().set(waitToRead);
             }
+            // CAS until successful. On failure, oldStatus will be updated with the latest value.
         }
         while (!m_status.compare_exchange_weak(oldStatus.value, newStatus.value,
                                                std::memory_order_release, std::memory_order_relaxed));