pw_ring_buffer: Fix some stale comments
Clarify some preconditions for internal functions.
Change-Id: I1aacbda759fccefc38d640068a8e21c7f5b4dd82
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/33520
Reviewed-by: Ewout van Bekkum <ewout@google.com>
Commit-Queue: Prashanth Swaminathan <prashanthsw@google.com>
diff --git a/pw_ring_buffer/prefixed_entry_ring_buffer.cc b/pw_ring_buffer/prefixed_entry_ring_buffer.cc
index 400e7d0..8758240 100644
--- a/pw_ring_buffer/prefixed_entry_ring_buffer.cc
+++ b/pw_ring_buffer/prefixed_entry_ring_buffer.cc
@@ -191,8 +191,11 @@
void PrefixedEntryRingBufferMulti::InternalPopFrontAll() {
// Forcefully pop all readers. Find the slowest reader, which must have
// the highest entry count, then pop all readers that have the same count.
+ //
+ // It is expected that InternalPopFrontAll is called only when there is
+ // something to pop from at least one reader. If no readers exist, or all
+ // readers are caught up, this function will assert.
size_t entry_count = GetSlowestReader().entry_count;
- // If no readers have any entries left to read, return immediately.
PW_DASSERT(entry_count != 0);
// Otherwise, pop the readers that have the largest value.
for (Reader& reader : readers_) {
@@ -208,7 +211,8 @@
// an existing reader). To determine the slowest reader, we consider three
// scenarios:
//
- // In all below cases, R1 is the slowest reader:
+ // In all below cases, WH is the write-head, and R# are readers, with R1
+ // representing the slowest reader.
// [[R1 R2 R3 WH]] => Right-hand writer, slowest reader is left-most reader.
// [[WH R1 R2 R3]] => Left-hand writer, slowest reader is left-most reader.
// [[R3 WH R1 R2]] => Middle-writer, slowest reader is left-most reader after
diff --git a/pw_ring_buffer/public/pw_ring_buffer/prefixed_entry_ring_buffer.h b/pw_ring_buffer/public/pw_ring_buffer/prefixed_entry_ring_buffer.h
index a627690..ee6b393 100644
--- a/pw_ring_buffer/public/pw_ring_buffer/prefixed_entry_ring_buffer.h
+++ b/pw_ring_buffer/public/pw_ring_buffer/prefixed_entry_ring_buffer.h
@@ -271,10 +271,14 @@
// Internal function to pop all of the slowest readers. This function may pop
// multiple readers if multiple are slow.
+ //
+ // Precondition: This function requires that at least one reader is attached
+ // and has at least one entry to pop.
void InternalPopFrontAll();
- // Returns the slowest reader in the list. This function requires that at
- // least one reader is attached.
+ // Returns the slowest reader in the list.
+ //
+ // Precondition: This function requires that at least one reader is attached.
Reader& GetSlowestReader();
// Get info struct with the size of the preamble and data chunk for the next
