From b16d3a25b7bec6fa4877822d9abf8b0fe008c5f0 Mon Sep 17 00:00:00 2001 From: Eli Pozniansky Date: Fri, 23 Sep 2016 13:08:23 -0700 Subject: [PATCH] Improve documentation of MPMCQueue size and sizeGuess methods Summary: See title. Reviewed By: nbronson Differential Revision: D3914188 fbshipit-source-id: dd9ccd0c48911632d229ae675cc40d835ea14724 --- folly/MPMCQueue.h | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) 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> : 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> : 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(); } -- 2.34.1