From: Eli Pozniansky <elip@fb.com>
Date: Fri, 23 Sep 2016 20:08:23 +0000 (-0700)
Subject: Improve documentation of MPMCQueue size and sizeGuess methods
X-Git-Tag: v2016.09.26.00^0
X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=b16d3a25b7bec6fa4877822d9abf8b0fe008c5f0;p=folly.git

Improve documentation of MPMCQueue size and sizeGuess methods

Summary: See title.

Reviewed By: nbronson

Differential Revision: D3914188

fbshipit-source-id: dd9ccd0c48911632d229ae675cc40d835ea14724
---

diff --git a/folly/MPMCQueue.h b/folly/MPMCQueue.h
index 2bf89c53..02a2bf12 100644
--- a/folly/MPMCQueue.h
+++ b/folly/MPMCQueue.h
@@ -696,9 +696,15 @@ class MPMCQueueBase<Derived<T, Atom, Dynamic>> : boost::noncopyable {
     delete[] slots_;
   }
 
-  /// Returns the number of successful reads minus the number of successful
-  /// writes.  Waiting blockingRead and blockingWrite calls are included,
-  /// so this value can be negative.
+  /// Returns the number of writes (including threads that are blocked waiting
+  /// to write) minus the number of reads (including threads that are blocked
+  /// waiting to read). So effectively, it becomes:
+  /// elements in queue + pending(calls to write) - pending(calls to read).
+  /// If nothing is pending, then the method returns the actual number of
+  /// elements in the queue.
+  /// The returned value can be negative if there are no writers and the queue
+  /// is empty, but there is one reader that is blocked waiting to read (in
+  /// which case, the returned size will be -1).
   ssize_t size() const noexcept {
     // since both pushes and pops increase monotonically, we can get a
     // consistent snapshot either by bracketing a read of popTicket_ with
@@ -737,7 +743,11 @@ class MPMCQueueBase<Derived<T, Atom, Dynamic>> : boost::noncopyable {
   }
 
   /// Returns is a guess at size() for contexts that don't need a precise
-  /// value, such as stats.
+  /// value, such as stats. More specifically, it returns the number of writes
+  /// minus the number of reads, but after reading the number of writes, more
+  /// writers could have came before the number of reads was sampled,
+  /// and this method doesn't protect against such case.
+  /// The returned value can be negative.
   ssize_t sizeGuess() const noexcept {
     return writeCount() - readCount();
   }