MINOR: ring: clarify the usage of ring_size() and add ring_allocated_size()

There's currently an abiguity around ring_size(), it's said to return
the allocated size but returns the usable size. We can't change it as
it's used everywhere in the code like this. Let's fix the comment and
add ring_allocated_size() instead for anything related to allocation.

diff --git a/include/haproxy/ring.h b/include/haproxy/ring.h
index 7fb9bc6b828848d8ae4ef7d0fb9635c0ce0b528d..f8c3a52b634bea479a5ea04ac7bacf1f9222c558 100644 (file)
--- a/include/haproxy/ring.h
+++ b/include/haproxy/ring.h
@@ -60,12 +60,22 @@ static inline size_t ring_data(const struct ring *ring)
                0 : ring->storage->size) + tail - ring->storage->head;
 }
 
-/* returns the allocated size in bytes for the ring */
+/* returns the usable size in bytes for the ring. It is smaller than
+ * the allocate size by the size of the ring_storage header.
+ */
 static inline size_t ring_size(const struct ring *ring)
 {
        return ring->storage->size;
 }
 
+/* returns the allocated size in bytes for the ring. It covers the whole
+ * area made of both the ring_storage and the usable area.
+ */
+static inline size_t ring_allocated_size(const struct ring *ring)
+{
+       return ring->storage->size + ring->storage->rsvd;
+}
+
 /* returns the head offset of the ring */
 static inline size_t ring_head(const struct ring *ring)
 {

diff --git a/src/ring.c b/src/ring.c
index cc0e3a79d886ade9802844def15ce01ef8d49bfb..16b8a4b027febe57be7da5a1bfe83292c3ba3bf8 100644 (file)
--- a/src/ring.c
+++ b/src/ring.c
@@ -104,7 +104,7 @@ struct ring *ring_make_from_area(void *area, size_t size, int reset)
 }
 
 /* Creates and returns a ring buffer of size <size> bytes. Returns NULL on
- * allocation failure.
+ * allocation failure. The size is the area size, not the usable size.
  */
 struct ring *ring_new(size_t size)
 {
@@ -114,7 +114,8 @@ struct ring *ring_new(size_t size)
 /* Resizes existing ring <ring> to <size> which must be larger, without losing
  * its contents. The new size must be at least as large as the previous one or
  * no change will be performed. The pointer to the ring is returned on success,
- * or NULL on allocation failure. This will lock the ring for writes.
+ * or NULL on allocation failure. This will lock the ring for writes. The size
+ * is the allocated area size, and includes the ring_storage header.
  */
 struct ring *ring_resize(struct ring *ring, size_t size)
 {