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

@@ -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)
 {

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)
 {