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 7ac98bf..1a577ca 100644
--- a/include/common/buffer.h
+++ b/include/common/buffer.h
@@ -769,6 +769,13 @@
}
+/* 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 167b75a..79cc133 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -247,6 +247,7 @@
fflush(o);
}
+/* see offer_buffer() for details */
void __offer_buffer(void *from, unsigned int threshold)
{
struct buffer_wait *wait, *bak;