DOC: buffers: clarify the purpose of the <from> pointer in offer_buffers()

This one is only used to compare pointers and NULL is permitted though
this is far from being clear.

diff --git a/include/common/buffer.h b/include/common/buffer.h
index 7ac98bf0d527b539e31a6394cd69a500e906a6d8..1a577ca3dfa91d6496c03c34c553de9a0dd5c0a0 100644 (file)
--- a/include/common/buffer.h
+++ b/include/common/buffer.h
@@ -769,6 +769,13 @@ static inline struct buffer *b_alloc_margin(struct buffer **buf, int margin)
 }
 
 
+/* Offer a buffer currently belonging to target <from> to whoever needs one.
+ * Any pointer is valid for <from>, including NULL. Its purpose is to avoid
+ * passing a buffer to oneself in case of failed allocations (e.g. need two
+ * buffers, get one, fail, release it and wake up self again). In case of
+ * normal buffer release where it is expected that the caller is not waiting
+ * for a buffer, NULL is fine.
+ */
 void __offer_buffer(void *from, unsigned int threshold);
 
 static inline void offer_buffers(void *from, unsigned int threshold)

diff --git a/src/buffer.c b/src/buffer.c
index 167b75ae7dbd62e56e1f57deda2179cc5981338c..79cc133cb6cbdb4382121323c3420b3b20a5d125 100644 (file)
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -247,6 +247,7 @@ void buffer_dump(FILE *o, struct buffer *b, int from, int to)
        fflush(o);
 }
 
+/* see offer_buffer() for details */
 void __offer_buffer(void *from, unsigned int threshold)
 {
        struct buffer_wait *wait, *bak;