- /// 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).