From: Willy Tarreau <w@1wt.eu>
Date: Mon, 15 Apr 2024 06:25:03 +0000 (+0200)
Subject: MINOR: ring: clarify the usage of ring_size() and add ring_allocated_size()
X-Git-Tag: v3.0-dev8~55
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=b662c5d2b887dc6e97d50e9706d17bc6ece75105;p=thirdparty%2Fhaproxy.git

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 7fb9bc6b82..f8c3a52b63 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 cc0e3a79d8..16b8a4b027 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)
 {