Documentation improvements.

include/disruptorplus/blocking_wait_strategy.hpp

@@ -72,7 +72,14 @@ namespace disruptorplus
             }
             return result;
         }
-        
+
+        // Wait until all of the specified sequences have at least
+        // published the specified sequence value.
+        // Timeout if specified timeoutTime has passed.
+        // Returns the highest sequence that all sequences have
+        // published if did not time out.
+        // If timed out then returns some number such that
+        // difference(result, sequence) < 0.
         template<typename Clock, typename Duration>
         sequence_t wait_until_published(
             sequence_t sequence,
@@ -94,7 +101,8 @@ namespace disruptorplus
             }
             return result;
         }
-        
+
+        // Signal any waiting threads that one of the sequences has changed.
         void signal_all_when_blocking()
         {
             // Take out a lock here because we don't want to notify other threads

include/disruptorplus/ring_buffer.hpp

@@ -8,6 +8,16 @@
 
 namespace disruptorplus
 {
+    // A ring buffer is a buffer of size power-of-two that can
+    // be indexed using a sequence number.
+    //
+    // A given slot, i, in the ring buffer is addressed by any sequence
+    // number that has the form n * size() + i for some n.
+    //
+    // A ring buffer is typically used in conjunction with a claim-strategy
+    // for writers to claim a slot in the ring buffer, and one or more
+    // sequence-barriers for readers to indicate where in the ring buffer
+    // they have processed up to.
     template<typename T>
     class ring_buffer
     {

include/disruptorplus/single_threaded_claim_strategy.hpp

@@ -67,6 +67,8 @@ namespace disruptorplus
         // The caller may write to the returned slot and once finished
         // must call publish() passing the returned sequence number to
         // make it available for readers.
+        //
+        // This operation has 'acquire' memory semantics.
         sequence_t claim_one()
         {
             return claim(1).first();

include/disruptorplus/spin_wait_strategy.hpp

@@ -10,10 +10,15 @@
 
 namespace disruptorplus
 {
+    // This wait strategy uses busy-waits to wait for sequences to be
+    // published.
     class spin_wait_strategy
     {
     public:
     
+        // Wait unconditionally until all of the specified sequences
+        // have at least published the specified sequence value.
+        // Returns the value of the least-advanced sequence.
         sequence_t wait_until_published(
             sequence_t sequence,
             size_t count,
@@ -29,7 +34,14 @@ namespace disruptorplus
             }
             return result;
         }
-        
+
+        // Wait until all of the specified sequences have at least
+        // published the specified sequence value.
+        // Timeout if waited longer than specified duration.
+        // Returns the highest sequence that all sequences have
+        // published if did not time out.
+        // If timed out then returns some number such that
+        // difference(result, sequence) < 0.
         template<typename Rep, typename Period>
         sequence_t wait_until_published(
             sequence_t sequence,
@@ -43,7 +55,16 @@ namespace disruptorplus
                 sequences,
                 std::chrono::high_resolution_clock::now() + timeout);
         }
-    
+
+        // Wait until either all of the values in the 'sequences' array are at
+        // least after the specified 'sequence' or until the specified 'timeoutTime'
+        // has passed.
+        //
+        // The 'sequences' array is assumed to have 'count' elements.
+        //
+        // Returns the minimum sequence number from 'sequences'. This will be
+        // prior to the specified 'sequence' if the operation timed out before
+        // the desired sequence number was reached by all sequences.
         template<typename Clock, typename Duration>
         sequence_t wait_until_published(
             sequence_t sequence,
@@ -66,10 +87,13 @@ namespace disruptorplus
             }
             return result;
         }
-        
+
+        // Signal any waiting threads that one of the sequences has changed.
         void signal_all_when_blocking()
         {
-            // No need to signal any threads, they are all busy-waiting.
+            // This is requred as part of the wait_strategy interface but does nothing
+            // for the spin_wait_strategy since all waiting threads are continuously
+            // checking the sequence values in a spin-wait loop.
         }
     
     };