From b662c5d2b887dc6e97d50e9706d17bc6ece75105 Mon Sep 17 00:00:00 2001
From: Willy Tarreau <w@1wt.eu>
Date: Mon, 15 Apr 2024 08:25:03 +0200
Subject: [PATCH] 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.
---
 include/haproxy/ring.h | 12 +++++++++++-
 src/ring.c             |  5 +++--
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/include/haproxy/ring.h b/include/haproxy/ring.h
index 7fb9bc6b8..f8c3a52b6 100644
--- 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 cc0e3a79d..16b8a4b02 100644
--- 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)
 {