DOC/MINOR: list: fixing MT_LIST_LOCK_ELT macro documentation

MT_LIST_LOCK_ELT macro was documented with an ambiguous
usage restriction, implying that concurrent list deletion
was not supported.

But it seems that either the code has evolved, or the comment is
wrong because the locking behavior implemented here is exactly
the same one used in MT_LIST_DELETE, and no such restriction is
described for MT_LIST_DELETE.

I made some tests to make sure concurrent MT_LIST_DELETE (or deletion
from mt_list_for_each_entry_safe) don't cause unexepected results.

At the present time, this macro is not used, this fix only
targets upcoming developments that might rely on this.

No backport needed.

diff --git a/include/haproxy/list.h b/include/haproxy/list.h
index 332098349b074bbb342833ff311a27ebfea6cb18..bc741d27e58b9e22918e59d48bec2e215986a8e4 100644 (file)
--- a/include/haproxy/list.h
+++ b/include/haproxy/list.h
@@ -604,10 +604,12 @@
  */
 #define MT_LIST_INLIST(el) ((el)->next != (el))
 
-/* Lock an element in the list, to be sure it won't be removed.
- * It needs to be synchronized somehow to be sure it's not removed
- * from the list in the meanwhile.
+/* Lock an element in the list, to be sure it won't be removed nor
+ * accessed by another thread while the lock is held.
+ * Locking behavior is inspired from MT_LIST_DELETE macro,
+ * thus this macro can safely be used concurrently with MT_LIST_DELETE.
  * This returns a struct mt_list, that will be needed at unlock time.
+ * (using MT_LIST_UNLOCK_ELT)
  */
 #define MT_LIST_LOCK_ELT(_el)                                              \
        ({                                                                 \